跳转到主要内容
GET
/
v1
/
characters_tasks
/
{task_id}
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": {}
}

​
功能概述

查询角色创建任务的状态和结果，获取已创建角色的详细信息（角色 ID、显示名称、用户名等），用于后续视频生成。
使用说明：
  • 角色创建是异步任务，需要轮询此接口获取结果
  • 任务完成后返回角色详细信息
  • 角色 username 可在 prompt 中使用 @username 格式引用
  • 角色任务 ID 可通过 character_url 参数在视频生成中使用

​
路径参数

​
task_id
string
必填
角色创建任务 ID这是从 创建角色 API 返回的任务 ID示例："task_01KBZ0TZZ7C7M3WS1TJM0PH8J4"

​
认证

​
Authorization
string
必填
Bearer Token 认证
Authorization: Bearer YOUR_API_KEY
获取 API Key：访问 API Key 管理页面

​
响应字段

​
id
string
任务唯一标识符（角色创建任务 ID）
​
object
string
对象类型，固定为 generation.task
​
model
string
使用的模型名称
​
status
string
任务状态：
  • queued - 排队等待处理
  • in_progress - 处理中
  • completed - 成功完成
  • failed - 失败
​
progress
integer
任务进度百分比（0-100）
​
created_at
integer
任务创建时间（Unix 时间戳）
​
completed_at
integer
任务完成时间（Unix 时间戳，仅完成后有值）
​
expires_at
integer
结果资源过期时间（Unix 时间戳，仅完成后有值）
​
result
object
任务结果（仅 status 为 completed 时有值）result.type 固定为 character，result.data.characters 为角色列表
​
error
object
错误信息（仅 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 分钟
超时处理重新提交任务或联系支持