> ## Documentation Index > Fetch the complete documentation index at: https://docs.yelinai.com/llms.txt > Use this file to discover all available pages before exploring further. # Character Creation API > Create reusable characters from videos and use them in future video generation via @username **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](https://api.yelinai.com) 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 Tips**When 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. ## Related Links ## Async API Recommended for video generation ## Model Pricing View complete pricing details ## Code Examples View more code examples ## FAQ Solve common issues