API Reference
AI 视频 - 角色创建 API
POST
video-character-api
ID 12
为 AI 视频工作流创建/管理角色资产，供后续视频生成引用。
POST
https://apis.xiaobao.ink/api/video/character
概述
- 角色创建
- 供生成接口引用
适用场景
- 角色一致性视频
- 系列内容生产
调用约定
- 网关 ·
https://apis.xiaobao.ink - 鉴权 · 请求携带
key（Query 或 JSON Body，以本接口为准） - 回包 · JSON；请同时校验业务码与 HTTP 状态，不要只看 200
鉴权
请求需携带平台 API Key（查询参数 key 或 JSON 字段 key，以本接口说明为准）。在控制台 API Key 管理 创建密钥。
POST https://apis.xiaobao.ink/api/video/character
Content-Type: application/json
{
"key": "YOUR_API_KEY"
}
请求示例
https://apis.xiaobao.ink/api/video/character?key=你的密钥
详细说明
请求HEADER：
| 名称 | 值 |
|---|---|
| Content-Type | application/json |
请求参数说明：
| 名称 | 必填 | 类型 | 示例值 | 说明 |
|---|---|---|---|---|
| pid | 否 | string | s_6933c62623048191a0f20b5dbe781888 | 视频pid AI生成视频结果的pid值(可以出现真人形象，pid和视频地址参数二选一即可） |
| url | 否 | string | https://ope.oss-cn-shanghai.aliyuncs.com/9d1212e12.mp4 | 视频URL（禁止出现真人形象，视频地址可公网访问下载，视频时长不要过长） |
| timestamps | 否 | string | 0,3 | 视频取用角色出现的时间范围 格式: 开始秒数,结束秒数,最多3秒 |
| notify | 是 | string | https://xx.com/xxx | 回调地址 （ 任务推送地址） |
返回参数说明：
| 名称 | 类型 | 说明 |
|---|---|---|
| code | int | 状态码 |
| msg | string | 状态信息 |
| data | array | 请求结果数据集 |
| - task_id | string | 任务ID |
| exec_time | float | 执行耗时 |
| user_ip | string | 客户端IP |
回调参数说明：
| 名称 | 类型 | 说明 |
|---|---|---|
| code | int | 状态码 |
| msg | string | 状态信息 |
| data | array | 请求结果数据集 |
| - task_id | string | 任务ID |
| - character_id | string | character.name character_id: 角色id |
| - failure_reason | string | 失败原因 "output_moderation": 输出违规 "input_moderation": 输入违规 "error": 其他错误 ------ 当生成失败时，会返还积分 |
| - error | string | 失败详细信息 |
| exec_time | float | 执行耗时 |
| user_ip | string | 客户端IP |
返回示例
{ "code": 200, "msg": "xxxx", "data": [ { "task_id": "xxxxx", "character_id": "character.name", "failure_reason": "", "error": "" } ]}
常见问题
角色创建接口用途？
生成可复用的角色标识，便于多支视频保持人物一致。
如何使用角色？
在支持角色参数的视频生成接口中传入返回的角色 ID。
需要什么素材？
按文档提交角色参考图或描述字段。
是否异步？
以该接口文档为准。
和数字人区别？
数字人侧重口播出镜合成；角色创建服务于文生视频等模型角色资产。
相关接口
完整控制台文档（含调试台）：/doc/12