通用视频协议

通过平台视频协议创建异步任务，再用任务 ID 查询进度和结果。各模型共用以下请求结构；模型支持的素材、参数和取值可能不同。

接口与鉴权

操作	方法与路径
创建任务	`POST /v1/contents/generations/tasks`
查询任务	`GET /v1/contents/generations/tasks/{id}`
可用视频模型	`GET /v1/models?output_modalities=video`

BASE_URL="https://api.ope.ai"
API_KEY="YOUR_API_KEY"

curl "$BASE_URL/v1/models?output_modalities=video" \
  -H "Authorization: Bearer $API_KEY"

创建请求使用 Content-Type: application/json。返回值为直接 JSON。

创建参数

字段	类型	必填	说明
`model`	string	是	可用模型列表中的模型 ID
`content`	object[]	是	至少一个输入元素，按输入顺序排列
`resolution`	string	否	分辨率，例如 `720p`
`ratio`	string	否	画面比例，例如 `16:9`、`9:16`
`duration`	integer	否	输出时长，单位秒；具体模型可能要求显式提供
`generate_audio`	boolean	否	是否生成音频。仅在所选模型支持时可用，具体以模型说明为准
`watermark`	boolean	否	是否添加水印。仅在所选模型支持时可用，具体以模型说明为准
`return_last_frame`	boolean	否	是否返回尾帧。仅在所选模型支持时可用，具体以模型说明为准
`extra_parameters`	object	否	模型专属扩展参数；具体字段、类型及支持范围见对应模型文档，例如 Seedance 系列

上表中的可选参数不需要时直接省略，由模型使用自身行为，不要用 null 代替省略。扩展参数放在 extra_parameters，例如 "extra_parameters": {"seed": 42}；duration 等通用参数仍放在顶层。

content 输入

`type`	对应字段	`role` 示例
`text`	`text: "提示词"`	不填
`image_url`	`image_url: {"url":"..."}`	`first_frame`、`last_frame`、`reference_image`
`video_url`	`video_url: {"url":"..."}`	`reference_video`
`audio_url`	`audio_url: {"url":"..."}`	`reference_audio`
`draft_task`	`draft_task: {"id":"..."}`	不填；仅支持样片续生成的模型

图片、音频接受可公开读取的 HTTP/HTTPS URL 或对应媒体类型的 Base64 Data URL；视频仅接受 HTTP/HTTPS URL。媒体 URL 应无需额外登录或鉴权 Header。请求体最多 64 MiB。

draft_task.id 使用本人已有的平台样片任务 ID。样片引用放在 content 内；样片开关按具体模型说明放在 extra_parameters.draft。

curl：创建与查询

将 YOUR_VIDEO_MODEL_ID 替换为可用模型 ID。下面请求明确指定 5 秒、720p 和横屏。

curl "$BASE_URL/v1/contents/generations/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "YOUR_VIDEO_MODEL_ID",
    "content": [{"type": "text", "text": "清晨的海面，镜头缓慢推进。"}],
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9"
  }'

HTTP 200 表示任务已受理，返回任务 ID：

{"id":"cgt_386cb55a950c4e4380fbe740762500a3"}

保存该 ID，用同一用户的 API Key 查询。创建成功不代表生成完成；queued 或 running 时继续查询。

TASK_ID="cgt_386cb55a950c4e4380fbe740762500a3"
curl "$BASE_URL/v1/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

成功结果示例：

{
  "id": "cgt_386cb55a950c4e4380fbe740762500a3",
  "model": "YOUR_VIDEO_MODEL_ID",
  "status": "succeeded",
  "content": {"video_url": "https://media.example.com/result.mp4"},
  "error": null,
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9",
  "created_at": 1791000000,
  "updated_at": 1791000060,
  "media_expires_at": 1791086460
}

响应字段	说明
`id`、`model`	平台任务 ID、模型 ID
`status`	见下表
`content.video_url`、`content.last_frame_url`	可用时返回视频、尾帧 URL
`error`	生成失败时包含 `code`、`message`，其他状态为 `null`
`created_at`、`updated_at`	创建、状态更新时间，Unix 秒
`media_expires_at`	媒体截止时间，Unix 秒；取得媒体后返回
`duration`、`resolution`、`ratio`、`generate_audio`	已确认的输出参数；未知时省略
`usage`	可用时返回 `completion_tokens`、`total_tokens` 及 `tool_usage`

`status`	含义
`queued`	排队中
`running`	生成中，或等待视频及请求要求的尾帧就绪
`succeeded`	生成成功
`failed`	生成失败；查看 `error`
`expired`	已成功生成的媒体超过访问期限

所有视频协议都在视频结果地址保存成功后才返回 succeeded；请求了 return_last_frame=true 时，还须等待尾帧就绪。需要转存的协议会等待视频和所需尾帧上传并保存地址。等待期间返回 running，已保存的媒体地址仍可返回，请继续查询同一任务；暂时转存失败也会继续等待，不要重新创建。未请求尾帧时不等待尾帧。媒体到期仍返回 expired。生成计费按原规则进行，不因等待结果地址延后或重复计费。

请求要求的尾帧下载返回 404 时，任务仍为 running，平台会继续重试，直到尾帧完成或媒体到期。下载失败会记录服务端诊断日志，可使用任务 ID 或请求 ID 排查。

生成失败的查询仍返回 HTTP 200，请检查 status。成功后使用返回的 content.video_url 播放或下载：

curl -L "VIDEO_URL_FROM_RESPONSE" --output result.mp4

视频和尾帧的访问期限为 24 小时，按返回的 media_expires_at 保存结果。到期查询返回 status: "expired"、content: {}、error: null，重新查询不会延长期限。

错误与调用边界

{"error":{"code":"InvalidRequest","message":"duration must be an integer","param":"duration"}}

param 在参数错误时指出需要修正的字段。常见 HTTP 状态：400 参数错误，401/403 认证或权限问题，402 额度不足，404 任务不可访问，413 请求过大，429 限流，500/503 服务异常或暂不可用，504 请求超时。响应 Header 中的 X-Request-ID 可用于反馈问题。

接口提供创建和单任务查询，不提供任务列表、主动取消或回调。每次 POST 都创建独立任务；不要通过重复创建来查询进度。

Seedance 的图片与多模态示例见 Seedance 系列。

接口与鉴权​

创建参数​

content 输入​

curl：创建与查询​

错误与调用边界​

接口与鉴权

创建参数

content 输入

curl：创建与查询

错误与调用边界