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

​
路径参数

​
task_id
string
required
角色创建任务 ID，即从创建角色 API 返回的任务 ID。示例："task_01KBZ0TZZ7C7M3WS1TJM0PH8J4"

​
请求示例

curl --request GET \
  --url 'https://geekapis.com/v1/characters_tasks/task_01KBZ0TZZ7C7M3WS1TJM0PH8J4' \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

​
返回示例

200（进行中）
{
  "id": "task_01KC0JZCMTMQ70D68XTM56Q5D0",
  "object": "generation.task",
  "model": "sora-2",
  "status": "in_progress",
  "progress": 45,
  "created_at": 1765251461,
  "metadata": {}
}
200（创建完成）
{
  "id": "task_01KC0JZCMTMQ70D68XTM56Q5D0",
  "object": "generation.task",
  "model": "sora-2",
  "status": "completed",
  "progress": 100,
  "created_at": 1765251461,
  "completed_at": 1765251561,
  "expires_at": 1765337961,
  "result": {
    "type": "character",
    "data": {
      "characters": [
        {
          "id": "char_abc123",
          "username": "duksvfkf.turbo_whis",
          "display_name": "Turbo Whiskers"
        }
      ]
    }
  }
}

​
响应字段

字段类型说明
idstring任务唯一标识符（角色创建任务 ID）
objectstring对象类型，固定为 generation.task
modelstring使用的模型名称
statusstring任务状态：queued / in_progress / completed / failed
progressinteger任务进度百分比（0–100）
created_atinteger任务创建时间（Unix 时间戳）
completed_atinteger任务完成时间（Unix 时间戳，仅完成后有值）
expires_atinteger结果资源过期时间（Unix 时间戳，仅完成后有值）
resultobject任务结果（仅 status 为 completed 时有值）
errorobject错误信息（仅 status 为 failed 时有值）

​
使用角色生成视频

角色创建完成后，可通过以下两种方式在视频生成中引用角色：

​
方式一：在 prompt 中使用 @username 引用

curl --request POST \
  --url https://geekapis.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://geekapis.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",
    "metadata": {
      "character_url": "task_01KC0JZCMTMQ70D68XTM56Q5D0"
    }
  }'
username 从查询结果的 result.data.characters[].username 字段获取；character_url 使用角色创建任务的 task_id。

​
轮询建议

参数建议值
轮询间隔5 秒
最大等待时间5 分钟
超时处理重新提交任务或联系支持