Skip to main content
POST
/
api
/
v1
/
jobs
/
createTask
Generate character animations using sora-2-characters
curl --request POST \
  --url https://api.kie.ai/api/v1/jobs/createTask \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "sora-2-characters",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "character_file_url": [
      "https://static.aiquickdraw.com/tools/example/character1.mp4"
    ],
    "character_prompt": "A friendly cartoon character with expressive eyes and fluid movements",
    "safety_instruction": "Ensure the animation is family-friendly and contains no violent or inappropriate content"
  }
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_sora-2-characters_1765174270120"
  }
}

​
File Upload Requirements

Before using the Character Animation API, you need to upload your character videos:
1

Upload Character Videos

Visit our File Upload API to upload your character videos.Requirements:
  • File Type: MP4, WebM, or AVI format
  • Duration: Between 1-4 seconds per video
  • Max File Size: 10MB per file
  • Content: Character movements or actions you want to animate
Only one character video can be uploaded per animation task.
2

Get Upload URLs

After successful upload, you’ll receive file URLs that can be used in the character_file_url parameter.
3

Submit Animation Task

Use the obtained URLs in your API request to generate character animations with the new parameters.

​
Additional Parameters

Besides the character video URL, you can provide additional parameters to enhance your character animation:
  • character_prompt: Description of the character and desired animation style (Max 5000 characters)
  • safety_instruction: Safety guidelines and content restrictions for the animation (Max 5000 characters)
Both parameters are optional but recommended for better control over the animation output.
File Storage Notice: Files uploaded through our File Upload API are stored temporarily for only 14 days. After this period, the character URLs will become invalid and cause errors when using the Character Animation API. We recommend using third-party permanent storage solutions (such as AWS S3, Google Cloud Storage, or other cloud storage services) to ensure long-term availability of your character video files.
Ensure your character videos are between 1-4 seconds long. Videos outside this duration range may cause processing errors.

​
Query Task Status

After submitting a task, use the unified query endpoint to check progress and retrieve results:

Get Task Details

Learn how to query task status and retrieve generation results

​
Task Query Response Format

When the task is completed successfully (state: "success"), the resultJson field contains: 
{
  "character_id": "example_123456789"
}
The character_id can be used to reference the generated character animation in subsequent operations.
For production use, we recommend using the callBackUrl parameter to receive automatic notifications when generation completes, rather than polling the status endpoint.

Market Overview

Explore all available models

File Upload API

Learn how to upload your character videos

Common API

Check credits and account usage

Authorizations

​
Authorization
string
header
required

All APIs require authentication via Bearer Token.

Get API Key:

  1. Visit API Key Management Page to get your API Key

Usage: Add to request header: Authorization: Bearer YOUR_API_KEY

Note:

  • Keep your API Key secure and do not share it with others
  • If you suspect your API Key has been compromised, reset it immediately in the management page

Body

application/json
​
model
enum<string>
default:sora-2-characters
required

The model name to use for generation. Required field.

  • Must be sora-2-characters for this endpoint
Available options:
sora-2-characters
Example:

"sora-2-characters"

​
callBackUrl
string<uri>

The URL to receive generation task completion updates. Optional but recommended for production use.

  • System will POST task status and results to this URL when generation completes
  • Callback includes generated content URLs and task information
  • Your callback endpoint should accept POST requests with JSON payload containing results
  • Alternatively, use the Get Task Details endpoint to poll task status
  • To ensure callback security, see Webhook Verification Guide for signature verification implementation
Example:

"https://your-domain.com/api/callback"

​
input
object

Input parameters for the generation task

Response

Request successful

​
code
enum<integer>

Response status code

  • 200: Success - Request has been processed successfully
  • 401: Unauthorized - Authentication credentials are missing or invalid
  • 402: Insufficient Credits - Account does not have enough credits to perform the operation
  • 404: Not Found - The requested resource or endpoint does not exist
  • 422: Validation Error - The request parameters failed validation checks
  • 429: Rate Limited - Request limit has been exceeded for this resource
  • 455: Service Unavailable - System is currently undergoing maintenance
  • 500: Server Error - An unexpected error occurred while processing the request
  • 501: Generation Failed - Content generation task failed
  • 505: Feature Disabled - The requested feature is currently disabled
Available options:
200,
401,
402,
404,
422,
429,
455,
500,
501,
505
​
msg
string

Response message, error description when failed

Example:

"success"

​
data
object