> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 建立 Kling 虛擬人像影片
> 使用 CometAPI 中的 Kling Avatar API，從圖片產生由虛擬人像驅動的影片。使用 POST /kling/v1/videos/avatar/image2video 快速建立 image-to-video 虛擬人像。
使用這個端點，透過一張來源圖片加上一個音訊來源來建立會說話的虛擬人像短片。
## 呼叫前須知
* 提供一張虛擬人像 `image`，可使用公開 URL 或原始 base64 字串
* 使用符合 Kling 像素需求的虛擬人像圖片；過小的縮圖會被生成任務拒絕
* 在 `audio_id` 或 `sound_file` 中只能傳送其中一個
* 第一個請求請盡量保持簡單：一張臉部圖片、一段音訊片段，以及一個可選的簡短 prompt
* 當參照的音訊屬於必須關聯的先前任務時，請包含 `task_id`
* 除非你明確需要更高品質的路徑，否則請從 `mode: std` 開始
## 音訊來源規則
* 當你已透過 Kling TTS 路徑產生語音時，`audio_id` 是最簡單的方式
* 當你已經有自己的 MP3、WAV、M4A 或 AAC 資產時，可使用 `sound_file`
* 文件說明虛擬人像音訊長度需為 2 到 60 秒
## 任務流程
提交圖片與一個音訊來源，然後儲存回傳的 task id。
持續使用 [取得 Kling 任務](./individual-queries)，直到任務進入最終狀態。
如果你需要在供應商交付 URL 失效後仍保留結果，請將最終資產複製到你自己的儲存空間中。
如需完整參數參考，請參閱[官方 Kling Avatar 文件](https://kling.ai/document-api/apiReference/model/avatar)。
## OpenAPI
````yaml api/openapi/video/kling/post-avatar.openapi.json POST /kling/v1/videos/avatar/image2video
openapi: 3.1.0
info:
title: Avatar API
version: 1.0.0
description: >-
Create a Kling avatar video task from one source image plus one audio
source.
servers:
- url: https://api.cometapi.com
security:
- bearerAuth: []
paths:
/kling/v1/videos/avatar/image2video:
post:
summary: Create a Kling avatar task
description: >-
Submit one avatar image and exactly one audio source. Poll the returned
task id through the generic Kling query route.
operationId: avatar
parameters:
- name: Content-Type
in: header
required: false
description: Optional content type header.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- image
- prompt
oneOf:
- required:
- audio_id
- required:
- sound_file
properties:
image:
type: string
description: >-
Avatar image URL or base64 image string. Use an image that
meets Kling pixel requirements; very small thumbnails are
rejected.
prompt:
type: string
description: Prompt describing the desired avatar performance.
audio_id:
type: string
description: Audio id from a prior Kling audio task.
sound_file:
type: string
description: Public audio URL when you provide your own audio.
task_id:
type: string
description: >-
Optional prior task id associated with the referenced audio
asset.
mode:
type: string
description: >-
Generation mode. Use `std` or `pro`; omitted requests use
`std`.
enum:
- std
- pro
default:
image: https://your-image-host/avatar.jpg
prompt: The speaker talks naturally to camera
sound_file: https://your-audio-host/speech.wav
mode: std
examples:
Default:
summary: Avatar image-to-video request
value:
image: https://your-image-host/avatar.jpg
prompt: The speaker talks naturally to camera
sound_file: https://your-audio-host/speech.wav
mode: std
responses:
'200':
description: Task accepted.
content:
application/json:
schema:
type: object
required:
- code
- message
- data
properties:
code:
type: integer
message:
type: string
data:
type: object
required:
- task_id
- task_status
- created_at
- updated_at
properties:
task_id:
type: string
task_status:
type: string
task_info:
type: object
additionalProperties: true
created_at:
type: integer
updated_at:
type: integer
x-codeSamples:
- lang: Shell
label: Default
source: |
curl https://api.cometapi.com/kling/v1/videos/avatar/image2video \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://your-image-host/avatar.jpg",
"prompt": "The speaker talks naturally to camera",
"sound_file": "https://your-audio-host/speech.wav",
"mode": "std"
}'
- lang: Python
label: Default
source: |
import os
import requests
response = requests.post(
"https://api.cometapi.com/kling/v1/videos/avatar/image2video",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
json={
"image": "https://your-image-host/avatar.jpg",
"prompt": "The speaker talks naturally to camera",
"sound_file": "https://your-audio-host/speech.wav",
"mode": "std"
},
)
result = response.json()
print(result.get("code"), result.get("data", {}).get("task_id"))
- lang: JavaScript
label: Default
source: >
const response = await
fetch("https://api.cometapi.com/kling/v1/videos/avatar/image2video",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"image": "https://your-image-host/avatar.jpg",
"prompt": "The speaker talks naturally to camera",
"sound_file": "https://your-audio-host/speech.wav",
"mode": "std"
}),
});
const result = await response.json();
console.log(result.code, result.data?.task_id);
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer token authentication. Use your CometAPI key.
````