> ## 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 [进行查询](/cn/api-manual/task-management/get-task-detail) - 任务完成后，`result_data` 将包含用于视频生成的 `element_id` **重要说明：** - 本模型用于创建可复用主体（元素），**不生成视频**，无需 prompt / duration / quality / aspect_ratio 等参数 ## OpenAPI ````yaml cn/api-manual/video-series/kling/kling-custom-element.json POST /v1/videos/generations openapi: 3.1.0 info: title: kling-custom-element接口 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接口 description: >- - Kling Custom Element (kling-custom-element) 通过参考图片或视频创建可复用的主体元素（角色/物体） - 创建成功后，返回的 `element_id` 可在 Kling O3 系列和 Kling V3 图生视频中通过 `element_list` 参数引用，实现角色外观一致性控制 - 异步处理模式，使用返回的任务ID [进行查询](/cn/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: 一个短发年轻男性角色，穿着白色T恤 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: 未认证、Token无效或过期 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: 一个短发年轻男性角色，穿着白色T恤 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回调地址 **回调时机：** - 任务完成（completed）、失败（failed）或取消（cancelled）时触发 - 在计费确认完成后发送 **安全限制：** - 仅支持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`秒后进行重试） - 回调响应体格式与任务查询接口返回的格式一致 - 回调地址若返回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: |- ##所有接口均需要使用Bearer Token进行认证## **获取 API Key：** 访问 [API Key 管理页面](https://evolink.ai/dashboard/keys) 获取您的 API Key **使用时在请求头中添加：** ``` Authorization: Bearer YOUR_API_KEY ``` ````