Documentation Index
Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
Use this file to discover all available pages before exploring further.
Sora2 查询角色状态
查询角色创建任务的状态和结果
功能概述
查询角色创建任务的状态和结果，获取已创建角色的详细信息（角色 ID、显示名称、用户名等），用于后续视频生成。
使用说明：
- 角色创建是异步任务，需要轮询此接口获取结果
- 任务完成后返回角色详细信息
- 角色
username 可在 prompt 中使用 @username 格式引用
- 角色任务 ID 可通过
character_url 参数在视频生成中使用
路径参数
角色创建任务 ID这是从 创建角色 API 返回的任务 ID示例："task_01KBZ0TZZ7C7M3WS1TJM0PH8J4" Bearer Token 认证Authorization: Bearer YOUR_API_KEY
响应字段
任务状态：
queued - 排队等待处理in_progress - 处理中completed - 成功完成failed - 失败
结果资源过期时间（Unix 时间戳，仅完成后有值）
任务结果（仅 status 为 completed 时有值）result.type 固定为 character，result.data.characters 为角色列表
错误信息（仅 status 为 failed 时有值）
curl --request GET \
--url 'https://toapis.com/v1/characters_tasks/task_01KBZ0TZZ7C7M3WS1TJM0PH8J4' \
--header 'Authorization: Bearer YOUR_API_KEY'
{
"id": "task_01KC0JZCMTMQ70D68XTM56Q5D0",
"object": "generation.task",
"model": "sora-2",
"status": "in_progress",
"progress": 45,
"created_at": 1765251461,
"metadata": {}
}
使用角色生成视频
角色创建完成后，可以在视频生成中使用角色。有两种引用方式：
方式一：使用 @username 在 prompt 中引用
curl --request POST \
--url https://toapis.com/v1/videos/generations \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "sora-2",
"prompt": "@duksvfkf.turbo_whis is dancing in the rain"
}'
方式二：使用 character_url 参数
curl --request POST \
--url https://toapis.com/v1/videos/generations \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "sora-2",
"prompt": "A cute cat is dancing in the rain",
"character_url": "task_01KC0JZCMTMQ70D68XTM56Q5D0"
}'
提示： username 从查询结果的 characters[].username 字段获取，character_url 使用角色创建任务的 task_id。
轮询建议
| 参数 | 建议值 |
|---|
| 轮询间隔 | 5 秒 |
| 最大等待时间 | 5 分钟 |
| 超时处理 | 重新提交任务或联系支持 |
