地鼠数字人 OpenAPI 接入文档

版本：1.4.0 正式地址：https://gateway.dspirit.cn/v1/digital-human

1. 最短接入流程

客户只需提供三个必填输入：

1. API2 身份验证：CLIENT_ID 和 CLIENT_SECRET，使用 HTTP Basic Auth。
2. image：一张已授权的正面人物图片。
3. audio：一段成品音频。

调用一次 POST /image-audio-videos。平台自动完成令牌申请、素材上传和任务创建，并立即返回 taskId，不会等待视频生成完成：

curl --request POST \
  'https://gateway.dspirit.cn/v1/digital-human/image-audio-videos' \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header 'X-Idempotency-Key: order-20260819-0001' \
  --form 'image=@/absolute/path/avatar.png' \
  --form 'audio=@/absolute/path/narration.wav'

任务受理后返回 HTTP 202：

{
  "ok": true,
  "code": 0,
  "message": "数字人任务已提交",
  "data": {
    "taskId": "dh_task_xxx",
    "operation": "image_avatar_video",
    "status": "processing",
    "billing": {
      "status": "reserved",
      "points": 5
    }
  }
}

响应头中的 Location 是轮询地址，Retry-After 是建议首次轮询等待秒数。也可以直接使用下面的地址轮询，仍然使用相同的 Basic Auth：

curl \
  'https://gateway.dspirit.cn/v1/digital-human/image-audio-videos/dh_task_xxx' \
  --user "${CLIENT_ID}:${CLIENT_SECRET}"

每隔 3-10 秒查询一次。data.status=success 时，从 data.resultUrl 下载 MP4；failed 时停止轮询，预扣积分进入退回流程。

如需回调，在同一个 multipart 请求中增加可选字段：

  --form 'callbackUrl=https://customer.example.com/callback/digital-human' \
  --form 'callbackSecret=客户自定义签名密钥'

任务进入终态后平台会向 callbackUrl 发送 POST 事件。传入 callbackSecret 时，回调包含 X-Dishu-Signature: sha256=<HMAC-SHA256>；轮询接口无论是否配置回调都始终可用。

除此以外不需要传 org_id、user_id、产品头、应用头、素材 URL、mediaId 或底层服务商 Key。X-Idempotency-Key 可省略，由服务端自动生成；同一业务请求重试时建议复用原值，避免重复创建和重复计费。

也可以把已经取得的短期 Token 作为验证值：

curl --request POST \
  'https://gateway.dspirit.cn/v1/digital-human/image-audio-videos' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --form 'image=@/absolute/path/avatar.png' \
  --form 'audio=@/absolute/path/narration.wav'

支持的图片格式：JPG、JPEG、PNG、WebP，最大 20MB。支持的音频格式：MP3、WAV、M4A、AAC、OGG，最大 100MB。

如需复用素材或调用更多高级能力，可继续使用后文的 /media、/image-videos 和 /tasks/{taskId} 流程。

机器可读规范：

• OpenAPI YAML：https://gateway.dspirit.cn/v1/digital-human/openapi.yaml
• OpenAPI JSON：https://gateway.dspirit.cn/v1/digital-human/openapi.json

2. 开通信息

地鼠为每个客户应用分配：

• CLIENT_ID
• CLIENT_SECRET
• SITE_ID，默认 100000
• 权限：digital-human:read、digital-human:write

凭证只能保存在客户服务端，不能写入网页、小程序、桌面安装包或公开仓库。凭证已绑定企业和服务账号，获取令牌时不要额外提交企业或用户 ID。

3. 获取访问令牌

curl --request POST \
  'https://dspirit.cn/authz/oidc/v2/100000/token' \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=ai:invoke digital-human:read digital-human:write'

后续高级接口统一携带：

Authorization: Bearer ACCESS_TOKEN
X-Dishu-Product-Code: ai_avatar
X-Dishu-App-Key: avatar

使用第 1 节的 /image-audio-videos 单接口时不需要手动获取 Token，也不需要传产品头和应用头。

4. 上传一个素材

一个接口接收图片、音频或视频。使用 multipart/form-data，文件字段固定为 file。

上传图片：

curl --request POST \
  'https://gateway.dspirit.cn/v1/digital-human/media' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'X-Dishu-Product-Code: ai_avatar' \
  --header 'X-Dishu-App-Key: avatar' \
  --form 'file=@/absolute/path/avatar.jpg'

上传音频：

curl --request POST \
  'https://gateway.dspirit.cn/v1/digital-human/media' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'X-Dishu-Product-Code: ai_avatar' \
  --header 'X-Dishu-App-Key: avatar' \
  --form 'file=@/absolute/path/narration.mp3'

成功返回 HTTP 201：

{
  "ok": true,
  "code": 0,
  "message": "素材上传成功",
  "data": {
    "mediaId": "dh_media_0123456789abcdef0123456789abcdef",
    "kind": "image",
    "fileName": "avatar.jpg",
    "contentType": "image/jpeg",
    "sizeBytes": 123456,
    "expiresInSeconds": 604800
  }
}

mediaId 只属于当前企业和服务账号，不能跨账号复用。过期后重新上传即可。

5. 创建照片数字人视频

curl --request POST \
  'https://gateway.dspirit.cn/v1/digital-human/image-videos' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'X-Dishu-Product-Code: ai_avatar' \
  --header 'X-Dishu-App-Key: avatar' \
  --header 'X-Idempotency-Key: customer-order-20260813-0001' \
  --header 'Content-Type: application/json' \
  --data '{
    "imageMediaId": "dh_media_IMAGE_ID",
    "audioMediaId": "dh_media_AUDIO_ID",
    "mode": 2,
    "title": "客户形象口播",
    "callbackUrl": "https://customer.example.com/callback/digital-human",
    "callbackSecret": "CUSTOMER_CALLBACK_SECRET"
  }'

callbackUrl 和 callbackSecret 都可省略。创建成功返回 HTTP 202：

{
  "ok": true,
  "code": 0,
  "message": "数字人任务已提交",
  "data": {
    "taskId": "dh_task_xxx",
    "operation": "image_avatar_video",
    "status": "processing",
    "callback": {
      "status": "pending",
      "attempts": 0
    },
    "billing": {
      "status": "reserved",
      "reserved": true,
      "committed": false,
      "refunded": false,
      "points": 5
    }
  }
}

同一个业务订单重试时必须复用原 X-Idempotency-Key，不要创建重复任务。

6. 接收回调

任务进入 success 或 failed 后，平台向 callbackUrl 发送 POST application/json：

{
  "event": "digital_human.task.completed",
  "data": {
    "taskId": "dh_task_xxx",
    "operation": "image_avatar_video",
    "status": "success",
    "resultUrl": "https://.../result.mp4",
    "billing": {
      "status": "committed",
      "committed": true,
      "points": 5
    }
  }
}

回调请求头：

X-Dishu-Event: digital_human.task.completed
X-Dishu-Task-Id: dh_task_xxx
X-Dishu-Signature: sha256=HEX_HMAC_SHA256

当创建任务传入 callbackSecret 时，签名计算方式为：

hex(HMAC-SHA256(callbackSecret, 原始 HTTP 请求体字节))

验签成功后返回任意 2xx。非 2xx 或网络失败会重试，最多 5 次。回调地址必须是公网 HTTPS，不能指向内网、回环或保留地址。不要只凭回调判断计费，必要时用任务查询接口读回确认。

7. 查询任务结果

curl \
  'https://gateway.dspirit.cn/v1/digital-human/tasks/dh_task_xxx' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'X-Dishu-Product-Code: ai_avatar' \
  --header 'X-Dishu-App-Key: avatar'

未使用回调时每隔 3-10 秒查询一次，达到终态后停止：

• success：生成成功，视频位于 data.resultUrl。
• failed：生成失败，预扣积分进入退回流程。
• settlement_pending：生成结果已确定，积分结算正在重试；不要重复创建任务。

data.callback.status 可为 pending、scheduled、delivering、delivered、failed 或 exhausted。回调失败不会把已生成成功的视频任务改成失败。

8. 其他能力

这些是兼容保留的高级接口；本次 mediaId 简化合同用于 /image-videos 照片数字人链路。完整请求结构以 OpenAPI JSON/YAML 为准。

9. 错误处理

{
  "ok": false,
  "code": "DISHU_MEDIA_UNSUPPORTED_TYPE",
  "message": "文件扩展名与实际素材类型不一致。",
  "error": {
    "code": "DISHU_MEDIA_UNSUPPORTED_TYPE",
    "message": "文件扩展名与实际素材类型不一致。"
  },
  "requestId": "req_xxx"
}

排查时提供 requestId、taskId、请求时间和接口路径，不要发送 Client Secret、访问令牌或回调密钥。

10. 上线检查

• Client Secret 与 callbackSecret 只保存在服务端密钥管理系统。
• 所有创建接口使用稳定幂等键。
• 回调先验签，再按 taskId 做幂等消费。
• 回调失败时使用 /tasks/{taskId} 主动查询，不重复创建视频。
• 记录 requestId、taskId、业务单号和计费状态，不记录令牌与原始声音文件。
• 取得人物形象、声音和内容的合法授权。
• 及时转存 resultUrl，并按客户数据保留政策清理素材。