Skip to main content
GET
/
v1
/
characters_tasks
/
{task_id}
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": {}
}

​
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 IDThis is the task ID returned from the Create Character APIExample: "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 --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 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

ParameterRecommended Value
Polling Interval5 seconds
Max Wait Time5 minutes
Timeout HandlingResubmit task or contact support