> ## Documentation Index
> Fetch the complete documentation index at: https://evolink.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Kling 커스텀 엘리먼트

> - Kling Custom Element (kling-custom-element)는 참조 이미지 또는 비디오에서 재사용 가능한 주체 요소(캐릭터/오브젝트)를 생성합니다
- 생성 성공 후, 반환된 `element_id`는 Kling O3 시리즈 및 Kling V3 이미지-투-비디오에서 `element_list` 매개변수를 통해 참조할 수 있으며, 캐릭터 외관 일관성 제어를 구현합니다
- 비동기 처리 모드, 반환된 작업 ID를 사용하여 [상태 조회](/ko/api-manual/task-management/get-task-detail)
- 작업 완료 후, `result_data`에 비디오 생성용 `element_id`가 포함됩니다

**중요 사항:**
- 이 모델은 재사용 가능한 주체(요소) 생성에 사용됩니다. **비디오를 생성하지 않습니다**. prompt / duration / quality / aspect_ratio 등의 매개변수가 필요하지 않습니다



## OpenAPI

````yaml ko/api-manual/video-series/kling/kling-custom-element.json POST /v1/videos/generations
openapi: 3.1.0
info:
  title: kling-custom-element API
  description: >-
    Kling O3 시리즈 및 Kling V3 이미지-투-비디오 생성에서 일관된 캐릭터 외관을 위한 재사용 가능한 주체
    요소(캐릭터/오브젝트) 생성
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.evolink.ai
    description: 프로덕션
security:
  - bearerAuth: []
tags:
  - name: 주체 요소 생성
    description: 비디오 생성에서 캐릭터 외관 일관성 제어를 위한 재사용 가능한 주체 요소 생성
paths:
  /v1/videos/generations:
    post:
      tags:
        - 주체 요소 생성
      summary: kling-custom-element API
      description: >-
        - Kling Custom Element (kling-custom-element)는 참조 이미지 또는 비디오에서 재사용 가능한
        주체 요소(캐릭터/오브젝트)를 생성합니다

        - 생성 성공 후, 반환된 `element_id`는 Kling O3 시리즈 및 Kling V3 이미지-투-비디오에서
        `element_list` 매개변수를 통해 참조할 수 있으며, 캐릭터 외관 일관성 제어를 구현합니다

        - 비동기 처리 모드, 반환된 작업 ID를 사용하여 [상태
        조회](/ko/api-manual/task-management/get-task-detail)

        - 작업 완료 후, `result_data`에 비디오 생성용 `element_id`가 포함됩니다


        **중요 사항:**

        - 이 모델은 재사용 가능한 주체(요소) 생성에 사용됩니다. **비디오를 생성하지 않습니다**. prompt / duration
        / quality / aspect_ratio 등의 매개변수가 필요하지 않습니다
      operationId: createCustomElement
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomElementRequest'
            examples:
              image_refer:
                summary: 참조 이미지로 주체 생성
                value:
                  model: kling-custom-element
                  model_params:
                    element_name: 내 캐릭터
                    element_description: 짧은 머리의 젊은 남성 캐릭터, 흰색 티셔츠를 입고 있음
                    reference_type: image_refer
                    element_image_list:
                      frontal_image: https://example.com/front.jpg
                      refer_images:
                        - image_url: https://example.com/side.jpg
              video_refer:
                summary: 참조 비디오로 주체 생성
                value:
                  model: kling-custom-element
                  model_params:
                    element_name: 내 캐릭터
                    element_description: 긴 머리의 여성 캐릭터, 빨간 원피스를 입고 있음
                    reference_type: video_refer
                    element_video_list:
                      video_url: https://example.com/reference.mp4
                    element_voice_id: '829824295735410756'
      responses:
        '200':
          description: 주체 요소 생성 작업이 성공적으로 제출되었습니다
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomElementResponse'
        '400':
          description: 잘못된 요청 매개변수
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: invalid_request
                  message: Invalid request parameters
                  type: invalid_request_error
        '401':
          description: 인증되지 않음, 토큰이 유효하지 않거나 만료됨
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: unauthorized
                  message: Invalid or expired token
                  type: authentication_error
        '402':
          description: 크레딧 부족, 충전이 필요합니다
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: insufficient_quota
                  message: Insufficient quota. Please top up your account.
                  type: insufficient_quota
        '403':
          description: 접근이 거부됨
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: model_access_denied
                  message: 'Token does not have access to model: kling-custom-element'
                  type: invalid_request_error
        '429':
          description: 요청 빈도 제한 초과
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: rate_limit_exceeded
                  message: Too many requests, please try again later
                  type: rate_limit_error
        '500':
          description: 서버 내부 오류
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal_error
                  message: Internal server error
                  type: api_error
        '502':
          description: 업스트림 서비스 오류
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: upstream_error
                  message: Upstream AI service unavailable
                  type: upstream_error
components:
  schemas:
    CustomElementRequest:
      type: object
      required:
        - model
        - model_params
      properties:
        model:
          type: string
          description: 모델 이름
          enum:
            - kling-custom-element
          default: kling-custom-element
          example: kling-custom-element
        model_params:
          type: object
          description: 모델 매개변수
          required:
            - element_name
            - element_description
            - reference_type
          properties:
            element_name:
              type: string
              description: |-
                주체 요소 이름

                **참고:**
                - 최대 `20`자
              maxLength: 20
              example: 내 캐릭터
            element_description:
              type: string
              description: |-
                주체 요소 설명, 모델이 주체의 외관 특징을 이해하는 데 도움을 줍니다

                **참고:**
                - 최대 `100`자
              maxLength: 100
              example: 짧은 머리의 젊은 남성 캐릭터, 흰색 티셔츠를 입고 있음
            reference_type:
              type: string
              description: |-
                참조 소재 유형

                | 값 | 설명 |
                |---|---|
                | `image_refer` | 참조 이미지를 사용하여 주체 생성 |
                | `video_refer` | 참조 비디오를 사용하여 주체 생성 |
              enum:
                - image_refer
                - video_refer
              example: image_refer
            element_image_list:
              type: object
              description: |-
                주체 요소 생성을 위한 참조 이미지 목록. `reference_type = image_refer`일 때 필수

                **참고:**
                - 선명하고, 조명이 충분하며, 주체가 뚜렷한 이미지 사용을 권장
                - 이미지 크기: 너비 및 높이 ≥ `300px`, 가로세로 비율 `1:2.5` ~ `2.5:1` 범위
                - `frontal_image`(권장): 정면 참조 이미지 URL
                - `refer_images`: 추가 참조 이미지 목록, 각 항목에 `image_url` 필드 포함
              properties:
                frontal_image:
                  type: string
                  format: uri
                  description: 정면 참조 이미지 URL (권장), 서버에서 직접 접근 가능해야 하며, 접근 시 직접 다운로드되어야 합니다
                refer_images:
                  type: array
                  description: >-
                    추가 참조 이미지 목록, 이미지 URL은 서버에서 직접 접근 가능해야 하며, 접근 시 직접 다운로드되어야
                    합니다
                  items:
                    type: object
                    properties:
                      image_url:
                        type: string
                        format: uri
                        description: 참조 이미지 URL, 서버에서 직접 접근 가능해야 하며, 접근 시 직접 다운로드되어야 합니다
                    required:
                      - image_url
              example:
                frontal_image: https://example.com/front.jpg
                refer_images:
                  - image_url: https://example.com/side.jpg
            element_video_list:
              type: object
              description: |-
                주체 요소 생성을 위한 참조 비디오. `reference_type = video_refer`일 때 필수

                **참고:**
                - `video_url`: 참조 비디오 URL
              properties:
                video_url:
                  type: string
                  format: uri
                  description: 참조 비디오 URL, 서버에서 직접 접근 가능해야 합니다
              required:
                - video_url
              example:
                video_url: https://example.com/reference.mp4
            element_voice_id:
              type: string
              description: |-
                요소에 할당할 음성 ID입니다. 생성된 비디오에서 요소가 말할 때 이 음성이 사용됩니다

                **참고:**
                - `reference_type = video_refer`일 때만 지원
                - `image_refer`에서는 사용할 수 없음
              example: '829824295735410756'
        callback_url:
          type: string
          description: |-
            작업 완료 시 HTTPS 콜백 URL

            **콜백 시점:**
            - 작업이 완료, 실패 또는 취소될 때 트리거됩니다
            - 과금 확인 후 전송됩니다

            **보안 제한:**
            - HTTPS 프로토콜만 지원
            - 내부 IP 주소 금지 (127.0.0.1, 10.x.x.x, 172.16-31.x.x, 192.168.x.x 등)
            - URL 길이는 `2048`자를 초과할 수 없습니다

            **콜백 메커니즘:**
            - 타임아웃: `10`초
            - 실패 후 최대 `3`회 재시도 (실패 후 `1`/`2`/`4`초)
            - 콜백 응답 형식은 작업 조회 API와 동일
            - 2xx 상태 코드는 성공으로 간주, 그 외 코드는 재시도 트리거
          format: uri
          example: https://your-domain.com/webhooks/video-task-completed
    CustomElementResponse:
      type: object
      properties:
        created:
          type: integer
          description: 작업 생성 타임스탬프
          example: 1757169743
        id:
          type: string
          description: 작업 ID
          example: task-unified-1757169743-8dxnm6yz
        model:
          type: string
          description: 실제 사용된 모델 이름
          example: kling-custom-element
        object:
          type: string
          enum:
            - video.generation.task
          description: 작업 유형
        progress:
          type: integer
          description: 작업 진행률 (0-100)
          minimum: 0
          maximum: 100
          example: 0
        status:
          type: string
          description: 작업 상태
          enum:
            - pending
            - processing
            - completed
            - failed
          example: pending
        task_info:
          type: object
          description: 작업 세부 정보
          properties:
            can_cancel:
              type: boolean
              description: 작업 취소 가능 여부
              example: true
            estimated_time:
              type: integer
              description: 예상 완료 시간 (초)
              minimum: 0
              example: 600
        type:
          type: string
          enum:
            - video
          description: 작업 출력 유형
          example: video
        usage:
          type: object
          description: 사용량 및 과금 정보
          properties:
            billing_rule:
              type: string
              description: 과금 규칙
              enum:
                - per_call
              example: per_call
            credits_reserved:
              type: number
              description: 예상 소비 크레딧
              minimum: 0
              example: 1
            user_group:
              type: string
              description: 사용자 그룹 카테고리
              example: default
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: 오류 코드 식별자
            message:
              type: string
              description: 오류 설명
            type:
              type: string
              description: 오류 유형
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |-
        ## 모든 API는 Bearer Token 인증이 필요합니다 ##

        **API Key 받기:**

        [API Key 관리 페이지](https://evolink.ai/dashboard/keys)를 방문하여 API Key를 받으세요

        **요청 헤더에 추가:**
        ```
        Authorization: Bearer YOUR_API_KEY
        ```

````