Sora 2 Character API - API易文档中心

Overview

The Sora 2 Character API allows you to create reusable characters from videos and maintain character consistency across multiple video generations. By referencing @id (unique Cameo ID or Character ID) in your prompts, you can make specific characters appear in different videos.

Since the API prohibits direct use of human faces, the Character API provides a compliant solution: create a character as a virtual entity first, then reference it via @id in prompts.

Core Concepts

How the Character API works:

Create Character: Generate a unique character ID from a video URL
Reference Character: Include @character_id or @username in video generation prompts
Maintain Consistency: Characters retain their appearance and features across different videos

Why Use Characters?

Important Limitation: Real human appearances are NOT allowed. The API does not permit uploading videos containing real human faces as characters.

Typical use cases for the Character API:

E-commerce Scenarios

Product Characterization

Turn product packaging into characters to maintain consistent brand logos, text, and visual identity. Reference the product via @character_id in subsequent videos to ensure consistent appearance across different scenes.

Example Applications:

Product showcase videos: Same product appearing in different environments (outdoor, indoor, workplace)
Brand marketing: Brand mascots maintaining consistent imagery across multiple short videos
Package display: Logos and text on product packaging remain clear and consistent from multiple angles

Animation Scenarios

Virtual Characters

Virtual personas, cartoon characters, and anime figures are ideal for character creation. Once created, characters can appear repeatedly across different plots and scenes while maintaining consistent design.

Example Applications:

Series animation shorts: Protagonists maintaining same appearance across episodes
Brand IP characters: Virtual spokespersons appearing in different marketing videos
Educational content: Teaching virtual instructors maintaining consistent image across videos

Other Scenarios

Game Assets: Promotional videos for game characters
Virtual Streamers: Series video content for virtual content creators
IP Derivatives: Video content creation for existing IP characters

Endpoint

https://api.apiyi.com/sora/v1/characters

Request Parameters

Parameter	Type	Required	Description
`model`	string	✅	Fixed value: `sora-character`
`url`	string	✅	Video URL containing the character to be created
`timestamps`	string	✅	Time range where character appears (in seconds), format: `"start,end"` Example: `"1,3"` means seconds 1-3 of the video Range difference: minimum 1 second, maximum 3 seconds

Parameter Details

url - Video URL Requirements

Video Length: 15 seconds or less
Format: MP4, MOV, and other common formats
Content: Must NOT contain real human faces or obvious human body outlines
Accessibility: URL must be publicly accessible (CDN addresses supported)

Best Practices:

Use CDN-hosted videos for better success rates
Ensure sufficient video clarity (720p or above recommended)
Character should have distinctive features (color, shape, texture, etc.)

timestamps - Time Range Settings

Format: String type, e.g., "1,3"
Meaning: Specifies the time segment in the video where the character appears (from which second to which second)
Unit: Seconds (integers or decimals accepted)
Total Video Length: Video can be any length up to 15 seconds
Time Segment Constraints:
- Segment duration (end seconds - start seconds): minimum 1 second, maximum 3 seconds
- Start time cannot be less than 0
- End time cannot exceed total video duration

Examples:

Video total length 15s, timestamps: "1,3" means use video content from seconds 1-3 as character (segment duration 2s)
Video total length 15s, timestamps: "8,11" means use video content from seconds 8-11 as character (segment duration 3s)
Video total length 10s, timestamps: "5,6" means use video content from seconds 5-6 as character (segment duration 1s)

Selection Tips:

Find the time segment in the video where character features are most prominent
Avoid time segments where character is occluded or motion-blurred
Segment duration can be 1-3 seconds based on actual needs, typically around 2 seconds works well

Future Support: Create from Async Task ID

Current Status: Not yet availableFuture updates will support creating characters directly using Sora 2 async video generation task video_id, eliminating the need to download and re-upload videos to CDN. This will significantly streamline the workflow.Expected parameter format:

{
  "model": "sora-character",
  "video_id": "video_abc123def456",
  "timestamps": "1,3"
}

Code Examples

cURL Example

cURL

curl -X POST "https://api.apiyi.com/sora/v1/characters" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "sora-character",
    "url": "https://mycdn-gg.oss-us-west-1.aliyuncs.com/sora/64ba6b88-8540-4b73-bf05-7bd2e96bebd1.mp4",
    "timestamps": "1,3"
  }'

Python Examples

import requests
import json

# API Configuration
API_URL = "https://api.apiyi.com/sora/v1/characters"
API_KEY = "YOUR_API_KEY"

# Request parameters
payload = {
    "model": "sora-character",
    "url": "https://mycdn-gg.oss-us-west-1.aliyuncs.com/sora/64ba6b88-8540-4b73-bf05-7bd2e96bebd1.mp4",
    "timestamps": "1,3"
}

# Send request
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

response = requests.post(API_URL, headers=headers, json=payload)
result = response.json()

# Output results
print(f"Character ID: {result['id']}")
print(f"Username: {result['username']}")
print(f"Display Name: {result['display_name']}")
print(f"Permalink: {result['permalink']}")
print(f"Profile Picture: {result['profile_picture_url']}")

Response Format

Success Response

{
  "id": "char_abc123def456",
  "username": "my_character_2024",
  "display_name": "My Virtual Character",
  "permalink": "https://api.apiyi.com/characters/my_character_2024",
  "profile_picture_url": "https://cdn.apiyi.com/characters/char_abc123def456/profile.jpg"
}

Response Fields

Field	Type	Description
`id`	string	Unique character identifier (Character ID) Can be referenced as `@char_abc123def456` in video generation prompts
`username`	string	Character username (unique) Can be referenced as `@my_character_2024` in video generation prompts
`display_name`	string	Character display name (can be duplicated) For display purposes only, cannot be used for referencing
`permalink`	string	Permanent link to character homepage
`profile_picture_url`	string	URL of character profile picture

Recommended Usage: Use @username in video generation for better readability, e.g., "@my_character_2024 walking in the park"

Pricing

Item	Price	Notes
Character Creation	$0.01 / request	Promotional pricing during beta period

Currently in promotional period with very low pricing. Official pricing may be adjusted. Please follow official announcements.

Using Characters in Video Generation

After creating a character, use it in Sora 2 video generation:

Usage Method

Reference the character in the prompt parameter:

# Method 1: Use @username
prompt = "@my_character_2024 running through a forest, sunlight filtering through leaves"

# Method 2: Use @id
prompt = "@char_abc123def456 playing with a little bird, warm and fun"

Complete Example

import requests

# Configuration
SORA_API_URL = "https://api.apiyi.com/v1/videos"
API_KEY = "YOUR_API_KEY"

# Generate video with character reference
payload = {
    "model": "sora-2",
    "prompt": "@my_character_2024 skateboarding on city streets, bustling commercial district background, sunny day",
    "size": "1280x720",
    "seconds": "10"
}

headers = {
    "Content-Type": "multipart/form-data",
    "Authorization": f"Bearer {API_KEY}"
}

response = requests.post(SORA_API_URL, headers=headers, files=payload)
result = response.json()

print(f"Video Task ID: {result['id']}")

See: Sora 2 Video Generation Documentation

Limitations and Considerations

Critical Limitation - Face Detection: Videos must NOT contain real human faces or obvious human body outlines, otherwise character creation will fail. Use virtual characters, cartoon images, products, objects, or other non-face content.

Success Rate Factors

Factors Affecting Success Rate

Real human faces or bodies in video
Low video quality (blurry, shaky)
Indistinct character features
Instability of iOS reverse engineering technology

Tips to Improve Success Rate

Use clear virtual character videos
Select segments with prominent character features
Ensure stable, shake-free video
Retry if necessary

Video Requirements

Requirement	Description
Maximum Length	15 seconds or less
Recommended Resolution	720p or above
Format	MP4, MOV, and other common formats
Content Restrictions	Must NOT contain real faces, violence, adult content, or other prohibited material
Character Clarity	Character should occupy reasonable screen proportion with distinctive features

Technical Limitations

Since character creation is based on iOS reverse engineering technology, there may be some technical instability. If creation fails, we recommend:

Check if video content meets requirements
Adjust timestamps time range to select clearer segments
Use retry mechanism (2-3 attempts recommended)
Contact technical support if failures persist

Best Practices

Selecting Optimal Video Segments

# Recommended: Prominent character features, stable footage
timestamps = "2,4"  # Select 2-second segment with clear, front-facing character

# Avoid: Occluded character, motion blur
timestamps = "0,1"  # Beginning may have transition effects, unstable

Retry Strategy

def create_character_with_retry(video_url, timestamps, max_retries=3):
    """Retry strategy with exponential backoff"""
    for i in range(max_retries):
        try:
            result = create_character(video_url, timestamps)
            return result
        except Exception as e:
            if i == max_retries - 1:
                raise
            wait_time = 2 ** i  # 2s, 4s, 8s
            print(f"Retry {i+1}/{max_retries}, waiting {wait_time} seconds...")
            time.sleep(wait_time)

Character Management

Maintain a character database:

characters_db = {
    "product_A": {
        "id": "char_abc123",
        "username": "product_a_2024",
        "description": "Product A packaging character",
        "created_at": "2024-01-15"
    },
    "mascot_B": {
        "id": "char_def456",
        "username": "mascot_b_2024",
        "description": "Brand mascot",
        "created_at": "2024-01-16"
    }
}

FAQ

Why does creation fail with 'contains human face' error?

The API has strict restrictions on real human faces. Even AI-generated realistic faces may be detected. Recommended alternatives:

Cartoon/anime-style virtual characters
Products, objects, or other non-human content
Abstract artistic style characters

If you must use humanoid characters, use highly stylized designs.

Do created characters expire?

Once successfully created, characters remain valid long-term and can be used repeatedly in video generation. However, we recommend saving the character’s id and username information.

Can I modify an existing character?

Currently, modifying existing characters is not supported. If adjustments are needed:

Create a new character
Use the new character in new video generations
Old characters remain usable and won’t be deleted

How to improve character consistency in videos?

Explicit Reference: Use @username at the beginning of prompts
Detailed Description: Describe character actions and scenes, but avoid repeating character appearance descriptions

Examples:

✅ Good prompt:
"@my_character running in the park, chasing a butterfly, sunny day"

❌ Poor prompts:
"A red character in the park"  # No character ID reference
"@my_character red body in park"  # Repeating appearance may cause conflicts

How to choose the best timestamps?

Selection tips:

Watch Video: Review entire video to find clearest character segments
Front Angle: Prioritize front-facing or 3/4 angle segments
Good Lighting: Avoid too dark or overexposed segments
No Occlusion: Ensure character is complete and unobstructed
Stable Footage: Avoid rapid movement or camera shake

Testing Method: Try different time ranges and compare results.

Are there limits for batch character creation?

Rate Limits: Follow API request rate limits (see API manual for details)
Concurrency Control: Recommend 3-5 concurrent requests to avoid throttling
Cost Considerations: While current pricing is low ($0.01/request), batch creation still incurs costs

Use the batch creation function in example code, which includes proper concurrency control.

Can characters be used in different Sora models?

After creation, characters are primarily used for Sora 2 video generation. Future support for other Sora series models may be added. Please follow official updates.

Sora 2 Video Generation

Learn how to use characters in video generation

Sora 2 Async API

Batch generate videos with characters

API Manual

Learn about API authentication, request formats, and basics

FAQ

View more frequently asked questions

Basics

Basic API

Video API

Image API

Multimodal Understanding API

Text API

​Overview

​Core Concepts

​Why Use Characters?

​E-commerce Scenarios

Product Characterization

​Animation Scenarios

Virtual Characters

​Other Scenarios

​Endpoint

​Request Parameters

​Parameter Details

​Code Examples

​cURL Example

​Python Examples

​Response Format

​Success Response

​Response Fields

​Pricing

​Using Characters in Video Generation

​Usage Method

​Complete Example

​Limitations and Considerations

​Success Rate Factors

Factors Affecting Success Rate

Tips to Improve Success Rate

​Video Requirements

​Technical Limitations

​Best Practices

​Selecting Optimal Video Segments

​Retry Strategy

​Character Management

​FAQ

​Related Resources

Sora 2 Video Generation

Sora 2 Async API

API Manual

FAQ

Overview

Core Concepts

Why Use Characters?

E-commerce Scenarios

Animation Scenarios

Other Scenarios

Endpoint

Request Parameters

Parameter Details

Code Examples

cURL Example

Python Examples

Response Format

Success Response

Response Fields

Pricing

Using Characters in Video Generation

Usage Method

Complete Example

Limitations and Considerations

Success Rate Factors

Video Requirements

Technical Limitations

Best Practices

Selecting Optimal Video Segments

Retry Strategy

Character Management

FAQ

Related Resources