> ## Documentation Index > > Fetch the complete documentation index at: https://kling.ai/document-api/llms.txt > Use this file to discover all available pages before exploring further. # Avatar > Source: https://kling.ai/document-api/api/video/avatar > Locale: en > Current Tab: Avatar > Sibling Tabs: Avatar / TTS > This content is optimized for LLMs. In-page tabs are expanded and UI-only controls are omitted. --- ## Create Task ### API Overview - Method: `POST` - Path: `/v1/videos/avatar/image2video` - Auth: `Authorization: Bearer ` - Content-Type: `application/json` ### Headers | Field | Type | Required | Default | Enum | Description | |---|---|---:|---|---|---| | `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format | | `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication | ### Request Body | Field Path | Type | Required | Default | Enum | Description | |---|---|---:|---|---|---| | `image` | string | Yes | - | - | Avatar Reference Image | | `audio_id` | string | No | - | - | Audio ID Generated via TTS API | | `sound_file` | string | No | - | - | Sound File | | `prompt` | string | No | - | - | Positive text prompt | | `mode` | string | No | `std` | `std`, `pro` | Video generation mode | | `watermark_info` | object | No | - | - | Whether to generate watermarked results simultaneously | | `callback_url` | string | No | - | - | The callback notification address for the result of this task. If configured, the server will actively notify when the task status changes | | `external_task_id` | string | No | - | - | Customized Task ID | #### Request Body Field Notes - `image`: Support inputting image Base64 encoding or image URL (ensure accessibility). - `image`: **Base64 Encoding Note:** Please note that when using the Base64 method, all image data parameters must be in Base64 format. Do not include any prefix such as `data:image/png;base64,`; only the raw Base64-encoded string should be provided. **Correct:** ```plaintext iVBORw0KGgoAAAANSUhEUgAAAAUA... ``` **Incorrect:** ```plaintext data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA... ``` - `image`: Supported image formats: .jpg / .jpeg / .png - `image`: Image file size ≤ 10MB, dimensions ≥ 300px, aspect ratio between 1:2.5 ~ 2.5:1 - `audio_id`: Only supports audio generated within the last 30 days, duration between 2-300 seconds - `audio_id`: Either `audio_id` or `sound_file` must be provided (mutually exclusive) - `sound_file`: Supports Base64-encoded audio or accessible audio URL - `sound_file`: Accepted formats: .mp3/.wav/.m4a/.aac, max 5MB, format mismatch or file too large will return error codes and other information - `sound_file`: Duration must be between 2-300 seconds - `sound_file`: Either `audio_id` or `sound_file` must be provided (mutually exclusive) - `sound_file`: System will verify audio content and return error codes if there are problems - `prompt`: Can be used to define avatar actions, emotions, and camera movements - `prompt`: 2500 characters maximum - `mode`: `std`: Standard Mode, cost-effective - `mode`: `pro`: Professional Mode, higher quality video output - `mode`: > Different model versions and video modes have different support ranges. For details, see [Capability Map](https://kling.ai/document-api/guides/capability-map/video) - `watermark_info`: Defined by the enabled parameter, format: ```json "watermark_info": { "enabled": boolean } ``` - `watermark_info`: true: generate watermarked result, false: do not generate - `watermark_info`: Custom watermarks are not currently supported - `callback_url`: For the specific message schema, see [Callback Protocol](https://kling.ai/document-api/api/get-started/callbacks) - `external_task_id`: Will not overwrite system-generated task ID, but can be used for task queries - `external_task_id`: Must be unique within a single user account ### Request Example ```bash curl --request POST \ --url https://api-singapore.klingai.com/v1/videos/avatar/image2video \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/pink_boy.png", "sound_file": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/go-to-world.mp3", "prompt": "While talking, excitedly shaking head, finally reaching out and making a fist, deciding to set off, hopping happily", "mode": "std", "external_task_id": "", "callback_url": "" }' ``` ### Response Example ```json { "code": 0, // Error codes; Specific definitions can be found in "Error Code" "message": "string", // Error information "request_id": "string", // Request ID, generated by the system "data": { "task_id": "string", // Task ID, generated by the system "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed "task_info": { // Task creation parameters "external_task_id": "string" // Customer-defined task ID }, "created_at": 1722769557708, // Task creation time, Unix timestamp, unit ms "updated_at": 1722769557708 // Task update time, Unix timestamp, unit ms } } ``` --- ## Query Task (Single) ### API Overview - Method: `GET` - Path: `/v1/videos/avatar/image2video/{id}` - Auth: `Authorization: Bearer ` - Content-Type: `application/json` ### Headers | Field | Type | Required | Default | Enum | Description | |---|---|---:|---|---|---| | `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format | | `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication | ### Path Params | Field | Type | Required | Default | Enum | Description | |---|---|---:|---|---|---| | `task_id` | string | No | - | - | Task ID for avatar, fill the value directly in the request path | | `external_task_id` | string | No | - | - | Customized Task ID for avatar. Fill the value directly in the request path. Choose either task_id or external_task_id for querying. | ### Request Example ```bash curl --request GET \ --url https://api-singapore.klingai.com/v1/videos/avatar/image2video/{task_id} \ --header 'Authorization: Bearer ' ``` ### Response Example ```json { "code": 0, // Error codes; Specific definitions can be found in "Error Code" "message": "string", // Error information "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems "data": { "task_id": "string", // Task ID, generated by the system "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.) "task_info": { // Task creation parameters "external_task_id": "string" // Customer-defined task ID }, "task_result": { "videos": [ { "id": "string", // Generated video ID; globally unique "url": "string", // URL for generating videos (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.) "watermark_url": "string", // Watermarked video download URL, anti-leech format "duration": "string" // Total video duration, unit: s (seconds) } ] }, "watermark_info": { "enabled": boolean }, "final_unit_deduction": "string", // The deduction units of task "final_balance_deduction": { // Balance deduction information "quota": "string", // Balance deduction discount price "list_price": "string" // Balance deduction list price }, "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms } } ``` --- ## Query Task (List) ### API Overview - Method: `GET` - Path: `/v1/videos/avatar/image2video` - Auth: `Authorization: Bearer ` - Content-Type: `application/json` ### Headers | Field | Type | Required | Default | Enum | Description | |---|---|---:|---|---|---| | `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format | | `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication | ### Query Params | Field | Type | Required | Default | Enum | Description | |---|---|---:|---|---|---| | `pageNum` | int | No | `1` | - | Page number | | `pageSize` | int | No | `30` | - | Number of items per page | #### Query Params Field Notes - `pageNum`: Value range: [1, 1000] - `pageSize`: Value range: [1, 500] ### Request Example ```bash curl --request GET \ --url 'https://api-singapore.klingai.com/v1/videos/avatar/image2video?pageNum=1&pageSize=30' \ --header 'Authorization: Bearer ' ``` ### Response Example ```json { "code": 0, // Error codes; Specific definitions can be found in Error codes "message": "string", // Error information "request_id": "string", // Request ID, generated by the system, to track requests and troubleshoot problems "data": [ { "task_id": "string", // Task ID, generated by the system "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.) "task_info": { // Task creation parameters "external_task_id": "string" // Customer-defined task ID }, "task_result": { "videos": [ { "id": "string", // Generated video ID; globally unique "url": "string", // URL for generating videos (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.) "watermark_url": "string", // Watermarked video download URL, anti-leech format "duration": "string" // Total video duration, unit: s (seconds) } ] }, "watermark_info": { "enabled": boolean }, "final_unit_deduction": "string", // The deduction units of task "final_balance_deduction": { // Balance deduction information "quota": "string", // Balance deduction discount price "list_price": "string" // Balance deduction list price }, "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms } ] } ```