> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rivus.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Sora 角色创建

> 创建可复用的角色，在多个视频中使用同一角色

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

## 典型使用流程

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

## 接口信息

* **接口地址**：`POST /sora/v1/characters`
* **认证方式**：在请求头中添加 `Authorization: Bearer <你的API密钥>`

<Callout type="warning">
  如果调用时返回 `sora character api is not supported for this channel` 或 `unsupported_api` 错误，说明你当前使用的 API 密钥不支持角色创建功能。请联系平台管理员确认或更换支持该功能的密钥。
</Callout>

## 创建角色

### 请求参数

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

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

```bash theme={null}
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 创建

```bash theme={null}
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"
  }'
```

### 响应示例

```json theme={null}
{
  "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 和时间片段：

```bash theme={null}
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` 引用角色：

```bash theme={null}
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"
  }'
```

<Callout type="info">
  推荐使用方式一（`character_url` + `character_timestamps`），这种方式更明确且兼容性更好。
</Callout>

## 完整示例

以下是从创建角色到生成视频的完整流程：

```bash theme={null}
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"
  }'
```

<Callout type="tip">
  * 角色创建和视频生成会分别计费
  * 如果不需要复用角色，可以直接使用纯文本或参考图生成视频，详见《视频生成》文档
</Callout>

## 计费说明

角色创建按次计费，使用模型 `sora-2-characters`：

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

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