|

Sora 2 Character API 完全教程：2 种方法创建可复用角色，实现跨视频角色一致性

ByAPIYI - Stable and affordable AI API

方法一：从视频 URL 提取角色

这是最常用的方法，适用于你已经有一个视频 URL（可以是 Sora 生成的，也可以是上传的视频），想要从中提取特定角色。

基本用法

import requests

url = "https://api.openai.com/v1/sora/v1/characters"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "model": "sora-2-character",
    "url": "https://cdn.openai.com/sora/videos/your-video.mp4",
    "timestamps": "5,8"  # 关键参数：指定角色出现的时间段
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

# 获取角色 ID
character_id = result['character_id']
print(f"角色 ID: {character_id}")

timestamps 参数详解

timestamps 是这个方法的核心参数，用于告诉 API "在视频的哪个时间段提取角色"。

格式要求：

  • 使用逗号分隔的两个数字，表示起始和结束时间（单位：秒）
  • 例如 "5,8" 表示从第 5 秒到第 8 秒
  • 确保这个时间段内角色清晰可见

选择时间段的技巧：

# ❌ 不好的选择：角色只是一闪而过
"timestamps": "1,1.5"  # 时间太短，可能提取不到足够特征

# ❌ 不好的选择：角色被遮挡或模糊
"timestamps": "10,12"  # 如果这段时间角色背对镜头或被遮挡

# ✅ 好的选择：角色正面清晰，持续时间足够
"timestamps": "5,8"  # 3秒的正面清晰镜头

# ✅ 好的选择：角色特征明显的时刻
"timestamps": "15,18"  # 角色特写镜头

实战建议：

def extract_character_from_url(video_url, start_time, end_time):
    """
    从视频 URL 提取角色
    
    参数：
        video_url: 视频地址
        start_time: 开始时间（秒）
        end_time: 结束时间（秒）
    
    返回：
        character_id: 角色 ID
    """
    # 验证时间参数
    if end_time - start_time < 2:
        print("警告：时间段太短，建议至少 2-3 秒")
    
    if end_time - start_time > 10:
        print("提示：时间段较长，API 会自动选择最佳帧")
    
    data = {
        "model": "sora-2-character",
        "url": video_url,
        "timestamps": f"{start_time},{end_time}"
    }
    
    response = requests.post(
        "https://api.openai.com/v1/sora/v1/characters",
        headers={
            "Authorization": "Bearer YOUR_API_KEY",
            "Content-Type": "application/json"
        },
        json=data
    )
    
    result = response.json()
    
    if 'character_id' in result:
        print(f"✓ 角色提取成功！ID: {result['character_id']}")
        return result['character_id']
    else:
        print(f"✗ 提取失败：{result}")
        return None

# 使用示例
character_id = extract_character_from_url(
    video_url="https://cdn.openai.com/sora/videos/hero.mp4",
    start_time=5,
    end_time=8
)

方法二：从任务 ID 复用角色

如果你刚用 Sora 生成了一个视频（有任务 ID），想要直接从这个任务中提取角色，不需要等视频 URL 生成，可以使用这个方法。

基本用法

import requests

url = "https://api.openai.com/v1/sora/v1/characters"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "model": "sora-2-character",
    "from_task": "video_f751ab9c12345",  # 刚生成视频的任务 ID
    "timestamps": "5,8"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

character_id = result['character_id']
print(f"角色 ID: {character_id}")

完整工作流示例

这个方法特别适合"生成视频 → 立即提取角色 → 用于下一个视频"的连续工作流：

import requests
import time

class SoraCharacterWorkflow:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.openai.com/v1"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
    
    def generate_video(self, prompt):
        """步骤 1: 生成视频"""
        response = requests.post(
            f"{self.base_url}/sora/v1/generations",
            headers=self.headers,
            json={
                "model": "sora-2-latest",
                "prompt": prompt,
                "duration": 10
            }
        )
        
        result = response.json()
        task_id = result['id']
        print(f"✓ 视频生成任务创建：{task_id}")
        
        # 等待视频生成完成
        while True:
            status_response = requests.get(
                f"{self.base_url}/sora/v1/generations/{task_id}",
                headers=self.headers
            )
            status = status_response.json()
            
            if status['status'] == 'completed':
                print(f"✓ 视频生成完成")
                return task_id
            elif status['status'] == 'failed':
                print(f"✗ 视频生成失败")
                return None
            
            print(f"等待中... 状态: {status['status']}")
            time.sleep(5)
    
    def extract_character(self, task_id, start_time, end_time):
        """步骤 2: 从任务 ID 提取角色"""
        response = requests.post(
            f"{self.base_url}/sora/v1/characters",
            headers=self.headers,
            json={
                "model": "sora-2-character",
                "from_task": task_id,
                "timestamps": f"{start_time},{end_time}"
            }
        )
        
        result = response.json()
        character_id = result.get('character_id')
        
        if character_id:
            print(f"✓ 角色提取成功：{character_id}")
            return character_id
        else:
            print(f"✗ 角色提取失败：{result}")
            return None
    
    def generate_with_character(self, prompt, character_id):
        """步骤 3: 使用角色 ID 生成新视频"""
        # 在提示词中包含角色 ID
        full_prompt = f"{prompt} @{character_id}"
        
        response = requests.post(
            f"{self.base_url}/sora/v1/generations",
            headers=self.headers,
            json={
                "model": "sora-2-latest",
                "prompt": full_prompt,
                "duration": 10
            }
        )
        
        result = response.json()
        print(f"✓ 使用角色的新视频任务创建：{result['id']}")
        return result['id']

# 使用示例
workflow = SoraCharacterWorkflow("YOUR_API_KEY")

# 1. 生成包含角色的视频
print("=== 步骤 1: 生成角色视频 ===")
task_id = workflow.generate_video(
    "A young woman with long dark hair walking in a park"
)

# 2. 从任务中提取角色
print("\n=== 步骤 2: 提取角色 ===")
character_id = workflow.extract_character(
    task_id=task_id,
    start_time=3,
    end_time=7
)

# 3. 在新场景中使用该角色
print("\n=== 步骤 3: 在新场景中使用角色 ===")
new_task_id = workflow.generate_with_character(
    prompt="walking on a beach at sunset",
    character_id=character_id
)

print(f"\n✓ 完成！角色 {character_id} 已在新视频中复用")

两种方法对比

特性 方法一：视频 URL 方法二：任务 ID
使用场景 已有视频 URL 刚生成的视频任务
速度 依赖视频加载 更快，直接复用任务
灵活性 可用于任何视频 仅限 Sora 生成的视频
最佳实践 从现有素材提取 连续生成工作流

选择建议：

# 场景 1: 你有一个现成的视频 URL
if has_video_url:
    use_method_1()  # 视频 URL 提取
    
# 场景 2: 刚用 Sora 生成了视频，还热乎着
elif just_generated_video:
    use_method_2()  # 任务 ID 复用，更快更便捷
    
# 场景 3: 需要批量处理多个视频
elif batch_processing:
    use_method_1()  # URL 方式更通用

完整实战代码

下面是一个完整的角色管理类，整合了两种方法：

import requests
import time
from typing import Optional, Dict, Any

class SoraCharacterManager:
    """Sora 角色管理器 - 支持两种角色创建方法"""
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.openai.com/v1"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
        self.characters = {}  # 存储创建的角色
    
    def create_from_url(
        self, 
        video_url: str, 
        start_time: float, 
        end_time: float,
        name: Optional[str] = None
    ) -> Optional[str]:
        """
        方法一：从视频 URL 创建角色
        
        参数:
            video_url: 视频地址
            start_time: 开始时间（秒）
            end_time: 结束时间（秒）
            name: 角色名称（可选，用于本地管理）
        
        返回:
            character_id: 角色 ID，失败返回 None
        """
        # 参数验证
        duration = end_time - start_time
        if duration < 2:
            print(f"⚠️  警告：时间段 {duration}秒 较短，建议至少 2-3 秒")
        elif duration > 10:
            print(f"ℹ️  提示：时间段 {duration}秒 较长，系统会自动选择最佳帧")
        
        data = {
            "model": "sora-2-character",
            "url": video_url,
            "timestamps": f"{start_time},{end_time}"
        }
        
        try:
            response = requests.post(
                f"{self.base_url}/sora/v1/characters",
                headers=self.headers,
                json=data
            )
            response.raise_for_status()
            
            result = response.json()
            character_id = result.get('character_id')
            
            if character_id:
                # 保存角色信息
                self.characters[character_id] = {
                    'name': name or f"character_{len(self.characters) + 1}",
                    'source': 'url',
                    'url': video_url,
                    'timestamps': f"{start_time},{end_time}",
                    'created_at': time.time()
                }
                
                print(f"✅ 角色创建成功！")
                print(f"   ID: {character_id}")
                print(f"   名称: {self.characters[character_id]['name']}")
                print(f"   来源: 视频 URL")
                
                return character_id
            else:
                print(f"❌ 创建失败：{result}")
                return None
                
        except Exception as e:
            print(f"❌ 请求错误：{str(e)}")
            return None
    
    def create_from_task(
        self,
        task_id: str,
        start_time: float,
        end_time: float,
        name: Optional[str] = None
    ) -> Optional[str]:
        """
        方法二：从任务 ID 创建角色
        
        参数:
            task_id: Sora 视频生成任务 ID
            start_time: 开始时间（秒）
            end_time: 结束时间（秒）
            name: 角色名称（可选）
        
        返回:
            character_id: 角色 ID，失败返回 None
        """
        duration = end_time - start_time
        if duration < 2:
            print(f"⚠️  警告：时间段 {duration}秒 较短，建议至少 2-3 秒")
        
        data = {
            "model": "sora-2-character",
            "from_task": task_id,
            "timestamps": f"{start_time},{end_time}"
        }
        
        try:
            response = requests.post(
                f"{self.base_url}/sora/v1/characters",
                headers=self.headers,
                json=data
            )
            response.raise_for_status()
            
            result = response.json()
            character_id = result.get('character_id')
            
            if character_id:
                self.characters[character_id] = {
                    'name': name or f"character_{len(self.characters) + 1}",
                    'source': 'task',
                    'task_id': task_id,
                    'timestamps': f"{start_time},{end_time}",
                    'created_at': time.time()
                }
                
                print(f"✅ 角色创建成功！")
                print(f"   ID: {character_id}")
                print(f"   名称: {self.characters[character_id]['name']}")
                print(f"   来源: 任务 {task_id}")
                
                return character_id
            else:
                print(f"❌ 创建失败：{result}")
                return None
                
        except Exception as e:
            print(f"❌ 请求错误：{str(e)}")
            return None
    
    def list_characters(self):
        """列出所有已创建的角色"""
        if not self.characters:
            print("暂无角色")
            return
        
        print(f"\n=== 角色列表 ({len(self.characters)} 个) ===")
        for char_id, info in self.characters.items():
            print(f"\n📌 {info['name']}")
            print(f"   ID: {char_id}")
            print(f"   来源: {info['source']}")
            print(f"   时间段: {info['timestamps']}")
    
    def get_character_prompt(self, character_id: str) -> str:
        """获取角色提示词（用于视频生成）"""
        if character_id in self.characters:
            return f"@{character_id}"
        else:
            print(f"⚠️  警告：角色 {character_id} 不存在")
            return ""

# ============ 使用示例 ============

# 初始化管理器
manager = SoraCharacterManager("YOUR_API_KEY")

# 示例 1: 从视频 URL 创建角色
print("=== 示例 1: 从视频 URL 创建角色 ===")
hero_id = manager.create_from_url(
    video_url="https://cdn.openai.com/sora/videos/hero-intro.mp4",
    start_time=5.0,
    end_time=8.0,
    name="英雄角色"
)

# 示例 2: 从任务 ID 创建角色
print("\n=== 示例 2: 从任务 ID 创建角色 ===")
villain_id = manager.create_from_task(
    task_id="video_abc123xyz",
    start_time=3.0,
    end_time=6.5,
    name="反派角色"
)

# 查看所有角色
manager.list_characters()

# 在新视频中使用角色
if hero_id:
    prompt = f"{manager.get_character_prompt(hero_id)} walking through a futuristic city"
    print(f"\n生成提示词: {prompt}")

timestamps 参数最佳实践

1. 时间段选择策略

def recommend_timestamps(video_duration: float) -> list:
    """
    根据视频长度推荐时间段
    
    参数:
        video_duration: 视频总时长（秒）
    
    返回:
        推荐的时间段列表
    """
    recommendations = []
    
    if video_duration < 5:
        # 短视频：取中间部分
        mid = video_duration / 2
        recommendations.append((max(0, mid - 1), min(video_duration, mid + 1)))
    
    elif video_duration <= 10:
        # 中等视频：取 1/4 到 3/4 之间的 3 秒
        start = video_duration * 0.25
        end = start + 3
        recommendations.append((start, end))
    
    else:
        # 长视频：提供多个选项
        # 开头部分
        recommendations.append((2, 5))
        # 中间部分
        mid = video_duration / 2
        recommendations.append((mid - 1.5, mid + 1.5))
        # 结尾部分
        recommendations.append((video_duration - 5, video_duration - 2))
    
    return recommendations

# 使用示例
duration = 15  # 15 秒视频
options = recommend_timestamps(duration)

print("推荐的时间段选择：")
for i, (start, end) in enumerate(options, 1):
    print(f"  选项 {i}: {start:.1f}秒 - {end:.1f}秒")

2. 角色质量检查

def validate_character_quality(
    video_url: str,
    start_time: float,
    end_time: float
) -> dict:
    """
    验证时间段是否适合提取角色
    
    返回:
        质量评估结果
    """
    duration = end_time - start_time
    
    issues = []
    warnings = []
    
    # 检查时间段长度
    if duration < 1.5:
        issues.append("时间段太短（< 1.5秒），可能无法提取足够特征")
    elif duration < 2:
        warnings.append("时间段较短（< 2秒），建议增加到 2-3 秒")
    elif duration > 15:
        warnings.append("时间段较长（> 15秒），系统会自动选择最佳帧")
    
    # 检查时间位置
    if start_time < 0.5:
        warnings.append("开始时间过早，视频开头可能模糊")
    
    return {
        'valid': len(issues) == 0,
        'issues': issues,
        'warnings': warnings,
        'score': 100 - len(issues) * 40 - len(warnings) * 10
    }

# 使用示例
result = validate_character_quality(
    video_url="test.mp4",
    start_time=0.5,
    end_time=2.0
)

print(f"质量评分: {result['score']}/100")
if result['issues']:
    print("❌ 问题:")
    for issue in result['issues']:
        print(f"   - {issue}")
if result['warnings']:
    print("⚠️  警告:")
    for warning in result['warnings']:
        print(f"   - {warning}")

常见错误及解决方案

错误 1: timestamps 格式错误

# ❌ 错误写法
"timestamps": "5-8"  # 使用了短横线
"timestamps": "5, 8"  # 有空格
"timestamps": [5, 8]  # 使用了数组

# ✅ 正确写法
"timestamps": "5,8"  # 逗号分隔，无空格

错误 2: 时间超出视频范围

# 假设视频长度为 10 秒

# ❌ 错误：结束时间超出范围
"timestamps": "8,12"  # 视频只有 10 秒

# ✅ 正确：在范围内
"timestamps": "7,10"

错误 3: 角色不清晰

# 解决方案：选择角色清晰可见的时间段

def find_best_character_moment(video_analysis: dict) -> tuple:
    """
    基于视频分析结果找到最佳角色提取时刻
    
    参数:
        video_analysis: 包含人脸检测、清晰度等信息
    
    返回:
        (start_time, end_time)
    """
    best_segments = []
    
    for segment in video_analysis['segments']:
        if (segment['face_visible'] and 
            segment['clarity_score'] > 0.8 and
            segment['face_size'] > 0.3):  # 脸部占画面 30% 以上
            
            best_segments.append({
                'start': segment['start'],
                'end': segment['end'],
                'score': segment['clarity_score'] * segment['face_size']
            })
    
    if best_segments:
        best = max(best_segments, key=lambda x: x['score'])
        return (best['start'], best['end'])
    else:
        # 如果没有理想片段，返回视频中段
        duration = video_analysis['duration']
        mid = duration / 2
        return (mid - 1.5, mid + 1.5)

总结

通过本文，你已经掌握了 Sora 2 Character API 的两种角色创建方法：

  1. 方法一：视频 URL 提取 – 适用于已有视频 URL 的场景
  2. 方法二：任务 ID 复用 – 适用于刚生成视频的连续工作流

核心要点回顾：

✅ timestamps 参数至关重要 – 选择角色清晰、时长 2-5 秒的片段
✅ 方法选择要灵活 – 根据实际场景选择最合适的方法
✅ 角色 ID 可复用 – 创建后可在多个视频中保持一致性
✅ 质量检查很重要 – 提取前验证时间段的合理性

下一步行动：

  1. 选择一个现有视频，尝试方法一提取角色
  2. 生成一个新视频，立即用方法二创建角色
  3. 在新场景中复用该角色，验证一致性效果

想要更稳定、更便宜的 API 服务？推荐使用 APIYI – 专业的 AI 大模型 API 中转站，提供 Sora API 接入，价格优惠，免费试用额度等你来拿！

Sora 2 Character API 두 가지 생성 방법

방법 1: 비디오 URL로 캐릭터 추출하기

이미 준비된 비디오 소스가 있을 때 사용하는 가장 직접적인 방법입니다.

요청 파라미터 설명:

파라미터 타입 필수 설명
model string ✅ 고정값 sora-2-character
url string ✅ 공개 URL로 접근 가능한 비디오 주소
timestamps string ✅ 캐릭터가 나타나는 시간 범위, 형식: "시작초,종료초"

전체 요청 예시:

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를 사용해서 캐릭터를 추출할 수 있어요. 비디오를 다시 업로드할 필요가 없습니다.

요청 파라미터 설명:

파라미터 타입 필수 설명
model string ✅ 고정값 sora-2-character
from_task string ✅ 이전에 생성한 비디오의 작업 ID
timestamps string ✅ 캐릭터가 나타나는 시간 범위

전체 요청 예시:

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 만료나 접근 문제 방지

추천: APIYI apiyi.com을 통해 Sora 2 Character API를 호출하세요. 안정적인 연동 서비스와 무료 테스트 크레딧을 제공합니다.

Sora 2 Character API 두 가지 방법 비교

sora-2-character-api-tutorial-create-reusable-characters-ko 图示

비교 항목 비디오 URL 방식 작업 ID 방식
사용 시나리오 기존 비디오 소스 보유 Sora 생성 비디오 재사용
파라미터 url from_task
업로드 필요 여부 공개 접근 가능한 비디오 URL 필요 불필요, 작업 ID만 참조
네트워크 요구사항 CDN 글로벌 접근 필요 추가 요구사항 없음
워크플로우 독립적인 소스 처리 비디오 생성 프로세스와 연계
추천 시나리오 외부 비디오 캐릭터 가져오기 시리즈 비디오 대량 생성

어떤 방법을 선택해야 할까요?

비디오 URL 방식을 선택하세요:

  • 기존 비디오 소스가 있을 때 (촬영한 실제 영상, 다른 플랫폼에서 다운로드한 비디오 등)
  • Sora가 아닌 다른 방식으로 생성된 비디오에서 캐릭터를 추출해야 할 때

작업 ID 방식을 선택하세요:

  • Sora 2 API로 비디오를 대량 생성하고 있을 때
  • 이미 생성된 비디오에서 캐릭터를 추출해서 후속 시리즈 영상에 사용하고 싶을 때
  • 더 매끄러운 자동화 워크플로우를 원할 때

Sora 2 Character API timestamps 파라미터 완벽 가이드

timestamps는 Character API에서 가장 중요한 파라미터로, 비디오의 어느 시간대에서 캐릭터를 추출할지 결정합니다.

timestamps 형식 규칙

규칙 설명 예시
형식 "시작초,종료초" "5,8"
타입 string(문자열) 따옴표로 감싸야 함
최소 차이 1초 "3,4" ✅
최대 차이 3초 "5,8" ✅
범위 초과 에러 발생 "1,10" ❌

timestamps 설정 팁

  1. 캐릭터가 선명하게 보이는 구간 선택: 캐릭터가 화면에 완전히 나타나고 가려지지 않아야 합니다
  2. 빠른 움직임 구간 피하기: 캐릭터가 상대적으로 정지해 있거나 천천히 움직이는 시간대를 선택하세요
  3. 조명이 충분한지 확인: 조명이 좋은 구간에서 더 정확한 캐릭터 특징을 추출할 수 있어요
  4. 정면 우선: 가능하다면 캐릭터가 카메라를 향하고 있는 구간을 선택하세요

예시 시나리오:

10초짜리 비디오가 있고, 2-4초에는 캐릭터가 정면으로 등장하고, 6-9초에는 측면에서 움직인다면:

// 추천: 정면이 선명한 구간 선택
{
  "timestamps": "2,4"
}

// 비추천: 측면에서 움직이는 구간
{
  "timestamps": "6,9"
}

Sora 2 Character API 완전 워크플로우

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:
    """캐릭터를 활용한 비디오 생성"""
    # prompt에서 @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}")

팁: APIYI apiyi.com을 통해 Sora 2 Character API에 접속하면, 완벽한 캐릭터 관리 기능과 기술 지원을 제공받을 수 있어요.

자주 묻는 질문

Q1: 비디오 URL에 접근할 수 없다면 어떻게 하나요?

비디오 URL이 다음 조건을 충족하는지 확인해주세요:

  1. 공개 네트워크 접근 가능: 내부 네트워크 주소나 로그인이 필요한 링크는 사용할 수 없어요
  2. CDN 글로벌 가속: 알리바바 클라우드 OSS, AWS S3 등을 사용한다면 글로벌 가속이나 글로벌 CDN을 활성화해야 해요
  3. URL 유효 기간: 임시 서명 URL이라면 충분히 긴 유효 기간을 확보해주세요
  4. 지원 형식: MP4 형식을 권장해요

Q2: timestamps 파라미터 오류는 어떻게 처리하나요?

흔히 발생하는 오류와 해결 방법이에요:

  1. 시간 범위가 3초 초과: 범위를 1-3초 이내로 줄여주세요. 예: "5,8" → "5,7"
  2. 시간 범위가 1초 미만: 시작과 종료 시간이 최소 1초 이상 차이나야 해요
  3. 형식 오류: 반드시 문자열 형식 "5,8"이어야 하며, 배열이나 숫자는 안 돼요
  4. 비디오 길이 초과: 시간 범위가 전체 비디오 길이 내에 있어야 해요

Q3: 생성한 캐릭터를 비디오 생성에 어떻게 사용하나요?

캐릭터 생성이 완료되면 character_id를 받게 돼요. 이후 비디오 생성 요청에서 프롬프트에 @character_id 형식으로 해당 캐릭터를 참조하면 돼요. 예를 들면:

@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 기술 커뮤니티에서 확인하실 수 있어요

Try AI Large Model https://api.apiyi.com for free
Stable and reliable AI LM API aggregation service, Get 300 Millions Tokens for Free~

Similar Posts