ToAPIsToAPIs
Sora2

Sora2 Create Character

Extract characters from video for subsequent video generation

POST
/v1/videos/generations

중국 본토 사용자 안내: 중국 본토 사용자는 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 url or from_task is required - must provide one
  • prompt parameter 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_KEY

Get your API Key from the API Key Management Page

요청 파라미터

modelstring본문필수기본값: sora-2

Video generation model name

Supported models:

  • sora-2 - Standard version
  • sora-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

idstring

Unique task identifier for querying character creation status

After completion, this character task ID can be used in video generation via the character_url parameter

objectstring

Object type, always generation.task

modelstring

모델 name used

statusstring

Task status:

  • queued - Queued for processing
  • in_progress - Processing
  • completed - Successfully completed
  • failed - Failed
progressinteger

Task progress percentage (0-100)

created_atinteger

Task creation time (Unix timestamp)

completed_atinteger

Task completion time (Unix timestamp, only available after completion)

resultobject

Character 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

  1. Choose Clear Character Segments: Select 1-3 second segments where character features are most prominent
  2. Ensure Video Quality: High-definition video allows better character feature extraction
  3. Include Audio: Video must contain an audio track
  4. Avoid Multiple Characters: The selected time range should ideally contain only one main character