Sora2 Create Character
Extract characters from video for subsequent video generation
중국 본토 사용자 안내: 중국 본토 사용자는 https://toapis.cn 를 API 엔드포인트(Base URL)로 사용해 주세요. 본 문서의 예시에서 https://toapis.com 을 https://toapis.cn 로 바꿔 주세요.
개요
The Sora2 character creation feature allows you to extract characters from existing videos. Once created, you can reuse the character in subsequent video generations to maintain character consistency.
Important:
- Video must contain audio and identifiable characters
- Time range limit: minimum 1 second, maximum 3 seconds
- Either
urlorfrom_taskis required - must provide one promptparameter is not required in this mode- After creation, the character task ID can be used for subsequent video generation
인증
Authorizationstring헤더필수Bearer Token authentication
Authorization: Bearer YOUR_API_KEYGet your API Key from the API Key Management Page
요청 파라미터
modelstring본문필수기본값: sora-2Video generation model name
Supported models:
sora-2- Standard versionsora-2-pro- Professional version (higher quality)
timestampsstring본문필수Character appearance timestamp range
Unit is seconds, format is "start_second,end_second"
Constraints:
- Time range difference minimum: 1 second
- Time range difference maximum: 3 seconds
Example: "1,3" means the character appearing from second 1 to second 3 in the video
urlstring본문Video URL containing the character to extract
Requirements:
- Video must contain audio
- Video must contain identifiable characters
Note: Either url or from_task required
Example: "https://example.com/my-video.mp4"
from_taskstring본문Task ID of a previously generated video
Create character from an existing video generation task
Note: Either url or from_task required
Example: "task_01KBYT59JDHB4A3KDDR9N9JVWP"
응답 Fields
idstringUnique task identifier for querying character creation status
After completion, this character task ID can be used in video generation via the character_url parameter
objectstringObject type, always generation.task
modelstring모델 name used
statusstringTask status:
queued- Queued for processingin_progress- Processingcompleted- Successfully completedfailed- Failed
progressintegerTask progress percentage (0-100)
created_atintegerTask creation time (Unix timestamp)
completed_atintegerTask completion time (Unix timestamp, only available after completion)
resultobjectCharacter creation result (only available after completion)
Contains created character information such as character ID, name, profile picture, etc.
요청 예시
curl --request POST \
--url https://toapis.com/v1/videos/generations \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "sora-2",
"url": "https://example.com/character-video.mp4",
"timestamps": "1,3"
}'curl --request POST \
--url https://toapis.com/v1/videos/generations \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "sora-2",
"from_task": "task_01KBYT59JDHB4A3KDDR9N9JVWP",
"timestamps": "1,3"
}'import requests
# Create character from video URL
response = requests.post(
"https://toapis.com/v1/videos/generations",
headers={
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"model": "sora-2",
"url": "https://example.com/character-video.mp4",
"timestamps": "1,3"
}
)
task = response.json()
print(f"Task ID: {task['id']}")
print(f"Status: {task['status']}")
# Create character from existing task
response = requests.post(
"https://toapis.com/v1/videos/generations",
headers={
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"model": "sora-2",
"from_task": "task_01KBYT59JDHB4A3KDDR9N9JVWP",
"timestamps": "1,3"
}
)// Create character from video URL
const response = await fetch('https://toapis.com/v1/videos/generations', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'sora-2',
url: 'https://example.com/character-video.mp4',
timestamps: '1,3'
})
});
const task = await response.json();
console.log(`Task ID: ${task.id}`);
console.log(`Status: ${task.status}`);package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)
func main() {
url := "https://toapis.com/v1/videos/generations"
payload := map[string]interface{}{
"model": "sora-2",
"url": "https://example.com/character-video.mp4",
"timestamps": "1,3",
}
jsonData, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}응답 예시
{
"id": "task_01KBYT59JDHB4A3KDDR9N9JVWP",
"object": "generation.task",
"model": "sora-2",
"status": "queued",
"progress": 0,
"created_at": 1703884800,
"metadata": {}
}{
"id": "task_01KC0JZCMTMQ70D68XTM56Q5D0",
"object": "generation.task",
"model": "sora-2",
"status": "completed",
"progress": 100,
"created_at": 1765251461,
"completed_at": 1765251507,
"result": {
"type": "character",
"data": {
"characters": [
{
"id": "ch_6937998961208191a45ef08447a554df",
"display_name": "Turbo Whiskers",
"profile_picture_url": "https://upload.toapis.com/f/image/character_task_xxx.jpg",
"username": "duksvfkf.turbo_whis"
}
]
}
},
"metadata": {}
}{
"error": {
"code": 400,
"message": "Invalid request: timestamps range must be between 1-3 seconds",
"type": "invalid_request_error"
}
}{
"error": {
"code": 401,
"message": "Authentication failed, please check your API key",
"type": "authentication_error"
}
}{
"error": {
"code": 402,
"message": "Insufficient account balance, please top up",
"type": "payment_required"
}
}Usage Flow
Submit Character Creation Request
Call this API with a video URL or existing task ID containing the character, along with the time range
Get Task ID
API returns task ID with status queued or in_progress
Query Task 상태
Use the Query Video Task 상태 API to poll task progress
Use Character in 비디오 생성
After character creation completes, use character_url parameter to reference the character task ID in subsequent video generation
Best Practices
- Choose Clear Character Segments: Select 1-3 second segments where character features are most prominent
- Ensure Video Quality: High-definition video allows better character feature extraction
- Include Audio: Video must contain an audio track
- Avoid Multiple Characters: The selected time range should ideally contain only one main character