Sora2 Query Character ステータス

概要

Query the status and result of character creation tasks. Retrieve detailed information about created characters (character ID, display name, username, etc.) for use in subsequent video generation.

Usage Notes:

Character creation is an async task - poll this endpoint for results
Task completion returns character details
Character username can be referenced in prompts using @username format
Character task ID can be used via character_url parameter in video generation

Path パラメータ

task_id

string

必須

Character creation task IDThis is the task ID returned from the Create Character APIExample: "task_01KBZ0TZZ7C7M3WS1TJM0PH8J4"

認証

Authorization

string

必須

Bearer Token authentication

Authorization: Bearer YOUR_API_KEY

Get your API Key from the API Key Management Page

レスポンス Fields

string

Unique task identifier (character creation task ID)

object

string

Object type, always generation.task

model

string

モデル name used

status

string

Task status:

queued - Queued for processing
in_progress - Processing
completed - Successfully completed
failed - Failed

progress

integer

Task progress percentage (0-100)

created_at

integer

Task creation time (Unix timestamp)

completed_at

integer

Task completion time (Unix timestamp, only available after completion)

expires_at

integer

Result expiration time (Unix timestamp, only available after completion)

result

object

Task result (only available when status is completed)result.type is character, and result.data.characters contains the character list

error

object

エラー information (only available when status is 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": {}
}

Using Character in 動画生成

After character creation completes, you can use the character in video generation. There are two ways to reference:

Method 1: Use @username in 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"
  }'

Method 2: Use character_url parameter

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"
  }'

Tip: username is obtained from the characters[].username field in query results, character_url uses the character creation task’s task_id.

Polling Recommendations

Parameter	Recommended Value
Polling Interval	5 seconds
Max Wait Time	5 minutes
Timeout Handling	Resubmit task or contact support

​概要

​Path パラメータ

​認証

​レスポンス Fields

​Using Character in 動画生成

​Method 1: Use @username in prompt

​Method 2: Use character_url parameter

​Polling Recommendations

概要

Path パラメータ

認証

レスポンス Fields

Using Character in 動画生成

Method 1: Use @username in prompt

Method 2: Use character_url parameter

Polling Recommendations