跳轉到主要內容
POST
/
v1
/
videos
/
generations
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",
    "url": "https://example.com/character-video.mp4",
    "timestamps": "1,3"
  }'

{
  "id": "task_01KBYT59JDHB4A3KDDR9N9JVWP",
  "object": "generation.task",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1703884800,
  "metadata": {}
}

​
功能概述

Sora2 角色創建功能允許您從現有視頻中提取角色，創建後可在後續視頻生成中複用該角色，實現角色一致性。
重要提示：
  • 視頻必須包含聲音和可識別的角色
  • 時間範圍限制：最小 1 秒，最大 3 秒
  • url 和 from_task 二選一，必須提供其中一個
  • 此模式下不需要 prompt 參數
  • 創建完成後，角色任務 ID 可用於後續視頻生成

​
認證

​
Authorization
string
必填
Bearer Token 認證
Authorization: Bearer YOUR_API_KEY
獲取 API Key：訪問 API Key 管理頁面

​
請求參數

​
model
string
預設值:"sora-2"
必填
視頻生成模型名稱支持的模型：
  • sora-2 - 標準版本
  • sora-2-pro - 專業版本（更高質量）
  • sora-2-vip - VIP版，更高優先級
​
timestamps
string
必填
角色出現的時間戳範圍單位爲秒，格式爲 "起始秒,結束秒"限制：
  • 時間範圍差值最小 1 秒
  • 時間範圍差值最大 3 秒
示例："1,3" 表示視頻中第 1 秒到第 3 秒出現的角色
​
url
string
包含需要創建角色的視頻 URL要求：
  • 視頻必須包含聲音
  • 視頻必須包含可識別的角色
說明： 與 from_task 二選一示例："https://example.com/my-video.mp4"
​
from_task
string
已生成的視頻任務 ID可以根據已經生成的視頻任務 ID 來創建角色說明： 與 url 二選一示例："task_01KBYT59JDHB4A3KDDR9N9JVWP"

​
響應字段

​
id
string
任務唯一標識符，用於查詢角色創建狀態創建完成後，可使用此角色任務 ID 在視頻生成時通過 character_url 參數引用該角色
​
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 時間戳，僅完成後有值）
​
result
object
角色創建結果（僅完成後有值）包含創建的角色信息，如角色 ID、名稱、頭像等
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",
    "url": "https://example.com/character-video.mp4",
    "timestamps": "1,3"
  }'

{
  "id": "task_01KBYT59JDHB4A3KDDR9N9JVWP",
  "object": "generation.task",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1703884800,
  "metadata": {}
}

​
使用流程

1

提交角色創建請求

調用此接口，提供包含角色的視頻 URL 或已有任務 ID，以及角色出現的時間範圍
2

獲取任務 ID

接口返回任務 ID，狀態爲 queued 或 in_progress
3

查詢任務狀態

使用 查詢視頻任務狀態 接口輪詢任務進度
4

使用角色生成視頻

角色創建完成後，在後續視頻生成中使用 character_url 參數引用該角色任務 ID

​
最佳實踐

  1. 選擇清晰的角色片段：選擇視頻中角色特徵最明顯的 1-3 秒片段
  2. 確保視頻質量：高清視頻能夠更好地提取角色特徵
  3. 包含聲音：視頻必須包含音頻軌道
  4. 避免多角色：選擇的時間範圍內最好只有一個主要角色