OpenAI/Sora-2

本文介绍 sora-2 视频模型的4个核心 API（异步提交任务、查询任务状态、下载视频、remix），需特别说明：本接口与此前 submit 接口调用方式不同，与 OpenAI 官方接口调用方式完全一致，模型功能无差异。以下详细说明各接口的请求地址、输入输出参数、调用示例及响应说明，供接口使用时查阅参考。

1. 认证方式

所有接口均采用 API Key 认证，统一使用 Authorization 请求头，格式如下：

Authorization: Bearer $OPENAI\_API\_KEY

说明：将 $OPENAI\_API\_KEY 替换为您实际的 API Key 即可完成认证，确保接口调用权限。

2. 异步提交任务接口

该接口用于提交 sora-2 模型视频生成异步任务，支持传入提示词、首帧图、尺寸、时长等参数，提交成功后返回任务唯一标识及基础任务信息，后续可通过该标识查询任务状态、下载视频或进行 remix 操作。

2.1 接口地址

http://api.modelverse.cn/v1/videos

2.2 输入参数

参数	类型	是否必选	描述
model	string	是	模型名称，固定为 `sora\-2`
prompt	string	是	提示词，用于指导视频生成，需明确描述视频风格、人物动作、场景等要求
size	string	否	生成视频的尺寸（分辨率），可选值：720x1280、1280x720，未传入时使用默认值
duration	string	否	视频生成时长（单位：秒），可选值：4、8、12，未传入时使用默认值
input_reference	string	否	首帧图，支持上传本地图片文件（如请求示例中所示）

2.3 调用注意事项

如果您使用 Windows 系统，建议使用 Postman 或其他 API 调用工具，避免命令行调用出现兼容问题。

2.4 请求示例（curl）

curl -X POST "http://api.modelverse.cn/v1/videos" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F prompt="She turns around and smiles, then slowly walks out of the frame." \
  -F model="sora-2" \
  -F size="1280x720" \
  -F seconds="8" \
  -F input_reference="@sample_720p.jpeg;type=image/jpeg"

2.5 输出参数

参数	类型	描述
id	string	异步任务的唯一标识，用于后续查询任务状态、下载视频、remix 操作
object	string	任务类型，固定返回 `video`
model	string	模型名称，返回 `sora\-2`
status	string	任务状态，可选值：queued（排队中）、in_progress（执行中）、completed（完成）、failed（失败）
progress	int	任务进度，取值范围 0-100，反映任务执行进度
size	string	生成视频的分辨率，与请求时传入的 size 一致（未传入时为默认值）
seconds	string	视频生成时长（单位：秒），与请求时传入的 duration 一致（未传入时为默认值）

2.6 响应示例

{
    "id": "video_456",
    "object": "video",
    "model": "sora-2",
    "status": "queued",
    "progress": 0,
    "created_at": 1712698600,
    "size": "720x1280",
    "seconds": "8"
}

3. 查询任务状态接口

该接口用于查询已提交异步任务的执行状态、进度及相关配置信息，需传入异步提交任务时返回的唯一标识（id）作为查询参数。

3.1 接口地址

https://api.modelverse.cn/v1/videos/<task_id>

说明：将 \<task\_id\> 替换为异步提交任务接口返回的实际 id（如 video_456），即可发起查询。

3.2 输入参数

输入参数通过 URL 路径参数传递，具体说明如下：

参数	类型	是否必选	描述
task_id	string	是	异步任务的唯一标识，由异步提交任务接口返回，用于定位查询具体任务

3.3 请求示例（curl）

curl --location 'https://api.modelverse.cn/v1/videos/video_6982fa1cd4f081908b619dc53cfc2435' \
-H "Authorization: Bearer $OPENAI_API_KEY"

3.4 输出参数

输出参数与异步提交任务接口的输出参数一致，详细说明见 2.5 输出参数。

3.5 响应示例

3.5.1 成功响应示例

{
  "id": "video_456",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1712698600,
  "size": "720x1280",
  "seconds": "8"
}

3.5.2 失败响应示例

{
  "error": {
    "message": "error",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

4. 下载视频接口

该接口用于下载已完成（status 为 completed）的视频生成结果，需传入任务唯一标识（task_id），仅当任务完成时可正常下载，未完成时返回异常信息。

4.1 接口地址

https://api.modelverse.cn/v1/videos/<task_id>/content

说明：将 \<task\_id\> 替换为异步提交任务接口返回的实际 id，且确保任务状态为 completed。

4.2 输入参数

输入参数通过 URL 路径参数传递，具体说明如下：

参数	类型	是否必选	描述
task_id	string	是	异步任务的唯一标识，用于定位要下载的视频任务，且任务状态需为 completed

4.3 请求示例（curl）

curl --location 'https://api.modelverse.cn/v1/videos/<task_id>/content' \
-H "Authorization: Bearer $OPENAI_API_KEY"
--output video.mp4

4.4 响应说明

4.4.1 正常返回

当任务状态为 completed 时，接口返回视频二进制流，可通过 \-\-output 指令指定保存路径及文件名（如示例中的 video.mp4）。

4.4.2 异常返回

当任务未完成（状态为 queued、in_progress）或任务失败（status 为 failed）时，返回异常信息，示例如下：

{
    "error": {
        "message": "task is not completed yet, current status: Pending",
        "type": "invalid_request_error"
    }
}

5. remix 接口

该接口用于基于已有的视频任务（task_id）进行二次生成（remix），需传入新的提示词，生成新的视频任务，返回新的任务标识及基础信息。

5.1 接口地址

https://api.modelverse.cn/v1/videos/<task_id>/remix

说明：将 \<task\_id\> 替换为已存在的视频任务唯一标识，基于该任务进行 remix 操作。

5.2 输入参数

输入参数通过请求体（JSON 格式）传递，具体说明如下：

参数	类型	是否必选	描述
prompt	string	是	新的提示词，用于指导 remix 视频生成（如修改视频风格、动作等），不可为空

5.3 请求示例（curl）

curl -X POST "https://api.modelverse.cn/v1/videos/<task_id>/remix" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "赛博朋克风格"
  }'

5.4 响应说明

5.4.1 正常返回

remix 任务提交成功后，返回新的视频任务信息，包含新的任务标识、状态及原任务标识，示例如下：

{
  "id": "video_456",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1712698600,
  "size": "720x1280",
  "seconds": "8",
  "remixed_from_video_id": "video_123"
}

说明：remixed\_from\_video\_id 字段表示当前 remix 任务基于的原视频任务标识。

5.4.2 异常返回

当输入参数不合法（如 prompt 为空）时，返回异常信息，示例如下：

{
    "error": {
        "message": "Invalid param: prompt is required",
        "type": "invalid_request_error",
        "param": "6217f8ed-396d-434a-9b78-96775c0d2f99",
        "code": "param_error"
    }
}