数字人

功能概览

本页用于说明 数字人 的核心能力、调用入口和接入要点，帮助开发者快速判断适用场景并完成集成。

适用场景

• 产品原型验证：快速接入模型能力，验证内容生成、理解或编辑流程。
• 生产业务接入：用于批量任务、自动化工作流和多模型组合调用。
• 能力迁移适配：适合从原有模型或 SDK 平滑切换到亿速API统一接口。

接入建议

• 优先确认模型名称、请求路径和响应字段，再接入具体业务流程。
• 对异步任务、媒体生成和长耗时请求，建议在业务侧加入重试与状态轮询。
• 上线前建议准备日志追踪、错误处理和内容安全校验，便于稳定运行。

接口总览

POST /digitalhuman/uploadDigitalHumanFile
POST /digitalhuman/createHuman
GET  /digitalhuman/getDigitalHumanList
GET  /digitalhuman/getDigitalHumanInfo
POST /digitalhuman/createDigitalHumanTimbre
GET  /digitalhuman/getDigitalHumanTimbreList
GET  /digitalhuman/getDigitalHumanTimbreInfo
POST /digitalhuman/submitDigitalHumanTask
GET  /digitalhuman/queryDigitalHumanTask

所有接口基础地址：

https://api.yisu.com

鉴权

所有接口都需要在请求头中传入 API Key：

Authorization: Bearer <API_KEY>

JSON 请求需要设置：

Content-Type: application/json

文件上传接口使用 multipart/form-data。

推荐接入流程

1. 调用 POST /digitalhuman/uploadDigitalHumanFile 上传图片、视频或音频素材，获得 file_id。
2. 调用 POST /digitalhuman/createHuman，使用图片或视频素材的 file_id 创建数字人形象，获得 human_id。
3. 如需文本驱动，调用 POST /digitalhuman/createDigitalHumanTimbre 创建音色，或使用内置音色。
4. 调用 POST /digitalhuman/submitDigitalHumanTask 创建数字人视频任务，获得 tag_id。
5. 调用 GET /digitalhuman/queryDigitalHumanTask 查询任务状态和结果视频地址。

通用错误格式

{
  "error": {
    "message": "file_id is required",
    "type": "invalid_request_error",
    "param": "file_id",
    "code": null
  }
}

常见 HTTP 状态码：

文件与形象接口

上传数字人相关素材文件

POST /digitalhuman/uploadDigitalHumanFile

上传数字人相关素材文件。上传成功后会返回 file_id，后续创建数字人形象、创建音色时都使用该 file_id。

请求

curl "https://api.yisu.com/digitalhuman/uploadDigitalHumanFile" \
  -H "Authorization: Bearer <API_KEY>" \
  -F "file=@/path/to/input.mp4"

请求参数

响应示例

上传成功后常见响应结构如下：

{
  "code": 200,
  "message": "上传成功",
  "data": {
    "file_id": 1637,
    "file_url": "https://cache.jiuma.com/static/uploads/20260710/example.mp4",
    "file_name": "example.mp4",
    "ext": "mp4",
    "mime": "video/mp4",
    "size": 1234567,
    "duration": 2.04
  }
}

创建数字人形象

POST /digitalhuman/createHuman

使用上传接口返回的 file_id 创建数字人形象。创建成功后返回 human_id，可用于后续形象查询和视频任务创建。

请求

curl "https://api.yisu.com/digitalhuman/createHuman" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": 1637,
    "name": "口播数字人",
    "role_type": 2,
    "gender": 1,
    "age": 28
  }'

请求参数

响应示例

{
  "code": 200,
  "message": "created",
  "data": {
    "id": "44439",
    "human_id": "44439",
    "name": "口播数字人",
    "gender_name": "男",
    "age": 28,
    "belong_type": 2,
    "role_type_name": "真人",
    "file_id": 1637,
    "file_url": "https://cache.jiuma.com/static/uploads/20260710/example.jpg",
    "video_file_id": 0,
    "video_file_url": ""
  }
}

说明

• 创建成功后的 human_id 可用于形象管理；创建视频任务时通过 video_id 传入。

获取当前账号可用的数字人形象列表

GET /digitalhuman/getDigitalHumanList

获取可用的数字人形象列表。

请求

curl "https://api.yisu.com/digitalhuman/getDigitalHumanList?page=1&list_rows=15&belong_type=2" \
  -H "Authorization: Bearer <API_KEY>"

请求参数

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "page": 1,
    "list_rows": 15,
    "total": 1,
    "list": [
      {
        "id": "44439",
        "human_id": "44439",
        "name": "口播数字人",
        "gender_name": "男",
        "age": 28,
        "belong_type": 2,
        "role_type_name": "真人",
        "file_id": 1637,
        "file_url": "https://cache.jiuma.com/static/uploads/20260710/example.jpg",
        "video_file_id": 0,
        "video_file_url": ""
      }
    ]
  }
}

获取数字人形象详情

GET /digitalhuman/getDigitalHumanInfo

获取指定数字人形象详情。

请求

单个形象：

curl "https://api.yisu.com/digitalhuman/getDigitalHumanInfo?human_id=44439" \
  -H "Authorization: Bearer <API_KEY>"

多个形象：

curl "https://api.yisu.com/digitalhuman/getDigitalHumanInfo?human_id=44439,44440" \
  -H "Authorization: Bearer <API_KEY>"

请求参数

单个形象响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "44439",
    "human_id": "44439",
    "name": "口播数字人",
    "gender_name": "男",
    "age": 28,
    "belong_type": 2,
    "role_type_name": "真人",
    "file_id": 1637,
    "file_url": "https://cache.jiuma.com/static/uploads/20260710/example.jpg",
    "video_file_id": 0,
    "video_file_url": ""
  }
}

多个形象响应示例

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "44439",
      "human_id": "44439",
      "name": "口播数字人",
      "gender_name": "男",
      "age": 28,
      "belong_type": 2,
      "role_type_name": "真人",
      "file_id": 1637,
      "file_url": "https://cache.jiuma.com/static/uploads/20260710/example.jpg",
      "video_file_id": 0,
      "video_file_url": ""
    }
  ]
}

音色接口

创建数字人音色

POST /digitalhuman/createDigitalHumanTimbre

创建数字人音色。先通过上传文件接口上传音频文件，再将返回的 file_id 传入本接口。

请求

curl "https://api.yisu.com/digitalhuman/createDigitalHumanTimbre" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": 2010,
    "name": "我的音色",
    "gender": 1,
    "age": 28,
    "belong_type": 2
  }'

请求参数

响应示例

{
  "code": 200,
  "message": "操作成功",
  "data": "2494"
}

data 即音色 ID，创建文本驱动任务时传入 input_reference.audio_config.timbre。

获取数字人音色列表

GET /digitalhuman/getDigitalHumanTimbreList

获取数字人音色列表。

请求

curl "https://api.yisu.com/digitalhuman/getDigitalHumanTimbreList?page=1&list_rows=15&belong_type=1" \
  -H "Authorization: Bearer <API_KEY>"

请求参数

自定义音色响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 1,
    "per_page": 15,
    "current_page": "1",
    "last_page": 1,
    "data": [
      {
        "id": "2494",
        "name": "我的音色",
        "age": 28,
        "belong_type": 2,
        "type": 0,
        "gender": 1,
        "config": "",
        "volume": "0.00",
        "des_label": ""
      }
    ]
  }
}

获取数字人音色详情

GET /digitalhuman/getDigitalHumanTimbreInfo

获取数字人音色详情。

请求

curl "https://api.yisu.com/digitalhuman/getDigitalHumanTimbreInfo?timbre_id=2494" \
  -H "Authorization: Bearer <API_KEY>"

请求参数

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": "2494",
    "name": "我的音色",
    "age": 28,
    "belong_type": 2,
    "type": 0,
    "gender": 1,
    "config": "",
    "volume": "0.00",
    "des_label": ""
  }
}

视频任务接口

创建数字人视频任务

POST /digitalhuman/submitDigitalHumanTask

创建数字人视频任务。该接口是异步任务接口，创建成功后返回 tag_id，需要通过查询接口获取最终视频结果。

engine 为顶层非必填参数，用于选择生成引擎：auto 自动，standard 超拟真，ultra Q版。请不要把 engine 放到 input_reference 或 audio_config 内。

限制说明：当 video_id 对应的数字人形象是图片素材创建的形象时，不能创建超拟真视频任务，engine 不能传 standard。

文本驱动请求

curl "https://api.yisu.com/digitalhuman/submitDigitalHumanTask" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jiuma-digital-human",
    "engine": "standard",
    "input_reference": {
      "video_id": 44439,
      "audio_config": {
        "drive": "text",
        "timbre": 2494,
        "words": "大家早上好，欢迎观看今天的产品介绍。",
        "end_silent": 1
      },
      "callback_url": "https://example.com/callback"
    }
  }'

音频驱动请求

curl "https://api.yisu.com/digitalhuman/submitDigitalHumanTask" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jiuma-digital-human",
    "engine": "ultra",
    "input_reference": {
      "video_id": 44439,
      "audio_config": {
        "drive": "audio",
        "audio_url": "https://example.com/audio.mp3",
        "timbre": 1,
        "duration": 12.5
      }
    }
  }'

请求参数

创建成功响应

{
  "status": "success",
  "tag_id": "89425"
}

创建失败响应

创建失败时可能返回：

{
  "status": "failed",
  "message": "Create digital human task failed",
  "request_id": "f7dad4740c308e8f8ca4f2ae506fefff"
}

参数校验失败时返回通用错误格式。

• 创建任务时会先根据预计时长进行预扣。
• 文本驱动按文本长度估算时长：约每 4 个字符按 1 秒估算，最少 1 秒。
• 音频驱动优先使用传入的 duration、duration_seconds、audio_duration、audio_seconds。
• 若音频驱动未传时长，系统会尝试下载 audio_url 并识别音频时长；如果 URL 无法访问、返回 403、不是音频文件或识别失败，会返回参数错误。
• 任务完成后按实际结果时长结算，多退少补或释放预扣金额。

查询数字人视频任务状态

GET /digitalhuman/queryDigitalHumanTask

查询数字人视频任务状态。传入创建任务返回的 tag_id。

请求

curl "https://api.yisu.com/digitalhuman/queryDigitalHumanTask?tag_id=89425" \
  -H "Authorization: Bearer <API_KEY>"

请求参数

响应状态

排队中响应示例

{
  "status": "queued",
  "tag_id": "89425"
}

制作中响应示例

{
  "status": "in_progress",
  "tag_id": "89425"
}

制作完成响应示例

{
  "status": "completed",
  "tag_id": "89425",
  "new_video_file_url": "https://cache.jiuma.com/static/uploads/20260710/6a50b2aedb24b.mp4",
  "new_video_file_duration": "2.04",
  "type": "super"
}

制作失败响应示例

{
  "status": "failed",
  "tag_id": "89425",
  "message": "制作失败"
}

任务结果通知

创建任务时可以传入 input_reference.callback_url 或顶层 callback_url。

任务完成或失败后，系统会向该地址发送 JSON 通知。制作完成通知示例：

{
  "status": "completed",
  "tag_id": "91851",
  "new_video_file_url": "https://cache.jiuma.com/static/uploads/20260713/6a54b4b902282.mp4",
  "type": "cartoon"
}

制作失败通知示例：

{
  "status": "failed",
  "tag_id": "91851",
  "message": "制作失败"
}

建议同时保留主动查询逻辑，以便在网络超时或通知失败时补偿获取结果。

字段说明

数字人形象对象

音色对象

注意事项

• 数字人视频任务制作耗时通常较长，请按异步任务处理。
• submitDigitalHumanTask 只支持 video_id，不支持传入 video_url。
• engine 是 submitDigitalHumanTask 的顶层参数，可选值为 auto、standard、ultra。
• 如果 video_id 对应的数字人形象是图片素材创建的形象，不能制作超拟真视频任务，即 engine 不能为 standard；可以不传 engine，或传 auto、ultra。
• 音频驱动建议显式传入 duration，可避免服务端因音频 URL 无法下载或识别失败导致创建任务失败。
• 任务结果通知可能受网络、证书、超时等因素影响，建议同时使用查询接口补偿获取结果。