ToAPIsToAPIs
Sora2

Sora2 查詢角色狀態

查詢角色創建任務的狀態和結果

GET
/v1/characters_tasks/{task_id}

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

功能概述

查詢角色創建任務的狀態和結果,獲取已創建角色的詳細信息(角色 ID、顯示名稱、用戶名等),用於後續視頻生成。

使用說明:

  • 角色創建是異步任務,需要輪詢此接口獲取結果
  • 任務完成後返回角色詳細信息
  • 角色 username 可在 prompt 中使用 @username 格式引用
  • 角色任務 ID 可通過 character_url 參數在視頻生成中使用

路徑參數

task_idstring路徑必填

角色創建任務 ID

這是從 創建角色 API 返回的任務 ID

示例:"task_01KBZ0TZZ7C7M3WS1TJM0PH8J4"

認證

Authorizationstring請求頭必填

Bearer Token 認證

Authorization: Bearer YOUR_API_KEY

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

響應字段

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 時有值)

result.type 固定爲 character,result.data.characters 爲角色列表

errorobject

錯誤信息(僅 status 爲 failed 時有值)

請求示例

curl --request GET \
  --url 'https://toapis.com/v1/characters_tasks/task_01KBZ0TZZ7C7M3WS1TJM0PH8J4' \
  --header 'Authorization: Bearer YOUR_API_KEY'
import requests
import time

def query_character_task(task_id):
    """查詢角色創建任務狀態"""
    url = f"https://toapis.com/v1/characters_tasks/{task_id}"
    headers = {"Authorization": "Bearer YOUR_API_KEY"}

    response = requests.get(url, headers=headers)
    return response.json()

def wait_for_character(task_id, max_wait=300, interval=5):
    """輪詢等待角色創建完成"""
    start_time = time.time()

    while time.time() - start_time < max_wait:
        result = query_character_task(task_id)

        status = result['status']
        progress = result.get('progress', 0)
        print(f"狀態: {status}, 進度: {progress}%")

        if status == 'completed':
            characters = result['result']['data']['characters']
            for char in characters:
                print(f"角色 ID: {char['id']}")
                print(f"顯示名稱: {char['display_name']}")
                print(f"用戶名: {char['username']}")
            return result

        if status == 'failed':
            raise Exception("角色創建失敗")

        time.sleep(interval)

    raise Exception("等待超時")

# 使用示例
task_id = "task_01KBZ0TZZ7C7M3WS1TJM0PH8J4"
result = wait_for_character(task_id)
async function queryCharacterTask(taskId) {
  const response = await fetch(
    `https://toapis.com/v1/characters_tasks/${taskId}`,
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );
  return await response.json();
}

async function waitForCharacter(taskId, maxWait = 300000, interval = 5000) {
  const startTime = Date.now();

  while (Date.now() - startTime < maxWait) {
    const result = await queryCharacterTask(taskId);

    const { status, progress } = result;
    console.log(`狀態: ${status}, 進度: ${progress}%`);

    if (status === 'completed') {
      const characters = result.result.data.characters;
      characters.forEach(char => {
        console.log(`角色 ID: ${char.id}`);
        console.log(`顯示名稱: ${char.display_name}`);
        console.log(`用戶名: ${char.username}`);
      });
      return result;
    }

    if (status === 'failed') {
      throw new Error('角色創建失敗');
    }

    await new Promise(resolve => setTimeout(resolve, interval));
  }

  throw new Error('等待超時');
}

// 使用示例
const taskId = 'task_01KBZ0TZZ7C7M3WS1TJM0PH8J4';
waitForCharacter(taskId).then(result => console.log(result));
package main

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

type CharacterResponse struct {
    ID        string `json:"id"`
    Object    string `json:"object"`
    Model     string `json:"model"`
    Status    string `json:"status"`
    Progress  int    `json:"progress"`
    CreatedAt int64  `json:"created_at"`
    Result    struct {
        Type string `json:"type"`
        Data struct {
            Characters []struct {
                ID                string `json:"id"`
                DisplayName       string `json:"display_name"`
                ProfilePictureURL string `json:"profile_picture_url"`
                Username          string `json:"username"`
            } `json:"characters"`
        } `json:"data"`
    } `json:"result"`
}

func queryCharacterTask(taskID string) (*CharacterResponse, error) {
    url := "https://toapis.com/v1/characters_tasks/" + taskID

    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

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

    body, _ := io.ReadAll(resp.Body)

    var result CharacterResponse
    json.Unmarshal(body, &result)
    return &result, nil
}

func main() {
    taskID := "task_01KBZ0TZZ7C7M3WS1TJM0PH8J4"

    for i := 0; i < 60; i++ {
        result, err := queryCharacterTask(taskID)
        if err != nil {
            panic(err)
        }

        fmt.Printf("狀態: %s, 進度: %d%%\n", result.Status, result.Progress)

        if result.Status == "completed" {
            for _, char := range result.Result.Data.Characters {
                fmt.Printf("角色 ID: %s\n", char.ID)
                fmt.Printf("顯示名稱: %s\n", char.DisplayName)
                fmt.Printf("用戶名: %s\n", char.Username)
            }
            break
        }

        time.Sleep(5 * time.Second)
    }
}

響應示例

{
  "id": "task_01KC0JZCMTMQ70D68XTM56Q5D0",
  "object": "generation.task",
  "model": "sora-2",
  "status": "in_progress",
  "progress": 45,
  "created_at": 1765251461,
  "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": "請求參數無效",
    "type": "invalid_request_error"
  }
}
{
  "error": {
    "code": 401,
    "message": "身份驗證失敗,請檢查您的 API 密鑰",
    "type": "authentication_error"
  }
}
{
  "error": {
    "code": 404,
    "message": "任務不存在",
    "type": "not_found_error"
  }
}
{
  "error": {
    "code": 429,
    "message": "請求過於頻繁,請稍後再試",
    "type": "rate_limit_error"
  }
}

使用角色生成視頻

角色創建完成後,可以在視頻生成中使用角色。有兩種引用方式:

方式一:使用 @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 分鐘
超時處理重新提交任務或聯繫支持