Skip to main content
POST

功能概述

Sora2 角色创建功能允许您从现有视频中提取角色,创建后可在后续视频生成中复用该角色,实现角色一致性。
重要提示:
  • 视频必须包含声音可识别的角色
  • 时间范围限制:最小 1 秒,最大 3 秒
  • urlfrom_task 二选一,必须提供其中一个
  • 此模式下不需要 prompt 参数
  • 创建完成后,角色任务 ID 可用于后续视频生成

认证

string
必填
Bearer Token 认证
获取 API Key:访问 API Key 管理页面

请求参数

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

响应字段

string
任务唯一标识符,用于查询角色创建状态创建完成后,可使用此角色任务 ID 在视频生成时通过 character_url 参数引用该角色
string
对象类型,固定为 generation.task
string
使用的模型名称
string
任务状态:
  • queued - 排队等待处理
  • in_progress - 处理中
  • completed - 成功完成
  • failed - 失败
integer
任务进度百分比(0-100)
integer
任务创建时间(Unix 时间戳)
integer
任务完成时间(Unix 时间戳,仅完成后有值)
object
角色创建结果(仅完成后有值)包含创建的角色信息,如角色 ID、名称、头像等

使用流程

1

提交角色创建请求

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

获取任务 ID

接口返回任务 ID,状态为 queuedin_progress
3

查询任务状态

使用 查询视频任务状态 接口轮询任务进度
4

使用角色生成视频

角色创建完成后,在后续视频生成中使用 character_url 参数引用该角色任务 ID

最佳实践

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