跳到主要内容
MarkdownLLMs.txt

数字人口播

本页示例中的 {BASE_URL} 表示 https://api.uniall.ai。

概览​

可灵数字人统一使用稳定模型 kling-v3，并传入 operation: avatar。请求需要一张公开图片，以及音频 URL 或 UniAll voice_id 二选一；不要再使用历史 Kling Avatar 档位模型名。

UniAll 当前没有开放可灵主体库的创建和查询接口，因此普通公开请求不要传 subject_ids。

适用场景​

  • 已有口播音频时使用 audio_url。
  • 需要使用 UniAll 音色列表或克隆接口返回的音色时使用 voice_id。
  • 标准清晰度使用 resolution: std，更高清晰度使用 resolution: pro。

接口​

操作方法路径
创建数字人视频任务POST/v1/videos
查询视频任务GET/v1/videos/{task_id}
下载已完成的视频GET/v1/videos/{task_id}/content
查询可灵音色GET/v1/audio/voices?model=kling-v3
克隆可灵音色POST/v1/audio/voices/clone

鉴权​

Authorization: Bearer sk-***
Content-Type: application/json

请求参数​

参数类型必填说明
modelstring是使用 kling-v3。
operationstring是使用 avatar。
promptstring是UniAll 视频接口要求提供的讲解、表情和镜头提示词。
imagestring是数字人图片的公开 HTTP(S) URL。
audio_urlstring条件必填公开口播音频 URL，与 voice_id 二选一。
voice_idstring条件必填UniAll 音色 ID，与 audio_url 二选一。
resolutionstring否std 或 pro，默认 std。
watermarkboolean否是否添加 AIGC 水印。

不要传 sound 开关。audio_url 和 voice_id 是口型驱动输入，展示风格由提示词描述；同一个请求不要同时传入两个音色输入。

查询可用音色​

curl "{BASE_URL}/v1/audio/voices?model=kling-v3" \
  -H "Authorization: Bearer sk-***"

使用音色列表响应中的 UniAll voice_id，不要传入上游音色 ID。

克隆音色​

curl -X POST "{BASE_URL}/v1/audio/voices/clone" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "voice_name": "产品旁白",
    "audio_url": "https://example.com/voice-sample.mp3",
    "text": "这是克隆音色的试听文本。"
  }'

克隆成功后保存响应中的 UniAll voice_id，再用于数字人任务。

请求示例​

使用音频 URL​

curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "operation": "avatar",
    "prompt": "自然讲解产品，表情友好，正面稳定镜头。",
    "image": "https://example.com/presenter.png",
    "audio_url": "https://example.com/speech.mp3",
    "resolution": "pro",
    "watermark": false
  }'

使用 UniAll 音色​

curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "operation": "avatar",
    "prompt": "专业讲解口吻，表情自然，正面稳定镜头。",
    "image": "https://example.com/presenter.png",
    "voice_id": "voice_xxxxxxxxxxxxx",
    "resolution": "std"
  }'

响应示例​

{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "kling-v3",
  "status": "queued",
  "progress": 0
}

任务状态与结果​

保存 id 或 task_id，然后按照视频生成概览中的公共规则，每 3 到 10 秒轮询一次，并处理终态、结果字段、错误和带鉴权下载。

计费说明​

数字人视频通常结合 kling-v3、operation: avatar、resolution 和输出时长计费。音色克隆可能按照模型广场当前规则单独计费。任务提交时可能预扣，最终以任务结算和消费记录为准。

常见错误​

  • 使用历史数字人档位模型名，而不是 kling-v3。
  • 缺少 operation: avatar 或必填的 prompt。
  • 同时传入 audio_url 和 voice_id，或两者都没有传。
  • 传入上游音色 ID，而不是 UniAll voice_id。
  • 在公开主体库接口尚未开放时传入 subject_ids。
  • 传入 sound、duration，或媒体 URL 无法由服务端公开访问。
  • 一次轮询超时后重新提交付费任务，而不是继续查询原 task_id。

公共响应不会返回供应商名称、上游任务 ID、路由、凭证或上游原始请求。

相关页面​