Полное руководство по Character API в Sora 2: 2 метода создания переиспользуемых персонажей и обеспечения согласованности персонажей между видео

Sora 2 Character API 两种角色创建方法详解

方法一：通过视频 URL 创建角色

这是最直接的方法——你已经有一个托管在公开 URL 上的视频，想从中提取角色。

核心参数说明

完整代码示例

import requests
import json

# API 配置（推荐使用 APIYI 中转服务）
API_KEY = "your_api_key_here"  # 在 apiyai.com 获取
BASE_URL = "https://api.apiyai.com/v1"  # APIYI 中转地址

# 请求头
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# 请求体：从视频 URL 提取角色
payload = {
    "model": "sora-2-character",
    "url": "https://cdn.example.com/my-video.mp4",  # 你的视频 URL
    "timestamps": "5,8"  # 提取 5-8 秒之间的角色
}

# 发送 POST 请求
response = requests.post(
    f"{BASE_URL}/sora/v1/characters",
    headers=headers,
    json=payload
)

# 解析响应
if response.status_code == 200:
    result = response.json()
    character_id = result.get("id")  # 获取角色 ID
    print(f"✅ 角色创建成功！")
    print(f"角色 ID: {character_id}")
    print(f"完整响应: {json.dumps(result, indent=2, ensure_ascii=False)}")
else:
    print(f"❌ 请求失败: {response.status_code}")
    print(f"错误信息: {response.text}")

timestamps 参数使用技巧

timestamps 参数定义角色在视频中的出现时间段，格式为 "开始秒,结束秒"：

# 示例 1: 提取 5-8 秒之间的角色
"timestamps": "5,8"

# 示例 2: 提取 2.5-6.3 秒之间的角色（支持小数）
"timestamps": "2.5,6.3"

# 示例 3: 提取 0-3 秒之间的角色
"timestamps": "0,3"

# 示例 4: 不指定（API 自动选择最佳时间段）
# "timestamps": None  # 可以不传递这个参数

最佳实践：

• ✅ 选择角色清晰、正面、光线充足的时间段
• ✅ 时间段建议 3-10 秒，太短可能特征不完整，太长浪费资源
• ✅ 避免选择角色被遮挡、模糊、背影的片段
• ❌ 不要选择多个角色同时出现的时间段（会混淆）

方法二：通过任务 ID 复用角色

如果你刚刚生成了一个视频（通过 Sora 2 API），可以直接从该任务 ID 中提取角色，无需等待视频下载或上传到 CDN。

核心参数说明

完整代码示例

import requests
import json

# API 配置
API_KEY = "your_api_key_here"
BASE_URL = "https://api.apiyai.com/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# 假设你刚刚生成了一个视频，获得了任务 ID
video_task_id = "video_f751ab9c4e2d4b8a9e1f2c3d4e5f6a7b"

# 请求体：从任务 ID 提取角色
payload = {
    "model": "sora-2-character",
    "from_task": video_task_id,  # 直接引用任务 ID
    "timestamps": "5,8"
}

response = requests.post(
    f"{BASE_URL}/sora/v1/characters",
    headers=headers,
    json=payload
)

if response.status_code == 200:
    result = response.json()
    character_id = result.get("id")
    print(f"✅ 角色从任务 {video_task_id} 中提取成功！")
    print(f"角色 ID: {character_id}")
else:
    print(f"❌ 请求失败: {response.status_code}")
    print(f"错误信息: {response.text}")

典型应用场景

# 完整工作流示例：生成视频 → 提取角色 → 复用角色

import time

# 步骤 1: 生成第一个视频
video_payload = {
    "model": "sora-2.0-turbo",
    "prompt": "一位年轻女性在咖啡店里微笑，阳光透过窗户照射进来",
    "duration": 10
}

video_response = requests.post(
    f"{BASE_URL}/sora/v1/generations",
    headers=headers,
    json=video_payload
)

video_task_id = video_response.json().get("id")
print(f"📹 视频生成任务已创建: {video_task_id}")

# 等待视频生成完成（实际应用中应使用轮询或 webhook）
time.sleep(60)  # 简化示例，实际需要检查任务状态

# 步骤 2: 从刚生成的视频中提取角色
character_payload = {
    "model": "sora-2-character",
    "from_task": video_task_id,
    "timestamps": "3,6"
}

char_response = requests.post(
    f"{BASE_URL}/sora/v1/characters",
    headers=headers,
    json=character_payload
)

character_id = char_response.json().get("id")
print(f"👤 角色已提取: {character_id}")

# 步骤 3: 使用该角色生成新视频
new_video_payload = {
    "model": "sora-2.0-turbo",
    "prompt": f"@{character_id} 在海滩上奔跑，夕阳西下",
    "duration": 10
}

new_video_response = requests.post(
    f"{BASE_URL}/sora/v1/generations",
    headers=headers,
    json=new_video_payload
)

print(f"🎬 新视频生成任务: {new_video_response.json().get('id')}")
print("✨ 角色在新场景中保持一致！")

两种方法对比与选择

选择建议：

• 如果你在一个连续的创作流程中（生成视频 → 提取角色 → 再生成视频），优先使用方法二
• 如果你要从已有视频库或外部素材中提取角色，使用方法一

返回数据结构解析

无论使用哪种方法，API 的响应格式都是相同的：

{
  "id": "char_abc123xyz789def",
  "object": "character",
  "created_at": 1704096000,
  "source": {
    "type": "url",  // 或 "task_id"
    "value": "https://cdn.example.com/video.mp4",  // 或任务 ID
    "timestamps": "5,8"
  },
  "metadata": {
    "gender": "female",
    "age_range": "25-35",
    "dominant_features": [
      "long_hair",
      "casual_clothing",
      "warm_smile"
    ]
  }
}

关键字段说明

实战案例：创建品牌 IP 系列视频

假设你要为一家咖啡品牌创建 3 支广告视频，使用同一个品牌代言人：

import requests
import json
import time

API_KEY = "your_api_key_here"
BASE_URL = "https://api.apiyai.com/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# 场景 1: 生成第一支广告（早晨场景）
print("📹 正在生成第一支广告...")
video1 = requests.post(
    f"{BASE_URL}/sora/v1/generations",
    headers=headers,
    json={
        "model": "sora-2.0-turbo",
        "prompt": "一位时尚的年轻女性在咖啡店，清晨阳光洒在桌上，她举起咖啡杯微笑",
        "duration": 8
    }
).json()

video1_id = video1["id"]
print(f"✅ 任务 ID: {video1_id}")

# 等待视频生成（实际应用中用轮询）
time.sleep(90)

# 提取品牌代言人角色
print("👤 正在提取品牌代言人...")
character = requests.post(
    f"{BASE_URL}/sora/v1/characters",
    headers=headers,
    json={
        "model": "sora-2-character",
        "from_task": video1_id,
        "timestamps": "2,5"  # 选择代言人最清晰的 3 秒
    }
).json()

character_id = character["id"]
print(f"✅ 品牌代言人 ID: {character_id}")

# 场景 2: 使用同一代言人拍摄办公室场景
print("🎬 正在生成第二支广告（办公室）...")
video2 = requests.post(
    f"{BASE_URL}/sora/v1/generations",
    headers=headers,
    json={
        "model": "sora-2.0-turbo",
        "prompt": f"@{character_id} 在现代办公室，对着电脑工作，桌上放着咖啡",
        "duration": 8
    }
).json()
print(f"✅ 办公室场景任务: {video2['id']}")

# 场景 3: 使用同一代言人拍摄傍晚场景
print("🎬 正在生成第三支广告（傍晚）...")
video3 = requests.post(
    f"{BASE_URL}/sora/v1/generations",
    headers=headers,
    json={
        "model": "sora-2.0-turbo",
        "prompt": f"@{character_id} 在城市天台，夕阳余晖中享受咖啡时光",
        "duration": 8
    }
).json()
print(f"✅ 天台场景任务: {video3['id']}")

print("\n🎉 3 支广告均使用同一品牌代言人，保证视觉一致性！")

常见错误与解决方案

错误 1: Invalid timestamps format

{
  "error": {
    "message": "timestamps must be in 'start,end' format",
    "type": "invalid_request_error"
  }
}

原因: timestamps 参数格式不正确

解决方案:

# ❌ 错误写法
"timestamps": "5-8"        # 不能用连字符
"timestamps": "5, 8"       # 不能有空格
"timestamps": ["5", "8"]   # 不能用数组

# ✅ 正确写法
"timestamps": "5,8"        # 逗号分隔，无空格
"timestamps": "2.5,6.3"    # 支持小数

错误 2: Video not accessible

{
  "error": {
    "message": "Unable to access video from provided URL",
    "type": "invalid_request_error"
  }
}

原因: 视频 URL 不可访问或需要认证

解决方案:

• 确保 URL 是公开访问的（不需要登录）
• 使用 CDN 直链，不要用短链或重定向 URL
• 测试 URL 能否在浏览器匿名模式下直接打开

错误 3: Task not found

{
  "error": {
    "message": "Video generation task not found",
    "type": "invalid_request_error"
  }
}

原因: 使用的任务 ID 不存在或已过期

解决方案:

# 确保任务 ID 正确且有效
# 任务 ID 格式通常为: video_xxxxxxxxxxxx

# 先查询任务状态
status_response = requests.get(
    f"{BASE_URL}/sora/v1/generations/{video_task_id}",
    headers=headers
)

if status_response.json().get("status") == "completed":
    # 任务完成后再创建角色
    character_response = requests.post(...)

timestamps 参数最佳实践

场景 1: 单人特写镜头

# 选择角色正面、表情清晰的时间段
"timestamps": "3,6"  # 3 秒足够捕捉特征

场景 2: 运动镜头

# 选择角色稳定出现的时间段
"timestamps": "5,10"  # 5 秒确保捕捉多个角度

场景 3: 多角色场景

# 选择目标角色独自出镜的时间段
"timestamps": "2,4"  # 避开其他角色出现的时间

场景 4: 自动选择（不推荐新手）

# 不传 timestamps，让 API 自动选择
# 但可能选到不理想的片段
payload = {
    "model": "sora-2-character",
    "url": "https://cdn.example.com/video.mp4"
    # 不传 timestamps
}

完整工作流模板

这是一个可直接使用的完整代码模板，整合了错误处理和状态轮询：

import requests
import json
import time

class SoraCharacterClient:
    def __init__(self, api_key, base_url="https://api.apiyai.com/v1"):
        self.api_key = api_key
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
    
    def create_character_from_url(self, video_url, timestamps=None):
        """从视频 URL 创建角色"""
        payload = {
            "model": "sora-2-character",
            "url": video_url
        }
        if timestamps:
            payload["timestamps"] = timestamps
        
        response = requests.post(
            f"{self.base_url}/sora/v1/characters",
            headers=self.headers,
            json=payload
        )
        
        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"角色创建失败: {response.text}")
    
    def create_character_from_task(self, task_id, timestamps=None):
        """从任务 ID 创建角色"""
        payload = {
            "model": "sora-2-character",
            "from_task": task_id
        }
        if timestamps:
            payload["timestamps"] = timestamps
        
        response = requests.post(
            f"{self.base_url}/sora/v1/characters",
            headers=self.headers,
            json=payload
        )
        
        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"角色创建失败: {response.text}")
    
    def generate_video(self, prompt, duration=10):
        """生成视频"""
        payload = {
            "model": "sora-2.0-turbo",
            "prompt": prompt,
            "duration": duration
        }
        
        response = requests.post(
            f"{self.base_url}/sora/v1/generations",
            headers=self.headers,
            json=payload
        )
        
        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"视频生成失败: {response.text}")
    
    def wait_for_completion(self, task_id, max_wait=300):
        """等待任务完成"""
        start_time = time.time()
        while time.time() - start_time < max_wait:
            response = requests.get(
                f"{self.base_url}/sora/v1/generations/{task_id}",
                headers=self.headers
            )
            
            if response.status_code == 200:
                status = response.json().get("status")
                if status == "completed":
                    return response.json()
                elif status == "failed":
                    raise Exception("任务失败")
            
            time.sleep(10)
        
        raise Exception("等待超时")

# 使用示例
if __name__ == "__main__":
    # 初始化客户端
    client = SoraCharacterClient(api_key="your_api_key_here")
    
    # 方法一：从 URL 创建角色
    print("📹 方法一：从视频 URL 创建角色")
    character1 = client.create_character_from_url(
        video_url="https://cdn.example.com/video.mp4",
        timestamps="5,8"
    )
    print(f"✅ 角色 ID: {character1['id']}")
    
    # 方法二：生成视频并提取角色
    print("\n📹 方法二：生成视频并提取角色")
    video = client.generate_video(
        prompt="一位年轻男性在公园里散步，阳光明媚",
        duration=10
    )
    video_id = video["id"]
    print(f"视频任务: {video_id}")
    
    # 等待视频完成
    completed_video = client.wait_for_completion(video_id)
    print("✅ 视频生成完成")
    
    # 从该视频提取角色
    character2 = client.create_character_from_task(
        task_id=video_id,
        timestamps="3,7"
    )
    print(f"✅ 角色 ID: {character2['id']}")
    
    # 使用角色生成新视频
    print("\n🎬 使用提取的角色生成新视频")
    new_video = client.generate_video(
        prompt=f"@{character2['id']} 在咖啡店里看书，氛围温馨",
        duration=10
    )
    print(f"✅ 新视频任务: {new_video['id']}")

总结与下一步

恭喜你！现在你已经掌握了 Sora 2 Character API 的两种核心使用方法：

✅ 方法一: 从已有视频 URL 提取角色特征
✅ 方法二: 从刚生成的任务 ID 中直接复用角色
✅ 理解 timestamps 参数的正确使用方式
✅ 能够构建完整的角色一致性视频工作流

推荐下一步学习:

1. 尝试创建你的第一个品牌 IP 角色
2. 探索角色在不同场景、光线、角度下的一致性表现
3. 结合 Sora 2 Remix API 实现更复杂的角色互动场景

关于 APIYI (apiyai.com)
本文所有示例代码均兼容 APIYI 的 Sora 2 API 中转服务，你可以：

• 🎁 免费试用额度，快速上手
• 💰 价格比官方更实惠
• 🚀 国内访问更稳定快速
• 📚 中文技术支持和文档

开始你的 AI 视频创作之旅吧！🎬

Sora 2 Character API: два метода создания персонажа

Метод 1: Извлечение персонажа из видео по URL

Это самый прямой способ, подходящий для случаев, когда у вас уже есть готовый видеоматериал.

Описание параметров запроса:

Полный пример запроса:

curl https://api.apiyi.com/sora/v1/characters \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "sora-2-character",
    "url": "https://your-cdn.com/video/character-source.mp4",
    "timestamps": "5,8"
  }'

⚠️ Важные моменты:

1. URL видео должен быть публично доступен: серверы OpenAI должны иметь возможность прочитать это видео
2. Настройте CDN для глобального доступа: если используете OSS/CDN, убедитесь в настройке глобального ускорения, чтобы избежать проблем с доступом для серверов OpenAI (обычно находятся за рубежом)
3. Временной диапазон timestamps:
   • Минимальная разница: 1 секунда
   • Максимальная разница: 3 секунды
   • Пример: "5,8" означает с 5-й по 8-ю секунду видео

Метод 2: Повторное использование персонажа через ID задачи

Если вы ранее генерировали видео через Sora 2 API, можете напрямую использовать ID задачи этого видео для извлечения персонажа, без повторной загрузки видео.

Описание параметров запроса:

Полный пример запроса:

curl https://api.apiyi.com/sora/v1/characters \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "sora-2-character",
    "from_task": "video_f751abfd-87a9-46e2-9236-1d94743c5e3e",
    "timestamps": "5,8"
  }'

Преимущества этого подхода:

• ✅ Не требуется дополнительная загрузка видео, экономия трафика
• ✅ Прямое повторное использование уже созданных видеоматериалов
• ✅ Более плавный рабочий процесс, подходит для массовой обработки
• ✅ Исключение проблем с истечением срока действия URL или доступом к видео

Рекомендация: Обращайтесь к Sora 2 Character API через платформу APIYI (apiyi.com), которая предоставляет стабильный сервис подключения и бесплатную тестовую квоту.

Сравнение двух методов Sora 2 Character API

Как выбрать подходящий метод?

Выбирайте метод через URL видео:

• У вас есть готовый видеоматериал (например, отснятое живое видео, скачанное с других платформ)
• Нужно извлечь персонажа из видео, не созданного через Sora

Выбирайте метод через ID задачи:

• Вы используете Sora 2 API для массового создания видео
• Хотите извлечь персонажа из уже созданного видео для последующих роликов серии
• Стремитесь к более плавному автоматизированному рабочему процессу

Подробное объяснение параметра timestamps в Character API Sora 2

timestamps — это ключевой параметр Character API, который определяет, из какого временного отрезка видео извлекать персонажа.

Правила формата timestamps

Советы по настройке timestamps

1. Выбирайте фрагменты, где персонаж четко виден: Персонаж должен полностью присутствовать в кадре, без перекрытий
2. Избегайте фрагментов с быстрым движением: Выбирайте временные отрезки, где персонаж относительно статичен или движется медленно
3. Обеспечьте хорошее освещение: Фрагменты с хорошим освещением позволяют извлечь более точные характеристики персонажа
4. Приоритет фронтальным ракурсам: По возможности выбирайте фрагменты, где персонаж обращен к камере

Пример сценария:

Допустим, у вас есть 10-секундное видео, где персонаж появляется фронтально на 2-4 секунде, а на 6-9 секунде движется боком:

// Рекомендуется: выбирайте фрагмент с четким фронтальным видом
{
  "timestamps": "2,4"
}

// Не рекомендуется: персонаж в профиль и в движении
{
  "timestamps": "6,9"
}

Полный рабочий процесс с Character API Sora 2

Пример кода на Python

import requests
import time

# Настройка APIYI интерфейса
API_BASE = "https://api.apiyi.com/sora/v1"
API_KEY = "sk-your-api-key"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

def create_character_from_url(video_url: str, timestamps: str) -> dict:
    """Способ 1: Создание персонажа из URL видео"""
    response = requests.post(
        f"{API_BASE}/characters",
        headers=headers,
        json={
            "model": "sora-2-character",
            "url": video_url,
            "timestamps": timestamps
        }
    )
    return response.json()

def create_character_from_task(task_id: str, timestamps: str) -> dict:
    """Способ 2: Создание персонажа из ID задачи"""
    response = requests.post(
        f"{API_BASE}/characters",
        headers=headers,
        json={
            "model": "sora-2-character",
            "from_task": task_id,
            "timestamps": timestamps
        }
    )
    return response.json()

# Примеры использования
# Способ 1: Создание из URL видео
result1 = create_character_from_url(
    video_url="https://your-cdn.com/video/hero.mp4",
    timestamps="5,8"
)
print(f"Задача создания персонажа: {result1}")

# Способ 2: Создание из ID задачи
result2 = create_character_from_task(
    task_id="video_f751abfd-87a9-46e2-9236-1d94743c5e3e",
    timestamps="2,4"
)
print(f"Задача создания персонажа: {result2}")

import requests
import time

API_BASE = "https://api.apiyi.com/sora/v1"
API_KEY = "sk-your-api-key"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

def create_character(video_url: str, timestamps: str) -> str:
    """Создает персонажа и возвращает ID персонажа"""
    # 1. Отправляем запрос на создание персонажа
    response = requests.post(
        f"{API_BASE}/characters",
        headers=headers,
        json={
            "model": "sora-2-character",
            "url": video_url,
            "timestamps": timestamps
        }
    )
    task_data = response.json()
    task_id = task_data.get("task_id")

    # 2. Периодически проверяем статус задачи
    while True:
        status_response = requests.get(
            f"{API_BASE}/characters/{task_id}",
            headers=headers
        )
        status_data = status_response.json()

        if status_data.get("status") == "completed":
            return status_data.get("character_id")
        elif status_data.get("status") == "failed":
            raise Exception(f"Ошибка создания персонажа: {status_data}")

        time.sleep(5)  # Проверяем каждые 5 секунд

def generate_video_with_character(prompt: str, character_id: str) -> str:
    """Генерирует видео с использованием персонажа"""
    # Ссылаемся на персонажа в промпте через @character_id
    full_prompt = f"@{character_id} {prompt}"

    response = requests.post(
        f"{API_BASE}/videos",
        headers=headers,
        json={
            "model": "sora-2",
            "prompt": full_prompt,
            "duration": 8,
            "resolution": "1080p"
        }
    )
    return response.json()

# Пример полного процесса
if __name__ == "__main__":
    # Шаг 1: Создаем персонажа
    character_id = create_character(
        video_url="https://your-cdn.com/video/hero.mp4",
        timestamps="5,8"
    )
    print(f"Персонаж успешно создан, ID: {character_id}")

    # Шаг 2: Используем персонажа для генерации серии видео
    scenes = [
        "walking through a futuristic city at night",
        "sitting in a coffee shop, reading a book",
        "running on a beach at sunset"
    ]

    for i, scene in enumerate(scenes):
        result = generate_video_with_character(scene, character_id)
        print(f"Задача генерации видео {i+1}: {result}")

Подсказка: Подключайтесь к Sora 2 Character API через платформу APIYI apiyi.com — здесь вы получите полный функционал управления персонажами и техническую поддержку.

Часто задаваемые вопросы

@char_abc123xyz идёт по футуристическому городу в мерцании неоновых огней

Резюме

Ключевые моменты работы с Sora 2 Character API:

1. Два способа создания: извлечение из видео по URL и повторное использование через ID задачи — гибкость для разных сценариев
2. Параметр timestamps: временной диапазон 1-3 секунды, выбирайте фрагмент, где персонаж чётко виден
3. Повторное использование персонажа: создайте один раз — используйте в разных видео, сохраняя единообразие персонажа
4. Настройка CDN: при использовании метода с URL видео убедитесь в глобальной доступности

Освоив Character API, вы сможете:

• Создавать многоразовых виртуальных персонажей для брендовых IP
• Производить серии видеоконтента с единообразными персонажами
• Реализовывать профессиональное последовательное повествование в видео

Рекомендуем подключиться к Sora 2 Character API через APIYI apiyi.com — платформа предоставляет стабильный сервис и бесплатные тестовые кредиты, что поможет вам быстро освоить функционал создания персонажей.

📚 Справочные материалы

⚠️ О формате ссылок: Все внешние ссылки представлены в формате Название: domain.com для удобства копирования, но не кликабельны — это помогает избежать утечки SEO-веса.

1. Официальный релиз OpenAI Sora 2: Обзор функций и возможностей Sora 2

   • Ссылка: openai.com/index/sora-2/
   • Описание: Официальная информация о Sora 2 и функционале персонажей

2. Центр помощи OpenAI — функция Characters: Руководство по созданию и использованию персонажей

   • Ссылка: help.openai.com/en/articles/12435986-generating-content-with-characters
   • Описание: Официальная инструкция по работе с персонажами

3. Документация OpenAI API — Video Generation: Техническая документация Sora API

   • Ссылка: platform.openai.com/docs/guides/video-generation
   • Описание: Спецификации API-интерфейса и описание параметров

4. Страница OpenAI Sora Characters: Презентация функционала персонажей

   • Ссылка: openai.com/sora/characters/
   • Описание: Позиционирование продукта и сценарии использования персонажей

Автор: Техническая команда
Обсуждение: Приглашаем к дискуссии в комментариях. Больше материалов — в техническом сообществе APIYI apiyi.com