# 创建角色 Character

**方法**: `POST`
**路径**: `/sora/v1/characters`

创建角色，后续可用于 @ 调用，注意调用角色需要跟 prompt 有空格隔开
例如：@{角色1Username} 在一个舞台上和 @{角色2Username} 牵手跳舞
@xxxx1 在一个舞台上和 @yyyy1 牵手跳舞

参数 url、 from\_task 二选一，必须设置一个

接口说明
角色客串功能:
你可以把生成的或者上传你自己的视频，把任何角色对象提取出来，加入视频中作为“客串角色”
用户不仅能客串自己，还可以创建生活中的角色(如宠物、朋友)或纯想象的角色(如怪物、英雄、奇幻生物)
只需上传相机里的视频(如宠物鸭子视频)，或直接生成全新角色，甚至从日常物品(如饼干罐)衍生出有趣面孔。
任何东西都能变身客串，激发无限脑洞

PS: 这个角色指的是物品，不是人物，人物要走 face id 录入暂不支持上传

## 请求参数

### Header 参数

```text
Content-Type
string
必需
示例:
application/json
Authorization
string
可选
默认值:
Bearer {{YOUR_API_KEY}}
```

### Body 参数 application/json

```text
timestamps
string
必需
单位秒，例如 ‘1,2’ 是指视频的1～2秒中出现的角色，注意范围差值最大 3 秒最小 1 秒
url
string
可选
视频中包含需要创建的角色，视频必须有声音、有角色;参数 url、 from_task 二选一，必须设置一个
from_task
string
可选
可以根据已经生成的任务 id，来创建角色;参数 url、 from_task 二选一，必须设置一个
示例
{
"url"
:
"https://filesystem.site/cdn/20251030/javYrU4etHVFDqg8by7mViTWHlMOZy.mp4"
,
"timestamps"
:
"1,3"
,
"from_task"
:
"video_637efe22-3b6a-47ad-ab02-ee01a686a0bd"
}
```

## 请求示例代码

### Shell

```bash
curl --location --request POST '/sora/v1/characters' \
--header 'Authorization: Bearer {{YOUR_API_KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://filesystem.site/cdn/20251030/javYrU4etHVFDqg8by7mViTWHlMOZy.mp4",
    "timestamps": "1,3",
    "from_task": "video_637efe22-3b6a-47ad-ab02-ee01a686a0bd"
}'
```

## 返回响应

### 🟢 200 成功

**内容类型**: `application/json`

#### 响应结构

```text
id
string
角色id
必需
username
string
必需
角色名称，用于放在提示词中 @{username}
permalink
string
必需
角色主页，跳转到 openai 角色主页
profile_picture_url
string
角色头像
必需
```

#### 示例

```json
{
    "id": "ch_691155df38588191b3ae5f2d390a4359",
    "username": "saparpomd.oddwingduo",
    "permalink": "https://sora.chatgpt.com/profile/saparpomd.oddwingduo",
    "profile_picture_url": "https://videos.openai.com/az/files/00000000-6614-71f7-b5e4-1459ba12ed5e%2Fraw?se=2025-11-14T00%3A00%3A00Z&sp=r&sv=2024-08-04&sr=b&skoid=cfbc986b-d2bc-4088-8b71-4f962129715b&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skt=2025-11-10T01%3A10%3A14Z&ske=2025-11-17T01%3A15%3A14Z&sks=b&skv=2024-08-04&sig=699mchlFKBCew8%2BOxBVfYr/08kVey5E3ItuznIMyGdw%3D&ac=oaisdmntprsouthcentralus"
}
```