Character Creation API

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 YeLIn 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

Parameter	Type	Required	Description
`model`	string	✓	Fixed value: `"sora-2-character"`
`url`	string	Either	Video URL (publicly accessible) containing the character
`from_task`	string	Either	Completed Sora video task ID
`timestamps`	string	✓	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

Field	Type	Description
`id`	string	Unique character identifier, starts with `ch_`
`username`	string	Character username for `@` reference
`display_name`	string	Character display name
`permalink`	string	Character link on Sora platform
`profile_picture_url`	string	Character 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

Operation	Price
Create character	$0.01/call
Generate video with character	Charged 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

Model Pricing

View complete pricing details

Code Examples

View more code examples

FAQ

Solve common issues

​Introduction

​Character Extraction

​Reusable

​Consistency

​Low Cost

​Prerequisites

​Quick Start

​1. Create Character from Video URL

​2. Create Character from Task ID

​API Reference

​Endpoint

​Request Parameters

​Response Fields

​Response Example

​Using Characters in Videos

​Usage Example

​Complete Workflow Example

​FAQ

​Pricing

​Related Links

​Async API

​Model Pricing

​Code Examples