Skip to main content
Sora 2 角色创建功能允许您从现有视频中提取角色，创建后可在后续视频生成中通过 @username 或 character_url 参数复用该角色，从而实现跨视频的角色一致性。
重要提示：
  • 视频必须包含声音和可识别的角色
  • 时间范围限制：最小 1 秒，最大 3 秒
  • url 和 from_task 二选一，必须提供其中一个
  • 此模式下不需要 prompt 参数
  • 创建完成后，角色任务 ID 可用于后续视频生成

​
请求参数

​
model
string
default:"sora-2"
required
视频生成模型名称。支持的模型：
  • sora-2 — 标准版本
  • sora-2-pro — 专业版本（更高质量）
  • sora-2-vip — VIP 版，更高优先级
​
timestamps
string
required
角色出现的时间戳范围，单位为秒，格式为 "起始秒,结束秒"。限制：
  • 时间范围差值最小 1 秒
  • 时间范围差值最大 3 秒
示例："1,3" 表示视频中第 1 秒到第 3 秒出现的角色。
​
url
string
包含需要创建角色的视频 URL。要求：
  • 视频必须包含声音
  • 视频必须包含可识别的角色
说明： 与 from_task 二选一。示例："https://example.com/my-video.mp4"
​
from_task
string
已生成的视频任务 ID，可根据已有视频任务创建角色。说明： 与 url 二选一。示例："task_01KBYT59JDHB4A3KDDR9N9JVWP"

​
请求示例

curl --request POST \
  --url https://geekapis.com/v1/videos/generations \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "sora-2",
    "url": "https://example.com/character-video.mp4",
    "timestamps": "1,3"
  }'

​
返回示例

200（提交成功）
{
  "id": "task_01KBYT59JDHB4A3KDDR9N9JVWP",
  "object": "generation.task",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1703884800,
  "metadata": {}
}

​
响应字段

字段类型说明
idstring任务唯一标识符，角色创建完成后可通过此 ID 引用角色
objectstring对象类型，固定为 generation.task
modelstring使用的模型名称
statusstring任务状态：queued / in_progress / completed / failed
progressinteger任务进度百分比（0–100）
created_atinteger任务创建时间（Unix 时间戳）
completed_atinteger任务完成时间（Unix 时间戳，仅完成后有值）
resultobject角色创建结果，包含角色 ID、名称、头像等（仅完成后有值）

​
使用流程

1

提交角色创建请求

调用本接口，提供包含角色的视频 URL 或已有任务 ID，以及角色出现的时间范围。
2

获取任务 ID

接口返回任务 ID，初始状态为 queued 或 in_progress。
3

查询任务状态

使用查询角色状态 API轮询任务进度，建议每 5 秒轮询一次。
4

在视频生成中使用角色

角色创建完成后，在视频生成中通过 character_url 参数或 @username 格式引用该角色。

​
查询任务状态

提交后，使用以下接口轮询角色创建任务进度： 
GET https://geekapis.com/v1/characters_tasks/{task_id}
详见查询角色状态 API。

​
最佳实践

  1. 选择清晰的角色片段：选择视频中角色特征最明显的 1–3 秒片段。
  2. 确保视频质量：高清视频能更好地提取角色特征。
  3. 包含声音：视频必须包含音频轨道。
  4. 避免多角色：选择的时间范围内最好只有一个主要角色。