视频 API

异步视频任务的创建、轮询状态与结果下载

视频生成采用异步任务模式：创建任务 → 轮询状态 → 下载结果。网关提供两条创建路径，查询与下载接口共用。

1. 能力概述

异步流程

创建任务 → 轮询 GET /v1/videos/{task_id} → 下载 GET /v1/videos/{task_id}/content

调用 POST /v1/videos 或 POST /v1/yunsellai/videos 提交任务，获得 task_id
轮询 GET /v1/videos/{task_id}，直至 status 为 completed 或 failed
任务完成后，通过 GET /v1/videos/{task_id}/content 下载视频；可选 ?variant=thumbnail 下载封面

两条创建路径对比

项	`POST /v1/videos`	`POST /v1/yunsellai/videos`
适用场景	通用视频创建，字段贴近上游视频模型约定	多模态视频生成，通过 `mode` + `assets[]` 组合输入
Content-Type	`application/json` 或 `multipart/form-data`	`application/json`
核心参数	`model`、`prompt`、`size`、`seconds`、`input_reference`	`model`、`mode`、`prompt`、`assets[]`、`resolution`、`duration_sec` 等
参考图	JSON URL / Base64 data URI / multipart 文件上传	`assets[]` 中按 `role` 传入 URL
生成模式	无 `mode` 字段，由模型与请求字段决定	显式 `mode`：`t2v`、`i2v`、`first_frame`、`first_last_frame`、`ref_image`、`video_extend`、`video_edit`
查询与下载	`GET /v1/videos/{task_id}`、`GET /v1/videos/{task_id}/content`	同上（共用）

前置条件：model 须为模型 API 中 supported_endpoint_types 含 openai-video 的模型。

2. 接口一览

方法	路径	说明
POST	`/v1/videos`	创建视频任务（通用）
GET	`/v1/videos/{task_id}`	查询任务状态
GET	`/v1/videos/{task_id}/content`	下载视频或封面
POST	`/v1/yunsellai/videos`	创建视频任务（多模态 / 云擎数智）

3. 任务状态说明

项	说明
任务 ID 格式	公开 ID 形如 `task_xxxxxxxx`
状态流转	`queued` → `in_progress` → `completed` / `failed`

`status`	说明
`queued`	排队中
`in_progress`	生成中
`completed`	已完成，可下载
`failed`	失败，见 `error` 字段

4. POST `/v1/videos`

创建视频任务。

鉴权：Bearer Token

Content-Type：application/json 或 multipart/form-data

请求体（JSON）

{
  "model": "sora-2",
  "prompt": "A cinematic shot of a cat walking on the beach at sunset, soft ocean waves, warm golden lighting",
  "size": "1280x720",
  "seconds": 8
}

请求字段

字段	类型	必填	说明
`model`	string	是	视频模型名
`prompt`	string	是	视频描述（≤ 2500 字符）
`size`	string	条件	分辨率，如 `1280x720`、`720x1280`；sora-2 等模型必填
`seconds`	int / string	条件	时长（秒）；sora-2 允许 `4/8/12/16/20`
`input_reference`	object / file	否	参考图

带参考图（JSON URL）：

{
  "model": "sora-2",
  "prompt": "动态化这张图，轻微镜头移动",
  "size": "1280x720",
  "seconds": 8,
  "input_reference": {
    "image_url": "https://example.com/ref.jpg"
  }
}

带参考图（Base64 data URI）：

{
  "model": "sora-2",
  "prompt": "动态化这张图，轻微镜头移动",
  "size": "1280x720",
  "seconds": 8,
  "input_reference": {
    "image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }
}

multipart/form-data：input_reference 为 file 类型表单字段，其余字段同名。

请求示例（curl）

JSON：

curl https://www.yunsell.com/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A cinematic shot of a cat walking on the beach at sunset, soft ocean waves, warm golden lighting",
    "size": "1280x720",
    "seconds": 8
  }'

带参考图（JSON）：

curl https://www.yunsell.com/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "动态化这张图，轻微镜头移动",
    "size": "1280x720",
    "seconds": 8,
    "input_reference": {
      "image_url": "https://example.com/ref.jpg"
    }
  }'

multipart/form-data（上传参考图）：

curl https://www.yunsell.com/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -F "model=sora-2" \
  -F "prompt=动态化这张图，轻微镜头移动" \
  -F "size=1280x720" \
  -F "seconds=8" \
  -F "input_reference=@/path/to/ref.jpg"

响应体

HTTP 200

{
  "id": "task_abc123xyz",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600
}

响应字段

字段	类型	说明
`id`	string	任务 ID，用于查询和下载
`status`	string	初始为 `queued`
`progress`	integer	进度 0–100
`created_at`	integer	Unix 时间戳（秒）

失败响应

HTTP 400

{
  "code": "invalid_request",
  "message": "seconds must be one of 4, 8, 12, 16, 20"
}

字段	类型	说明
`code`	string	错误码
`message`	string	校验失败原因

错误格式说明见任务类错误。

5. GET `/v1/videos/{task_id}`

查询视频任务状态。

鉴权：Bearer Token

Path 参数：task_id — 创建任务返回的 id

请求：无请求体

请求示例（curl）

curl https://www.yunsell.com/v1/videos/task_abc123xyz \
  -H "Authorization: Bearer sk-xxx"

响应体（生成中）

HTTP 200

{
  "id": "task_abc123xyz",
  "object": "video",
  "model": "agnes-video-v2.0",
  "status": "in_progress",
  "progress": 45,
  "created_at": 1712697600,
  "seconds": "5.0",
  "size": "1280x704"
}

响应体（已完成）

HTTP 200

{
  "id": "task_abc123xyz",
  "object": "video",
  "model": "agnes-video-v2.0",
  "status": "completed",
  "progress": 100,
  "created_at": 1712697600,
  "completed_at": 1712698200,
  "seconds": "5.0",
  "size": "1280x704",
  "remixed_from_video_id": "https://cdn.example.com/videos/video_abc.mp4",
  "error": null,
  "metadata": {
    "url": "https://cdn.example.com/videos/video_abc.mp4"
  }
}

响应体（失败）

HTTP 200

{
  "id": "task_abc123xyz",
  "object": "video",
  "model": "agnes-video-v2.0",
  "status": "failed",
  "progress": 100,
  "created_at": 1712697600,
  "error": {
    "message": "upstream generation failed",
    "code": "generation_failed"
  }
}

响应字段

字段	类型	说明
`id`	string	任务 ID，与创建时返回的 `id` 相同
`object`	string	固定为 `video`
`model`	string	使用的模型
`status`	string	任务状态，见任务状态说明
`progress`	integer	进度 0–100
`created_at`	integer	创建时间 Unix 时间戳（秒）
`completed_at`	integer	完成时间 Unix 时间戳（秒）；未完成时不返回
`expires_at`	integer	结果过期时间 Unix 时间戳（秒）；部分渠道返回
`seconds`	string	视频时长（秒），如 `"5.0"`
`size`	string	视频分辨率，如 `"1280x704"`
`remixed_from_video_id`	string	视频结果 URL；部分渠道（如 Agnes AI）在此字段返回 CDN 地址
`error`	object / null	失败时的错误信息；成功时为 `null` 或不返回
`error.message`	string	失败原因描述
`error.code`	string	错误码，如 `generation_failed`
`metadata`	object	扩展元数据，常见键见下表

metadata 常见键：

键	类型	说明
`url`	string	视频结果 URL
`thumbnail_url`	string	封面图 URL
`duration`	number	实际时长（秒）
`width`	integer	视频宽度（像素）
`height`	integer	视频高度（像素）
`fps`	integer	帧率
`seed`	integer	随机种子

6. GET `/v1/videos/{task_id}/content`

下载已生成的视频或封面图。

鉴权：Bearer Token 或管理台 Session

Path 参数：task_id

Query 参数：

参数	说明
`variant`	可选。`video`（默认）下载视频；`thumbnail` 下载封面图

前置条件：任务 status 必须为 completed。

请求示例（curl）

下载视频（跟随 301 重定向）：

curl -L https://www.yunsell.com/v1/videos/task_abc123xyz/content \
  -H "Authorization: Bearer sk-xxx" \
  -o output.mp4

下载封面图：

curl -L "https://www.yunsell.com/v1/videos/task_abc123xyz/content?variant=thumbnail" \
  -H "Authorization: Bearer sk-xxx" \
  -o cover.jpg

响应（已转存至对象存储）

HTTP 301 Moved Permanently

Location: https://cdn.example.com/users/1/tasks/task_abc123xyz/video.mp4

Header / 字段	说明
`Location`	对象存储或 CDN 上的资源 URL；客户端应跟随重定向下载
响应体	无 JSON 内容

响应（网关代理上游）

HTTP 200，响应体为二进制流（非 JSON）。

Header	说明
`Content-Type`	`video/mp4`（视频）或 `image/jpeg` / `image/png`（封面）
`Content-Length`	文件字节数
`Content-Disposition`	可能含文件名，如 `attachment; filename="task_abc123xyz.mp4"`
响应体	视频或封面二进制数据

错误响应

任务未完成，HTTP 400：

{
  "error": {
    "message": "Task is not completed yet, current status: in_progress",
    "type": "invalid_request_error"
  }
}

任务不存在，HTTP 404：

{
  "error": {
    "message": "Task not found",
    "type": "invalid_request_error"
  }
}

无效 variant，HTTP 400：

{
  "error": {
    "message": "invalid variant \"cover\", must be \"video\" or \"thumbnail\"",
    "type": "invalid_request_error"
  }
}

封面不可用，HTTP 404：

{
  "error": {
    "message": "Thumbnail not available",
    "type": "invalid_request_error"
  }
}

错误格式说明见标准错误。

7. POST `/v1/yunsellai/videos`

多模态视频生成。通过 mode 指定生成模式，通过 assets[] 传入图片/视频 URL。

提交成功后，使用 GET /v1/videos/{task_id} 查询、GET /v1/videos/{task_id}/content 下载。

鉴权：Bearer Token

Content-Type：application/json

生成模式 `mode`

`mode`	说明	典型必填资产
`t2v`	文生视频	无
`i2v`	图生视频	`image`
`first_frame`	首帧生成视频	`first_frame`
`first_last_frame`	首尾帧生成视频	`first_frame`、`last_frame`
`ref_image`	参考图生成视频	至少 1 条 `reference_images`
`video_extend`	视频续写	`source_video`
`video_edit`	视频智能编辑	`source_video`；可选 `reference_images`

各模型启用的 mode 以管理台「模型能力 → 视频能力」配置为准。

请求字段

字段	类型	必填	说明
`model`	string	是	视频模型
`mode`	string	是	生成模式
`prompt`	string	条件	视频描述；多数模式必填
`assets`	array	条件	`[{ "role": "...", "url": "https://..." }]`
`resolution`	string	否	如 `720p`、`1080p`
`duration_sec`	number	否	时长（秒）
`aspect_ratio`	string	否	如 `16:9`、`3:2`
`prompt_optimize`	boolean	否	是否开启 prompt 优化
`gen_tier`	string	否	生成档位
`quality`	string	否	画质
`audio_mode`	string	否	音频模式
`camera_control`	string	否	运镜控制
`shot_type`	string	否	镜头类型
`hd_upscale`	string	否	高清放大

请求示例：文生视频（t2v）

{
  "model": "agnes-video-v2.0",
  "mode": "t2v",
  "prompt": "A cinematic shot of a cat walking on the beach at sunset, soft ocean waves, warm golden lighting, realistic motion",
  "resolution": "720p",
  "duration_sec": 5,
  "aspect_ratio": "3:2",
  "prompt_optimize": false
}

请求示例：首帧图生视频（first_frame）

{
  "model": "agnes-video-v2.0",
  "mode": "first_frame",
  "prompt": "The woman slowly turns around and looks back at the camera, natural facial expression, cinematic camera movement",
  "assets": [
    { "role": "first_frame", "url": "https://example.com/image.png" }
  ],
  "duration_sec": 5
}

请求示例：参考图生视频（ref_image）

{
  "model": "agnes-video-v2.0",
  "mode": "ref_image",
  "prompt": "Create a smooth transformation scene between the two reference images, cinematic lighting, consistent character identity, natural motion",
  "assets": [
    { "role": "reference_images", "url": "https://example.com/image1.png" },
    { "role": "reference_images", "url": "https://example.com/image2.png" }
  ],
  "duration_sec": 5
}

请求示例：视频续写（video_extend）

{
  "model": "wan2.6-t2v",
  "mode": "video_extend",
  "prompt": "Continue the scene with the character walking into the sunset",
  "assets": [
    { "role": "source_video", "url": "https://example.com/source.mp4" }
  ],
  "duration_sec": 5,
  "resolution": "720p"
}

请求示例（curl）

文生视频（t2v）：

curl https://www.yunsell.com/v1/yunsell/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "mode": "t2v",
    "prompt": "A cinematic shot of a cat walking on the beach at sunset, soft ocean waves, warm golden lighting, realistic motion",
    "resolution": "720p",
    "duration_sec": 5,
    "aspect_ratio": "3:2",
    "prompt_optimize": false
  }'

首帧图生视频（first_frame）：

curl https://www.yunsell.com/v1/yunsell/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "mode": "first_frame",
    "prompt": "The woman slowly turns around and looks back at the camera, natural facial expression, cinematic camera movement",
    "assets": [
      {"role": "first_frame", "url": "https://example.com/image.png"}
    ],
    "duration_sec": 5
  }'

参考图生视频（ref_image）：

curl https://www.yunsell.com/v1/yunsell/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "mode": "ref_image",
    "prompt": "Create a smooth transformation scene between the two reference images, cinematic lighting, consistent character identity, natural motion",
    "assets": [
      {"role": "reference_images", "url": "https://example.com/image1.png"},
      {"role": "reference_images", "url": "https://example.com/image2.png"}
    ],
    "duration_sec": 5
  }'

视频续写（video_extend）：

curl https://www.yunsell.com/v1/yunsell/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "mode": "video_extend",
    "prompt": "Continue the scene with the character walking into the sunset",
    "assets": [
      {"role": "source_video", "url": "https://example.com/source.mp4"}
    ],
    "duration_sec": 5,
    "resolution": "720p"
  }'

响应体

HTTP 200

{
  "id": "task_abc123xyz",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600
}

响应字段

与 POST /v1/videos 创建任务响应相同。

字段	类型	说明
`id`	string	任务 ID，用于后续查询和下载
`status`	string	初始为 `queued`
`progress`	integer	进度 0–100
`created_at`	integer	创建时间 Unix 时间戳（秒）

后续查询与下载分别使用 GET /v1/videos/{task_id} 和 GET /v1/videos/{task_id}/content，响应字段见第 5 节与第 6 节。

失败响应

HTTP 400

{
  "code": "invalid_request",
  "message": "model and mode are required"
}

{
  "code": "invalid_request",
  "message": "prompt is required"
}

错误格式说明见任务类错误。

8. 异步视频推荐流程

1. POST /v1/videos 或 POST /v1/yunsellai/videos
   → 获得 task_id

2. 轮询 GET /v1/videos/{task_id}
   → status = queued / in_progress 时继续等待
   → status = failed 时查看 error
   → status = completed 时进入下一步

3. GET /v1/videos/{task_id}/content
   → 下载视频文件

4. （可选）GET /v1/videos/{task_id}/content?variant=thumbnail
   → 下载封面图

建议轮询间隔 3–10 秒，避免过于频繁触发限流。

图像 API

文生图与图生图/编辑，同步返回图片 URL 或 Base64 数据

音频 API

文本转语音（TTS）与音色列表查询