GlobalAiOpcGlobalAiOpc
微信微信
登录
Model CenterGlobalAiOpc

数字人视频合成

POST/kyyReactApiServer/v2/model-center/tasks

价格

登录后查看当前账号的价格及可用规格。请使用页面顶部的登录入口。
根据输入素材与语音生成数字人视频，适合口播、讲解等场景。素材类型、可选版本和限制请查看下方请求参数。
提交请求后返回 1 个任务 ID，通过查询接口获取生成结果。

快速开始

  1. 将下方示例中的 <API_KEY> 替换为你的 API 密钥，修改创作内容后提交请求。
  2. 保存响应中的 task_ids，逐个查询，每隔 3–5 秒查询一次即可。
  3. 当 status 为 completed 时，使用返回的文件链接获取作品。

请求地址

http
POST https://zcbservice.aizfw.cn/kyyReactApiServer/v2/model-center/tasks

认证

获取 Key
所有请求都需要 API 密钥。提交时使用以下请求头，将 <API_KEY> 替换为你的密钥。
http
Authorization: Bearer <API_KEY>
Content-Type: application/json

准备输入素材

将素材上传后，填写可直接读取的文件链接；不要填写本机路径或需要登录的分享页面。调用前确认链接能够正常访问，且文件格式符合参数说明。
先使用下方请求示例提交一次任务，保存返回的任务 ID。查询成功后，从完成响应中的视频链接获取生成文件；具体字段名见“完成响应示例”。

时长计费说明

按 audioUrl 中输入音频的实际时长计费，不足一秒向上取整。例如 12.3 秒按 13 秒计费，费用为计费秒数 × 每秒单价。无需额外填写音频或视频时长。
输入文件读取或时长检测失败时不会扣费；生成失败退还该任务费用。生成成功后的文件交付异常保留收费，由平台排查处理。

请求参数

以下参数放在请求体（JSON）中提交。标记“必填”的参数每次都要提供，其余参数按所选创作方式填写。
modelstring必填
填写此模型名称。
取值与限制：digital_human
audioUrlstring必填
驱动口型的音频链接，请填写可直接读取的网络文件地址。
取值与限制：链接不能包含中文字符；支持格式：mp4、mp3、wav、m4a、aar（可带查询参数）
videoUrlstring必填
人物原始视频链接，请填写可直接读取的网络文件地址。
取值与限制：链接不能包含中文字符
sideFaceinteger
侧脸优化：人物侧脸明显时可设为 1；一般场景可省略。
取值与限制：可选值：0；1
tiltedFaceinteger
歪头优化：人物正脸但头部倾斜时可设为 1；一般场景可省略。
取值与限制：可选值：0；1
modelVersioninteger
生成版本，请从当前可选值中选择；未列出的版本不可使用。
取值与限制：可选值：7777777（也可传 "v3"）；666666（也可传 "v3-bigface"）

请求示例

以下最小请求按本页参数规则生成，省略可选项。请将 example 替换为实际内容、YOUR_ 开头的值替换为你可用的对应编号（例如音色 ID），并将 example.com 链接替换为真实素材链接后再提交。
选择创作方式查看请求内容。右侧提供 cURL、Python、JavaScript 完整调用代码；Python 示例需先安装 requests，JavaScript 示例可使用 Node.js 18+。
JSON
{
  "model": "digital_human",
  "audioUrl": "https://example.com/media.mp3",
  "videoUrl": "https://example.com/media.mp4"
}

提交响应

请求成功返回 HTTP 202，表示已开始排队。作品生成需要时间，请继续查询任务。
字段说明
task_ids本次生成的全部任务 ID。请保存并逐个查询，避免遗漏作品。
id第一个任务的 ID。
statusqueued 表示排队中。
error错误信息；无错误时为 null。

查询结果

http
GET https://zcbservice.aizfw.cn/kyyReactApiServer/v2/model-center/tasks/{task_id}
task_idstring必填
将地址中的 {task_id} 替换为提交响应 task_ids 中的一个值，并使用同一个 API 密钥查询。每个任务分别查询，保存并使用全部任务 ID。

任务状态

status含义下一步
queued排队中等待 3–5 秒后再次查询。
processing处理中（生成或文件交付）等待 3–5 秒后再次查询。
completed已完成读取返回的业务字段，使用媒体地址播放或下载。
failed生成失败查看 error 了解原因；退款进度见 refund_status。
delivery_exception作品生成成功，但文件暂时无法获取停止轮询，联系支持处理；不要重复提交。
manual_required任务需要人工核查停止轮询，保留任务 ID 并联系支持；不要重复提交。

完成响应示例

JSON
{
  "id": "mcp_00000000000000000000000000000001",
  "model": "digital_human",
  "object": "video",
  "created": 1792022400,
  "status": "completed",
  "amount": 0.25,
  "billing_status": "deducted",
  "refund_status": "none",
  "computing_power": 0,
  "data_project_id": "示例文本",
  "video_url": "https://storage.example.com/video.bin",
  "error": null
}
示例地址和积分仅作说明。实际费用以账户配置及任务记录为准；只有 completed 状态才可获取生成文件。

返回字段

字段说明
id当前查询的任务 ID。
model使用的模型名称。
object结果类型，例如 audio、video。
created任务创建时间，Unix 时间戳，单位为秒。
status任务状态，completed 表示完成。
amount / billing_status / refund_status该任务消耗的积分、扣费状态和退款状态。
error错误信息；成功时为 null。
error_code发生错误时返回的平台错误代码。
媒体地址字段说明
video_url视频下载地址；完成时返回

结果字段

字段类型必返说明
computing_powerinteger否本次任务消耗的算力
data_project_idstring否任务id
返回的媒体地址均为平台保存后的地址，可直接用于播放或下载。可选文件未交付时不返回对应地址。

费用与常见问题

每个任务单独计费，生成失败后可通过 refund_status 查看退款进度。
  • 提交超时：请先确认原请求是否成功，避免重复生成和扣费；已有任务 ID 时直接查询该任务。
  • 查询暂时失败：稍后使用原任务 ID 重试查询，不需要重新生成。
  • 返回 delivery_exception：生成费用保留，请联系支持恢复文件。