跳轉到主要內容
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 分鐘
超時處理重新提交任務或聯繫支持