跳转到主要内容

概述

Sora 2 角色接口(Character API)允许您通过视频创建可复用的角色,并在后续视频生成中保持角色的一致性。通过在提示词中引用 @id(唯一性的 Cameo 出镜秀 ID 或角色 Character ID),您可以让特定角色在不同视频中反复出镜。
由于 API 禁止直接放入人脸,角色接口提供了一个合规的解决方案:先将角色创建为虚拟角色,然后在提示词中通过 @id 引用该角色即可。

核心要义

角色接口的核心工作原理:
  1. 创建角色:通过视频 URL 创建一个唯一的角色 ID
  2. 引用角色:在视频生成的提示词中加入 @角色ID@username
  3. 保持一致性:角色在不同视频中保持外观、特征的一致性

为什么需要角色?

重要限制:真人出镜不可行。API 不允许直接上传包含真实人脸的视频作为角色。
角色接口的典型应用场景:

电商场景

商品角色化

将电商商品包装做成角色,固定商品包装上的品牌标识、文字信息等元素。在后续视频生成时,通过 @角色ID 植入该商品,确保商品在不同场景下保持一致的外观和品牌信息。
示例应用
  • 产品展示视频:同一款商品在不同场景(户外、室内、工作场景)中出现
  • 品牌营销视频:品牌吉祥物在多个短视频中保持一致形象
  • 包装展示:商品包装上的 Logo、文字在多角度展示中保持清晰和一致

动漫场景

虚拟人物

虚拟人物、卡通角色、动漫角色都非常适合做成角色。创建后可以让角色在不同剧情、场景中反复登场,保持角色设定的一致性。
示例应用
  • 系列动画短片:主角在多集中保持相同外观
  • 品牌 IP 角色:虚拟代言人在不同营销视频中出镜
  • 教育内容:教学类虚拟讲师在多个视频中保持形象

其他场景

  • 游戏资产:游戏角色的宣传视频制作
  • 虚拟主播:虚拟 UP 主的系列视频内容
  • IP 衍生:已有 IP 角色的视频化内容创作

端点地址

https://api.apiyi.com/sora/v1/characters

请求参数

参数类型必填说明
modelstring固定值:sora-character
urlstring视频 URL 地址,视频中应包含需要创建的角色
timestampsstring角色出现的时间范围(单位:秒),格式:"起始秒,结束秒"
例如:"1,3" 表示视频的 1-3 秒
范围差值:最小 1 秒,最大 3 秒

参数说明

  • 视频长度:15 秒以内
  • 格式:MP4、MOV 等常见格式
  • 内容:不得包含真实人脸或明显的人体轮廓
  • 可访问性:URL 必须可公开访问(支持 CDN 地址)
推荐实践
  • 使用 CDN 托管视频以提高创建成功率
  • 确保视频清晰度足够(建议 720p 或以上)
  • 角色在视频中应有明显的特征(颜色、形状、纹理等)
  • 格式:字符串类型,例如 "1,3"
  • 含义:指定视频中角色出现的时间段(从视频的第几秒到第几秒)
  • 单位:秒(整数或小数均可)
  • 视频总长度:视频可以是 15 秒以内的任意长度
  • 时间段限制
    • 时间段长度(结束秒数 - 起始秒数):最小 1 秒,最大 3 秒
    • 起始时间不能小于 0
    • 结束时间不能超过视频总长度
举例说明
  • 视频总长 15 秒,timestamps: "1,3" 表示使用视频第 1-3 秒的内容作为角色(时间段长度 2 秒)
  • 视频总长 15 秒,timestamps: "8,11" 表示使用视频第 8-11 秒的内容作为角色(时间段长度 3 秒)
  • 视频总长 10 秒,timestamps: "5,6" 表示使用视频第 5-6 秒的内容作为角色(时间段长度 1 秒)
选择建议
  • 在视频中找到角色特征最明显的时间段
  • 避免选择角色被遮挡或运动模糊的时间段
  • 时间段长度可以根据实际情况选择 1-3 秒,通常 2 秒左右效果较好
当前状态:未上线未来将支持直接使用 Sora 2 异步视频生成任务的 video_id 创建角色,无需先下载视频再上传到 CDN。这将大大简化工作流程。预计参数格式:
{
  "model": "sora-character",
  "video_id": "video_abc123def456",
  "timestamps": "1,3"
}

代码示例

cURL 示例

cURL
curl -X POST "https://api.apiyi.com/sora/v1/characters" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "sora-character",
    "url": "https://mycdn-gg.oss-us-west-1.aliyuncs.com/sora/64ba6b88-8540-4b73-bf05-7bd2e96bebd1.mp4",
    "timestamps": "1,3"
  }'

Python 示例

import requests
import json

# API 配置
API_URL = "https://api.apiyi.com/sora/v1/characters"
API_KEY = "YOUR_API_KEY"

# 请求参数
payload = {
    "model": "sora-character",
    "url": "https://mycdn-gg.oss-us-west-1.aliyuncs.com/sora/64ba6b88-8540-4b73-bf05-7bd2e96bebd1.mp4",
    "timestamps": "1,3"
}

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

response = requests.post(API_URL, headers=headers, json=payload)
result = response.json()

# 输出结果
print(f"角色ID: {result['id']}")
print(f"用户名: {result['username']}")
print(f"展示名称: {result['display_name']}")
print(f"主页链接: {result['permalink']}")
print(f"封面图片: {result['profile_picture_url']}")

响应格式

成功响应

{
  "id": "char_abc123def456",
  "username": "my_character_2024",
  "display_name": "我的虚拟角色",
  "permalink": "https://api.apiyi.com/characters/my_character_2024",
  "profile_picture_url": "https://cdn.apiyi.com/characters/char_abc123def456/profile.jpg"
}

响应字段说明

字段类型说明
idstring角色的唯一标识符(Character ID)
在视频生成提示词中可使用 @char_abc123def456 引用
usernamestring角色的用户名(唯一性)
在视频生成提示词中可使用 @my_character_2024 引用
display_namestring角色的展示名称(可重复)
仅用于展示,不能用于引用
permalinkstring角色主页的永久链接地址
profile_picture_urlstring角色主页的封面图片 URL
推荐使用方式:在视频生成时,使用 @username 更简洁易读,例如:"@my_character_2024 在公园里散步"

定价

项目价格说明
角色创建$0.01 / 次限免期特惠价格
当前处于限免期,定价极低。正式定价可能会调整,请关注官方公告。

在视频生成中使用角色

创建角色后,可以在 Sora 2 视频生成接口中使用:

使用方式

prompt 参数中引用角色:
# 方式一:使用 @username
prompt = "@my_character_2024 在森林中奔跑,阳光透过树叶洒在身上"

# 方式二:使用 @id
prompt = "@char_abc123def456 和一只小鸟一起玩耍,温馨有趣"

完整示例

import requests

# 配置
SORA_API_URL = "https://api.apiyi.com/v1/videos"
API_KEY = "YOUR_API_KEY"

# 引用角色生成视频
payload = {
    "model": "sora-2",
    "prompt": "@my_character_2024 在城市街道上滑滑板,背景是繁华的商业区,阳光明媚",
    "size": "1280x720",
    "seconds": "10"
}

headers = {
    "Content-Type": "multipart/form-data",
    "Authorization": f"Bearer {API_KEY}"
}

response = requests.post(SORA_API_URL, headers=headers, files=payload)
result = response.json()

print(f"视频任务ID: {result['id']}")
详见:Sora 2 视频生成文档

注意事项与限制

重要限制 - 人脸检测:视频中不得包含真实人脸或明显的人体轮廓,否则角色创建会失败。请使用虚拟角色、卡通形象、商品、物体等非人脸内容。

成功率说明

影响成功率的因素

  • 视频中包含真实人脸或人体
  • 视频质量过低(模糊、抖动)
  • 角色特征不明显
  • iOS 逆向技术的不稳定性

提高成功率的建议

  • 使用清晰的虚拟角色视频
  • 选择角色特征明显的片段
  • 确保视频稳定无抖动
  • 必要时多次重试

视频要求

要求项说明
最大长度15 秒以内
推荐分辨率720p 或以上
格式MP4、MOV 等常见格式
内容限制不得包含真实人脸、暴力、色情等违规内容
角色清晰度角色应占据画面合理比例,特征明显

技术限制说明

由于角色创建基于 iOS 逆向工程技术,可能存在一定的技术不稳定性。如果创建失败,建议:
  1. 检查视频内容是否符合要求
  2. 调整 timestamps 时间范围,选择更清晰的片段
  3. 使用重试机制(建议 2-3 次)
  4. 如果持续失败,请联系技术支持

最佳实践

选择合适的视频片段

# 推荐:角色特征明显、画面稳定
timestamps = "2,4"  # 选择角色正面、清晰的 2 秒片段

# 避免:角色被遮挡、运动模糊
timestamps = "0,1"  # 开头可能有转场效果,不稳定

重试策略

def create_character_with_retry(video_url, timestamps, max_retries=3):
    """带指数退避的重试策略"""
    for i in range(max_retries):
        try:
            result = create_character(video_url, timestamps)
            return result
        except Exception as e:
            if i == max_retries - 1:
                raise
            wait_time = 2 ** i  # 2s, 4s, 8s
            print(f"重试 {i+1}/{max_retries},等待 {wait_time} 秒...")
            time.sleep(wait_time)

角色管理

建议维护一个角色数据库:
characters_db = {
    "product_A": {
        "id": "char_abc123",
        "username": "product_a_2024",
        "description": "A产品包装角色",
        "created_at": "2024-01-15"
    },
    "mascot_B": {
        "id": "char_def456",
        "username": "mascot_b_2024",
        "description": "品牌吉祥物",
        "created_at": "2024-01-16"
    }
}

常见问题

API 对真实人脸有严格限制。即使是 AI 生成的拟真人脸也可能被检测到。建议使用:
  • 卡通/动漫风格的虚拟角色
  • 商品、物体等非人物内容
  • 抽象艺术风格的角色
如果必须使用类人角色,建议使用风格化程度较高的设计。
角色一旦创建成功,将长期有效,可以反复在视频生成中使用。但建议保存好角色的 idusername 信息。
当前不支持修改已创建的角色。如果需要调整角色,建议:
  1. 创建新的角色
  2. 在新视频生成中使用新角色
  3. 旧角色仍然可用,不会被删除
  • 明确引用:在提示词开头使用 @username
  • 详细描述:描述角色的动作和场景,但不要重复描述角色外观
  • 示例
    ✅ 好的提示词:
    "@my_character 在公园里奔跑,追逐一只蝴蝶,阳光明媚"
    
    ❌ 不好的提示词:
    "一个红色的角色在公园里"  # 没有引用角色 ID
    "@my_character 红色的身体在公园"  # 重复描述外观可能导致冲突
    
选择建议:
  • 观看视频:先完整观看视频,找到角色最清晰的片段
  • 正面角度:优先选择角色正面或 3/4 侧面的片段
  • 光线充足:避免过暗或过曝的片段
  • 无遮挡:确保角色主体完整,无被遮挡
  • 稳定画面:避免快速运动或镜头晃动的片段
测试方法:可以尝试不同的时间段,对比创建结果。
  • 速率限制:请遵守 API 的请求速率限制(具体限制请参考 API 手册)
  • 并发控制:建议控制在 3-5 个并发,避免触发限流
  • 成本考虑:虽然当前定价很低($0.01/次),但批量创建仍需考虑总成本
建议使用示例代码中的批量创建函数,它包含了适当的并发控制。
角色创建后,主要用于 Sora 2 视频生成。未来可能支持在其他 Sora 系列模型中使用,请关注官方更新。

相关资源