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

# Kling Custom Element

> - Kling Custom Element (kling-custom-element) creates reusable subject elements (characters/objects) from reference images or videos
- After successful creation, the returned `element_id` can be referenced in Kling O3 series and Kling V3 Image-to-Video via the `element_list` parameter, enabling consistent character appearance control
- Asynchronous processing mode, use the returned task ID to [query status](/en/api-manual/task-management/get-task-detail)
- Upon task completion, `result_data` will contain the `element_id` for video generation

**Important Notes:**
- This model is used to create reusable subjects (elements), **it does not generate videos**, no prompt / duration / quality / aspect_ratio parameters are needed



## OpenAPI

````yaml en/api-manual/video-series/kling/kling-custom-element.json post /v1/videos/generations
openapi: 3.1.0
info:
  title: kling-custom-element API
  description: >-
    Create reusable subject elements (characters/objects) for consistent
    character appearance in Kling O3 series and Kling V3 Image-to-Video
    generation
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.evolink.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Subject Element Creation
    description: >-
      Create reusable subject elements for consistent character appearance
      control in video generation
paths:
  /v1/videos/generations:
    post:
      tags:
        - Subject Element Creation
      summary: kling-custom-element API
      description: >-
        - Kling Custom Element (kling-custom-element) creates reusable subject
        elements (characters/objects) from reference images or videos

        - After successful creation, the returned `element_id` can be referenced
        in Kling O3 series and Kling V3 Image-to-Video via the `element_list`
        parameter, enabling consistent character appearance control

        - Asynchronous processing mode, use the returned task ID to [query
        status](/en/api-manual/task-management/get-task-detail)

        - Upon task completion, `result_data` will contain the `element_id` for
        video generation


        **Important Notes:**

        - This model is used to create reusable subjects (elements), **it does
        not generate videos**, no prompt / duration / quality / aspect_ratio
        parameters are needed
      operationId: createCustomElement
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomElementRequest'
            examples:
              image_refer:
                summary: Create Subject from Reference Images
                value:
                  model: kling-custom-element
                  model_params:
                    element_name: My Character
                    element_description: >-
                      A young male character with short hair, wearing a white
                      T-shirt
                    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: Create Subject from Reference Video (with Voice)
                value:
                  model: kling-custom-element
                  model_params:
                    element_name: My Character
                    element_description: A female character with long hair, wearing a red dress
                    reference_type: video_refer
                    element_video_list:
                      video_url: https://example.com/reference.mp4
                    element_voice_id: "829826751244537879"
      responses:
        '200':
          description: Subject element creation task submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomElementResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: invalid_request
                  message: Invalid request parameters
                  type: invalid_request_error
        '401':
          description: Unauthenticated, token is invalid or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: unauthorized
                  message: Invalid or expired token
                  type: authentication_error
        '402':
          description: Insufficient quota, top-up required
          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: Access denied
          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: Rate limit exceeded
          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: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal_error
                  message: Internal server error
                  type: api_error
components:
  schemas:
    CustomElementRequest:
      type: object
      required:
        - model
        - model_params
      properties:
        model:
          type: string
          description: Model name
          enum:
            - kling-custom-element
          default: kling-custom-element
          example: kling-custom-element
        model_params:
          type: object
          description: Model parameters
          required:
            - element_name
            - element_description
            - reference_type
          properties:
            element_name:
              type: string
              description: |-
                Subject element name

                **Note:**
                - Maximum `20` characters
              maxLength: 20
              example: My Character
            element_description:
              type: string
              description: >-
                Subject element description, helps the model understand the
                subject's appearance features


                **Note:**

                - Maximum `100` characters
              maxLength: 100
              example: A young male character with short hair, wearing a white T-shirt
            reference_type:
              type: string
              description: |-
                Reference material type

                | Value | Description |
                |---|---|
                | `image_refer` | Create subject using reference images |
                | `video_refer` | Create subject using reference video |
              enum:
                - image_refer
                - video_refer
              example: image_refer
            element_image_list:
              type: object
              description: >-
                Reference image list for creating subject elements. Required
                when `reference_type = image_refer`


                **Note:**

                - It is recommended to use clear, well-lit images with a
                prominent subject

                - `frontal_image` (recommended): Frontal reference image URL

                - `refer_images`: Additional reference image list, each item
                contains an `image_url` field
              properties:
                frontal_image:
                  type: string
                  format: uri
                  description: Frontal reference image URL (recommended)
                refer_images:
                  type: array
                  description: Additional reference image list
                  items:
                    type: object
                    properties:
                      image_url:
                        type: string
                        format: uri
                        description: Reference image 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 video for creating subject elements. Required when
                `reference_type = video_refer`


                **Note:**

                - `video_url`: Reference video URL
              properties:
                video_url:
                  type: string
                  format: uri
                  description: Reference video URL
              required:
                - video_url
              example:
                video_url: https://example.com/reference.mp4
            element_voice_id:
              type: string
              description: >-
                Voice ID to assign to the element. The assigned voice will be
                used when the element speaks in generated videos.


                **Note:**

                - Only supported when `reference_type = video_refer`

                - Not available for `image_refer` (image-based element creation
                does not support voice assignment)

                - See the Voice ID Reference table in the API documentation page
                for all available voice IDs
              example: "829826751244537879"
        callback_url:
          type: string
          description: >-
            HTTPS callback URL for task completion


            **Callback Timing:**

            - Triggered when task is completed, failed, or cancelled

            - Sent after billing confirmation


            **Security Restrictions:**

            - HTTPS protocol only

            - Internal IP addresses are prohibited (127.0.0.1, 10.x.x.x,
            172.16-31.x.x, 192.168.x.x, etc.)

            - URL length must not exceed `2048` characters


            **Callback Mechanism:**

            - Timeout: `10` seconds

            - Maximum `3` retries after failure (at `1`/`2`/`4` seconds after
            failure)

            - Callback response format is consistent with task query API

            - 2xx status code is considered successful, other codes trigger
            retry
          format: uri
          example: https://your-domain.com/webhooks/video-task-completed
    CustomElementResponse:
      type: object
      properties:
        created:
          type: integer
          description: Task creation timestamp
          example: 1757169743
        id:
          type: string
          description: Task ID
          example: task-unified-1757169743-8dxnm6yz
        model:
          type: string
          description: Actual model name used
          example: kling-custom-element
        object:
          type: string
          enum:
            - video.generation.task
          description: Task type
        progress:
          type: integer
          description: Task progress percentage (0-100)
          minimum: 0
          maximum: 100
          example: 0
        status:
          type: string
          description: Task status
          enum:
            - pending
            - processing
            - completed
            - failed
          example: pending
        task_info:
          type: object
          description: Task details
          properties:
            can_cancel:
              type: boolean
              description: Whether the task can be cancelled
              example: true
            estimated_time:
              type: integer
              description: Estimated completion time (seconds)
              minimum: 0
              example: 600
        type:
          type: string
          enum:
            - video
          description: Task output type
          example: video
        usage:
          type: object
          description: Usage and billing information
          properties:
            billing_rule:
              type: string
              description: Billing rule
              enum:
                - per_call
              example: per_call
            credits_reserved:
              type: number
              description: Estimated credits consumed
              minimum: 0
              example: 1
            user_group:
              type: string
              description: User group category
              example: default
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code identifier
            message:
              type: string
              description: Error description message
            type:
              type: string
              description: Error type
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        ## All APIs require Bearer Token authentication ##


        **Get API Key:**


        Visit [API Key Management Page](https://evolink.ai/dashboard/keys) to
        get your API Key


        **Add to request header:**

        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````




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

# Query Task Status

> Query the status, progress, and result information of asynchronous tasks by task ID



## OpenAPI

````yaml en/api-manual/task-management/get-task-detail.json get /v1/tasks/{task_id}
openapi: 3.1.0
info:
  title: Get Task Details API
  description: >-
    Query the status, progress, and result information of asynchronous tasks by
    task ID
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.evolink.ai
    description: Production environment
security:
  - bearerAuth: []
tags:
  - name: Task Management
    description: Asynchronous task management related APIs
paths:
  /v1/tasks/{task_id}:
    get:
      tags:
        - Task Management
      summary: Query Task Status
      description: >-
        Query the status, progress, and result information of asynchronous tasks
        by task ID
      operationId: getTaskDetail
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
          description: >-
            Task ID, ignore {} when querying, append the id from the async task
            response body at the end of the path
          example: task-unified-1756817821-4x3rx6ny
      responses:
        '200':
          description: Task status details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskDetailResponse'
        '400':
          description: Request parameter error, format error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: invalid_task_id
                  message: Invalid task ID format, must start with 'task-unified-'
                  type: invalid_request_error
                  param: task_id
        '401':
          description: Unauthenticated, token invalid or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: unauthorized
                  message: Authentication required
                  type: authentication_error
        '402':
          description: Insufficient quota, recharge required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: quota_exceeded
                  message: Insufficient quota. Please top up your account.
                  type: insufficient_quota
        '403':
          description: No permission to access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: permission_denied
                  message: You don't have permission to access this task
                  type: invalid_request_error
        '404':
          description: Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: task_not_found
                  message: The requested task could not be found
                  type: invalid_request_error
        '429':
          description: Request rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: rate_limit_exceeded
                  message: Rate limit exceeded
                  type: evo_api_error
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal_error
                  message: Failed to retrieve task status
                  type: api_error
components:
  schemas:
    TaskDetailResponse:
      type: object
      properties:
        created:
          type: integer
          description: Task creation timestamp
          example: 1756817821
        id:
          type: string
          description: Task ID
          example: task-unified-1756817821-4x3rx6ny
        model:
          type: string
          description: Model used
          example: gemini-3.1-flash-image-preview
        object:
          type: string
          description: Task type
          enum:
            - image.generation.task
            - video.generation.task
            - audio.generation.task
          example: image.generation.task
        progress:
          type: integer
          minimum: 0
          maximum: 100
          description: Task progress percentage
          example: 100
        results:
          type: array
          items:
            type: string
            format: uri
          description: Task result list (provided when completed)
          example:
            - http://example.com/image.jpg
        status:
          type: string
          description: Task status
          enum:
            - pending
            - processing
            - completed
            - failed
          example: completed
        error:
          type: object
          nullable: true
          description: >-
            Error information when the task fails (only present when status is
            "failed"). Note: error.code here is a string-type business error
            code, different from HTTP status codes. See the Error Codes
            Reference for the complete list.
          properties:
            code:
              type: string
              description: Business error code (string type)
              example: content_policy_violation
            message:
              type: string
              description: User-friendly error description with troubleshooting tips
              example: |-
                Content policy violation.
                Your request was blocked by safety filters.
            type:
              type: string
              description: Error type identifier, always "task_error"
              example: task_error
        task_info:
          type: object
          description: Task detailed information
          properties:
            can_cancel:
              type: boolean
              description: Whether the task can be cancelled
              example: false
        type:
          type: string
          description: Task type
          enum:
            - image
            - video
            - audio
            - text
          example: image
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code (string type)
              example: invalid_task_id
            message:
              type: string
              description: Error description message
              example: Invalid task ID format
            type:
              type: string
              description: Error type
              example: invalid_request_error
            param:
              type: string
              description: Related parameter name
              example: task_id
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        ##All APIs require Bearer Token authentication##


        **Get API Key:**


        Visit [API Key Management Page](https://evolink.ai/dashboard/keys) to
        get your API Key


        **Add to request header:**

        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````