ToAPIsToAPIs
Sora2

Sora2 創建角色

從視頻中提取角色,用於後續視頻生成

POST
/v1/videos/generations

中國大陸用戶請注意: 中國大陸用戶請使用 https://toapis.cn 作為接口地址(Base URL)。文檔示例中的 https://toapis.com 請替換為 https://toapis.cn。

功能概述

Sora2 角色創建功能允許您從現有視頻中提取角色,創建後可在後續視頻生成中複用該角色,實現角色一致性。

重要提示:

  • 視頻必須包含聲音和可識別的角色
  • 時間範圍限制:最小 1 秒,最大 3 秒
  • url 和 from_task 二選一,必須提供其中一個
  • 此模式下不需要 prompt 參數
  • 創建完成後,角色任務 ID 可用於後續視頻生成

認證

Authorizationstring請求頭必填

Bearer Token 認證

Authorization: Bearer YOUR_API_KEY

獲取 API Key:訪問 API Key 管理頁面

請求參數

modelstring請求體必填預設值: sora-2

視頻生成模型名稱

支持的模型:

  • sora-2 - 標準版本
  • sora-2-pro - 專業版本(更高質量)
timestampsstring請求體必填

角色出現的時間戳範圍

單位爲秒,格式爲 "起始秒,結束秒"

限制:

  • 時間範圍差值最小 1 秒
  • 時間範圍差值最大 3 秒

示例:"1,3" 表示視頻中第 1 秒到第 3 秒出現的角色

urlstring請求體

包含需要創建角色的視頻 URL

要求:

  • 視頻必須包含聲音
  • 視頻必須包含可識別的角色

說明: 與 from_task 二選一

示例:"https://example.com/my-video.mp4"

from_taskstring請求體

已生成的視頻任務 ID

可以根據已經生成的視頻任務 ID 來創建角色

說明: 與 url 二選一

示例:"task_01KBYT59JDHB4A3KDDR9N9JVWP"

響應字段

idstring

任務唯一標識符,用於查詢角色創建狀態

創建完成後,可使用此角色任務 ID 在視頻生成時通過 character_url 參數引用該角色

objectstring

對象類型,固定爲 generation.task

modelstring

使用的模型名稱

statusstring

任務狀態:

  • queued - 排隊等待處理
  • in_progress - 處理中
  • completed - 成功完成
  • failed - 失敗
progressinteger

任務進度百分比(0-100)

created_atinteger

任務創建時間(Unix 時間戳)

completed_atinteger

任務完成時間(Unix 時間戳,僅完成後有值)

resultobject

角色創建結果(僅完成後有值)

包含創建的角色信息,如角色 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"
  }'
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",
    "from_task": "task_01KBYT59JDHB4A3KDDR9N9JVWP",
    "timestamps": "1,3"
  }'
import requests

# 從視頻 URL 創建角色
response = requests.post(
    "https://toapis.com/v1/videos/generations",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "model": "sora-2",
        "url": "https://example.com/character-video.mp4",
        "timestamps": "1,3"
    }
)

task = response.json()
print(f"任務 ID: {task['id']}")
print(f"狀態: {task['status']}")

# 從已生成任務創建角色
response = requests.post(
    "https://toapis.com/v1/videos/generations",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "model": "sora-2",
        "from_task": "task_01KBYT59JDHB4A3KDDR9N9JVWP",
        "timestamps": "1,3"
    }
)
// 從視頻 URL 創建角色
const response = await fetch('https://toapis.com/v1/videos/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'sora-2',
    url: 'https://example.com/character-video.mp4',
    timestamps: '1,3'
  })
});

const task = await response.json();
console.log(`任務 ID: ${task.id}`);
console.log(`狀態: ${task.status}`);
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    url := "https://toapis.com/v1/videos/generations"

    payload := map[string]interface{}{
        "model":      "sora-2",
        "url":        "https://example.com/character-video.mp4",
        "timestamps": "1,3",
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

響應示例

{
  "id": "task_01KBYT59JDHB4A3KDDR9N9JVWP",
  "object": "generation.task",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1703884800,
  "metadata": {}
}
{
  "id": "task_01KC0JZCMTMQ70D68XTM56Q5D0",
  "object": "generation.task",
  "model": "sora-2",
  "status": "completed",
  "progress": 100,
  "created_at": 1765251461,
  "completed_at": 1765251507,
  "result": {
    "type": "character",
    "data": {
      "characters": [
        {
          "id": "ch_6937998961208191a45ef08447a554df",
          "display_name": "Turbo Whiskers",
          "profile_picture_url": "https://upload.toapis.com/f/image/character_task_xxx.jpg",
          "username": "duksvfkf.turbo_whis"
        }
      ]
    }
  },
  "metadata": {}
}
{
  "error": {
    "code": 400,
    "message": "請求參數無效:timestamps 時間範圍必須在 1-3 秒之間",
    "type": "invalid_request_error"
  }
}
{
  "error": {
    "code": 401,
    "message": "身份驗證失敗,請檢查您的 API 密鑰",
    "type": "authentication_error"
  }
}
{
  "error": {
    "code": 402,
    "message": "賬戶餘額不足,請充值後再試",
    "type": "payment_required"
  }
}

使用流程

提交角色創建請求

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

獲取任務 ID

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

查詢任務狀態

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

使用角色生成視頻

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

最佳實踐

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