数字人 / 智能剪辑 API

用一张照片或一段视频注册一个可复用的数字人形象,再用音频或文字驱动它出片;也可以给现成视频做对口型、把一段视频的动作迁移到人物图上,或用模板做智能剪辑。

鉴权与其它端点完全一致 —— 同一把 sk-gpushare-* Key,四种方式任选(x-api-key / x-goog-api-key header / ?key= query / Authorization: Bearer),详见 鉴权。计费扣账户余额(全部 Key 共享),余额不足返回 402 quota_exceeded。

出片与查询用的是 媒体 API 里那对通用的视频端点,只是换了 model 和请求体字段 —— 下面每种玩法都给了完整示例。

一、形象库#

POST /v1/videos/avatars#

用一张正面照片(或一段人物视频)注册形象。异步:立刻返回一个 pending 记录,轮询到 ready 后才能用来出片。上游通常 5–10 分钟。

{
  "name": "我的主播",
  "source_url": "https://example.com/portrait.jpg",
  "source_kind": "image"
}

响应:

{
  "id": "9f1c…",
  "name": "我的主播",
  "source_kind": "image",
  "status": "pending",
  "error": null,
  "created_at": "2026-07-29T08:12:00+00:00"
}

这个 id 就是你之后要用的形象引用 —— 出片时把它填进 avatar 字段即可,不需要关心底层的形象编号。

GET /v1/videos/avatars/{id}#

轮询创建状态,建议 15–30 秒一次。

{ "id": "9f1c…", "name": "我的主播", "status": "ready", "error": null, "created_at": "…" }

status 三态:pending / ready / failed。失败会自动全额退款(退款以这条记录为凭据,所以 pending 期间不允许删除)。

GET /v1/videos/avatars#

列出本账号的形象(最多 200 条,按创建时间倒序)。

DELETE /v1/videos/avatars/{id}#

删除一个形象。创建中(pending)的形象不能删 —— 等它成功或失败后再删。

GET /v1/videos/avatars/presets#

平台预置形象,免费直接用,不必自己注册:

{ "avatars": [ { "id": "…", "name": "职业女主播" }, … ] }

把 presets 里的 id 直接填进出片请求的 avatar 字段即可。

二、数字人出片(dh-avatar)#

驱动一个已就绪的形象说话。成片长度由驱动音频 / 文案决定,按成片秒数计费。

方式 1:用音频驱动#

{
  "model": "dh-avatar",
  "avatar": "9f1c…",
  "audio_url": "https://example.com/voice.mp3",
  "duration": 32
}

方式 2:用文字 + 音色驱动(一步到位,不用先合成音频)#

{
  "model": "dh-avatar",
  "avatar": "9f1c…",
  "voice": "<音色 id>",
  "text": "大家好,今天给大家介绍……",
  "duration": 30
}

voice 可以是:

• POST /v1/audio/voices 克隆出来的音色 id(你自己的克隆音色),或
• GET /v1/audio/voices 返回的 presets 里的平台预设音色 id。

duration 是必填的,单位秒。它是我们预留费用的依据 —— 填驱动音频的真实时长,或按文案估算(中文口播约 字数 ÷ 3.3 秒)。任务结束后按上游返回的实际成片秒数结算,多预留的部分会自动退回;预留额同时是本次出片的费用上限。

提交与轮询用通用视频端点:

curl https://dianqi.zsopc.com/v1/videos/generations \
  -H "Authorization: Bearer $GPUSHARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"dh-avatar","avatar":"9f1c…","audio_url":"https://example.com/voice.mp3","duration":32}'
# → {"id":"…","status":"queued","model":"dh-avatar","created_at":1753…}

curl https://dianqi.zsopc.com/v1/videos/generations/<id> \
  -H "Authorization: Bearer $GPUSHARE_API_KEY"
# → {"id":"…","status":"succeeded","video_url":"https://…","expires_at":…}

三、对口型(dh-lipsync / -pro / -max)#

给一段现成的人物视频换一条音轨,让口型对上。三个档位画质递增、价格递增。

{
  "model": "dh-lipsync-pro",
  "source_video_url": "https://example.com/source.mp4",
  "audio_url": "https://example.com/new-voice.mp3",
  "duration": 45
}

成片长度跟随驱动音频。源视频和音频都必须是公网可访问的直链。

四、动作迁移(dh-motion)#

把一段动作源视频里的动作,迁移到 1–7 张人物图上。

{
  "model": "dh-motion",
  "source_video_url": "https://example.com/dance.mp4",
  "face_count": 2,
  "resolution": "standard",
  "content": [
    { "type": "image_url", "image_url": { "url": "https://example.com/person1.jpg" } },
    { "type": "image_url", "image_url": { "url": "https://example.com/person2.jpg" } }
  ],
  "duration": 20
}

成片长度跟随动作源视频。

五、智能剪辑(clip-realman / clip-mixcut / clip-news)#

用平台模板把素材剪成成片。必须先取一个模板 id 当 style_id。

第 1 步:取模板#

curl "https://dianqi.zsopc.com/v1/videos/clip-templates?scene=realMan" \
  -H "Authorization: Bearer $GPUSHARE_API_KEY"

scene 可选值:

响应里每个模板带 id、标题、封面,以及两个能力标记:

• has_title —— 该模板有标题图层,可以传标题文案;
• has_persona —— 该模板有人设图层,可以传人设文案。

标记为 false 时对应的输入会被上游忽略,不必传。需要看模板完整结构(画布 / 图层)时用 GET /v1/videos/clip-templates/{id}。

这两个端点免费,结果有服务端缓存,可以放心在客户端每次打开时调用。Key 至少要被允许一个 clip-* 模型才能访问模板目录。

第 2 步:提交剪辑#

{
  "model": "clip-realman",
  "style_id": "<第 1 步拿到的模板 id>",
  "duration": 60
}

其余字段(素材、口播音频、标题 / 人设文案等)随模板而定,参考模板详情里的图层结构。

计价#

按秒计费的 SKU,结算以上游返回的实际成片秒数为准,提交时按 duration 预留、多退。

配套的语音端点(合成 / 克隆)见 媒体 API。

异步与超时约定#

• 形象注册与出片都是异步任务:提交立即返回,之后轮询状态端点。轮询本身免费。
• 出片任务的 video_url 是限时链接,响应里的 expires_at 是过期时间戳 —— 需要长期保存请及时转存。
• 任务失败(上游报错 / 超时过期)自动全额退款,不需要你做任何事。
• 形象记录是退款凭据:pending 期间调 DELETE 会返回 400,请等它进入终态后再删。

常见错误#

错误体形状与其它端点一致,详见 错误码。