Skip to main content
通过 Sora 角色创建接口，你可以从视频中提取角色，并在后续的视频生成中复用该角色，实现同一角色在不同场景中多次出镜。

​
典型使用流程

  1. 准备一段包含目标角色的视频（或使用已生成的视频任务 ID）
  2. 调用 /sora/v1/characters 创建角色
  3. 在 /v1/videos 中通过 character_url / character_timestamps 引用该角色生成新视频

​
接口信息

  • 接口地址：POST /sora/v1/characters
  • 认证方式：在请求头中添加 Authorization: Bearer <你的API密钥>
如果调用时返回 sora character api is not supported for this channel 或 unsupported_api 错误，说明你当前使用的 API 密钥不支持角色创建功能。请联系平台管理员确认或更换支持该功能的密钥。

​
创建角色

​
请求参数

  • url：包含目标角色的视频 URL（与 from_task 二选一）
  • from_task：基于已有的视频任务 ID 创建角色（与 url 二选一）
  • timestamps：角色在视频中的时间片段，格式如 1,3（表示第 1～3 秒）

​
方式一：通过视频 URL 创建

curl -X POST "https://models.kapon.cloud/sora/v1/characters" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://filesystem.site/cdn/20251030/javYrU4etHVFDqg8by7mViTWHlMOZy.mp4",
    "timestamps": "1,3"
  }'

​
方式二：通过任务 ID 创建

curl -X POST "https://models.kapon.cloud/sora/v1/characters" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_task": "sora-2:task_01kbfq03gpe0wr9ge11z09xqrj",
    "timestamps": "1,3"
  }'

​
响应示例

{
  "id": "chr_1234567890",
  "username": "dshfdavpv.mooskyflig",
  "permalink": "https://platform.openai.com/characters/chr_1234567890",
  "profile_picture_url": "https://filesystem.site/cdn/avatar.png"
}
响应字段说明：
  • id：角色 ID
  • username：角色标识名称，可在提示词中使用（如 @dshfdavpv.mooskyflig）
  • permalink：角色主页链接
  • profile_picture_url：角色头像

​
在视频生成中使用角色

创建角色后，可以通过以下两种方式在 /v1/videos 中使用该角色：

​
方式一：使用 character_url 和 character_timestamps

直接使用与角色创建相同的 URL 和时间片段： 
curl -X POST "https://models.kapon.cloud/v1/videos" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "使用已创建角色，在咖啡馆场景中阅读一本书",
    "seconds": "10",
    "size": "16x9",
    "character_url": "https://filesystem.site/cdn/20251030/javYrU4etHVFDqg8by7mViTWHlMOZy.mp4",
    "character_timestamps": "1,3",
    "private": "false"
  }'

​
方式二：在提示词中使用 @username

在提示词中通过 @username 引用角色： 
curl -X POST "https://models.kapon.cloud/v1/videos" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "使用 @dshfdavpv.mooskyflig 这个角色在街边咖啡馆中行走",
    "seconds": "10",
    "size": "16x9"
  }'
推荐使用方式一（character_url + character_timestamps），这种方式更明确且兼容性更好。

​
完整示例

以下是从创建角色到生成视频的完整流程： 
export YOUR_API_KEY="sk-xxxxx"
export BASE_URL="https://models.kapon.cloud"

# 步骤 1：创建角色
curl -X POST "$BASE_URL/sora/v1/characters" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://filesystem.site/cdn/20251030/javYrU4etHVFDqg8by7mViTWHlMOZy.mp4",
    "timestamps": "1,3"
  }'

# 步骤 2：使用该角色生成视频
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "使用已创建角色，在咖啡馆场景中阅读一本书",
    "seconds": "10",
    "size": "16x9",
    "character_url": "https://filesystem.site/cdn/20251030/javYrU4etHVFDqg8by7mViTWHlMOZy.mp4",
    "character_timestamps": "1,3",
    "private": "false"
  }'
  • 角色创建和视频生成会分别计费
  • 如果不需要复用角色，可以直接使用纯文本或参考图生成视频，详见《视频生成》文档

​
计费说明

角色创建按次计费，使用模型 sora-2-characters：
  • 每次成功调用计费一次
  • 调用失败不会扣费
  • 请确保账户余额充足，余额不足时会返回相应错误提示
如需查看具体价格，请联系平台管理员或查看平台的价格说明页面。