Sora2 Query Character Status

Query character creation task status and results

GET /v1/characters_tasks/{task_id}

cURL

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

200 (In Progress)

{
  "id": "task_01KC0JZCMTMQ70D68XTM56Q5D0",
  "object": "generation.task",
  "model": "sora-2",
  "status": "in_progress",
  "progress": 45,
  "created_at": 1765251461,
  "metadata": {}
}

Overview

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 Parameters

task_id · string · required

Character creation task ID

This is the task ID returned from the Create Character API

Example: "task_01KBZ0TZZ7C7M3WS1TJM0PH8J4"

Authentication

Authorization · string · required

Bearer Token authentication

Authorization: Bearer YOUR_API_KEY

Get your API Key from the API Key Management Page

Response Fields

id · string

Unique task identifier (character creation task ID)

object · string

Object type, always generation.task

model · string

Model 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

Error information (only available when status is failed)

cURL

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

200 (In Progress)

{
  "id": "task_01KC0JZCMTMQ70D68XTM56Q5D0",
  "object": "generation.task",
  "model": "sora-2",
  "status": "in_progress",
  "progress": 45,
  "created_at": 1765251461,
  "metadata": {}
}

Using Character in Video Generation

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