Skip to main content
Base URL: https://api.yelinai.com/sora/v1/characters Price: $0.01/call Model: sora-2-character

​
Introduction

Sora 2 Character feature allows you to extract characters (people, pets, objects, etc.) from videos and create reusable character identities. Once created, you can reference the character using @username syntax in subsequent video generation, maintaining consistent appearance and traits.

​
Character Extraction

Extract character from video clips

​
Reusable

Create once, use multiple times

​
Consistency

Maintain consistent appearance and traits

​
Low Cost

Only $0.01/call

​
Prerequisites

1 Get API Key Log in to laozhang.ai console to obtain your API key 2 Prepare Video Source Prepare a video containing the character you want to extract:
  • Video URL (publicly accessible)
  • Completed Sora video task ID

​
Quick Start

​
1. Create Character from Video URL

curl Python JavaScript 
curl https://api.yelinai.com/sora/v1/characters \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "sora-2-character",
    "url": "https://example.com/your-video.mp4",
    "timestamps": "1,3"
  }'

​
2. Create Character from Task ID

If you’ve already generated a video through the Sora API, you can use the task ID directly: curl Python 
curl https://api.yelinai.com/sora/v1/characters \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "sora-2-character",
    "from_task": "video_8a06e19b-408b-4cf1-9b70-9d25c4843451",
    "timestamps": "1,3"
  }'

​
API Reference

​
Endpoint

POST https://api.yelinai.com/sora/v1/characters

​
Request Parameters

ParameterTypeRequiredDescription
modelstring✓Fixed value: "sora-2-character"
urlstringEitherVideo URL (publicly accessible) containing the character
from_taskstringEitherCompleted Sora video task ID
timestampsstring✓Time range where character appears (seconds), format: "start,end", e.g., "1,3"
timestamps Explanation
  • Format: "start_second,end_second", e.g., "1,3" means from 1st to 3rd second of the video
  • Time range: minimum 1 second, maximum 3 seconds
  • Ensure the character is clearly visible within the specified time range
Either url or from_task must be provided, but not both.

​
Response Fields

FieldTypeDescription
idstringUnique character identifier, starts with ch_
usernamestringCharacter username for @ reference
display_namestringCharacter display name
permalinkstringCharacter link on Sora platform
profile_picture_urlstringCharacter avatar URL

​
Response Example

{
  "id": "ch_6940d0068884819191a38537b5f48e10",
  "username": "ae27a25bd.dairymuse",
  "display_name": "Daisy the Dairy Muse",
  "permalink": "https://sora.chatgpt.com/profile/ae27a25bd.dairymuse",
  "profile_picture_url": "https://mycdn-gg.oss-us-west-1.aliyuncs.com/sora/95f24b0e-ffd6-43ce-83b8-5575b07d2efc.jpg"
}

​
Using Characters in Videos

After creating a character, you can reference it using @username syntax in your video generation prompts.

​
Usage Example

Python - Sync API Python - Async API 
import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.yelinai.com/v1"
)

# Reference created character using @username
response = client.chat.completions.create(
    model="sora_video2",
    messages=[
        {
            "role": "user",
            "content": "@ae27a25bd.dairymuse running happily in a sunny meadow"
        }
    ]
)

print(response.choices[0].message.content)
Prompt TipsWhen using characters, describe the character’s actions, scene, and atmosphere after @username, for example:
  • @username reading a book in a coffee shop
  • @username walking on the beach at sunset
  • @username working in an office, focused and concentrated

​
Complete Workflow Example

Here’s a complete workflow from video generation to character creation to character reuse: 
import requests
import openai
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.yelinai.com"

# Step 1: Generate initial video (Async API)
print("Step 1: Generating initial video...")
video_response = requests.post(
    f"{BASE_URL}/v1/videos",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}"
    },
    json={
        "model": "sora-2",
        "prompt": "A cute cartoon character dancing",
        "size": "1280x720",
        "seconds": "10"
    }
)
task = video_response.json()
task_id = task["id"]
print(f"Video task ID: {task_id}")

# Step 2: Wait for video generation to complete
print("Step 2: Waiting for video generation...")
while True:
    status_response = requests.get(
        f"{BASE_URL}/v1/videos/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    status = status_response.json()
    if status["status"] == "completed":
        print("Video generation complete!")
        break
    elif status["status"] == "failed":
        print("Video generation failed")
        exit(1)
    time.sleep(10)

# Step 3: Create character from video
print("Step 3: Creating character...")
character_response = requests.post(
    f"{BASE_URL}/sora/v1/characters",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}"
    },
    json={
        "model": "sora-2-character",
        "from_task": task_id,
        "timestamps": "1,3"
    }
)
character = character_response.json()
username = character["username"]
print(f"Character created! Username: @{username}")

# Step 4: Generate new video with character
print("Step 4: Generating new video with character...")
new_video_response = requests.post(
    f"{BASE_URL}/v1/videos",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}"
    },
    json={
        "model": "sora-2",
        "prompt": f"@{username} performing on stage, audience cheering",
        "size": "1280x720",
        "seconds": "10"
    }
)
new_task = new_video_response.json()
print(f"New video task ID: {new_task['id']}")

​
FAQ

What are the timestamps limitations?
  • Minimum range: 1 second (e.g., "1,2")
  • Maximum range: 3 seconds (e.g., "1,4")
  • Ensure the character is clearly visible within the specified time range
  • Choose clips where the character is front-facing with good lighting
What types of characters can be created? You can extract various types of characters from videos:
  • Human characters
  • Animals/pets
  • Cartoon characters
  • AI-generated virtual characters
  • Objects/props
How many times can a character be reused? Created characters have no usage limit and can be reused in any number of video generations. How to get the best character extraction results? Recommendations:
  • Choose video clips where the character is clearly visible
  • Ensure good lighting conditions
  • Select frames showing the character’s front or clear side view
  • Avoid clips where the character is obscured or blurry

​
Pricing

OperationPrice
Create character$0.01/call
Generate video with characterCharged at video generation price (from $0.15/call)
Character creation is billed per call at only $0.01. When generating videos with characters, standard video generation pricing applies.

​
Async API

Recommended for video generation

​
Model Pricing

View complete pricing details

​
Code Examples

View more code examples

​
FAQ

Solve common issues