Sora 角色创建

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

典型使用流程

准备一段包含目标角色的视频（或使用已生成的视频任务 ID）
调用 /sora/v1/characters 创建角色
在 /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：

每次成功调用计费一次
调用失败不会扣费
请确保账户余额充足，余额不足时会返回相应错误提示

如需查看具体价格，请联系平台管理员或查看平台的价格说明页面。

概述

文本生成

音频

图像

视频

其他

典型使用流程

接口信息

创建角色

请求参数

方式一：通过视频 URL 创建

方式二：通过任务 ID 创建

响应示例

在视频生成中使用角色

方式一：使用 character_url 和 character_timestamps

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

完整示例

计费说明

​典型使用流程

​接口信息

​创建角色

​请求参数

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

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

​响应示例

​在视频生成中使用角色

​方式一：使用 character_url 和 character_timestamps

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

​完整示例

​计费说明

典型使用流程

接口信息

创建角色

请求参数

方式一：通过视频 URL 创建

方式二：通过任务 ID 创建

响应示例

在视频生成中使用角色

方式一：使用 character_url 和 character_timestamps

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

完整示例

计费说明