视频生成 API 文档

视频生成统一使用异步任务：先提交 POST /v1/videos 创建任务，再轮询 GET /v1/videos/{task_id} 读取状态和视频地址。

生图 / 生视频

本页是视频生成文档；图片生成请看 图片生成 API 文档。如果你想对照 Apifox 的在线接口目录，可以打开 goswitcher api文档。

基础变量

所有示例都使用 BASE_URL 表示站点根地址，不包含 /v1。切换站点时只改这一行即可。

BASE_URL="https://goswitcher.com"
API_KEY="YOUR_API_KEY"

如何选择接口

场景	模式	模型	接口	结果读取
Omni 文生视频 / 图生视频 / 视频修改	异步	omni_flash-10s 等 Omni 模型	POST /v1/videos	返回任务 ID，最后用任务查询
Veo 文生视频 / 参考图 / 首尾帧	异步	veo_3_1-fast、veo_3_1-fast-fl、veo_3_1-lite-fl 等 Veo 模型	POST /v1/videos	返回任务 ID，最后用任务查询
任务查询	公共查询	任务 ID	GET /v1/videos/{task_id}	从 url、video_url、content_url 或 data[].video_url 读取视频

当前实现说明

/v1/videos 是异步任务接口。当前文档只展示 Omni / Veo 视频模型；模型是否开放，以站点后台配置和 Apifox 在线目录为准。

通用鉴权

Header	必填	说明
Authorization	是	Bearer YOUR_API_KEY
Content-Type	是	JSON 请求使用 application/json；文件上传使用 multipart/form-data

地址变量

BASE_URL 是站点根地址，例如 https://goswitcher.com。不要把它写成 https://goswitcher.com/v1 后再拼 /v1/videos，否则会变成重复路径。

接口详情

Omni 异步视频

项目	内容
Method	POST
Path	/v1/videos
Content-Type	application/json 或 multipart/form-data
返回	任务对象，需要继续查询

请求参数

参数	类型	必填	说明
model	string	是	如 omni_flash-10s；更多档位以 Apifox 在线目录为准
prompt	string	是	视频提示词
size	string	否	视频尺寸，如 1280x720、720x1280
images	string[]	否	JSON 请求使用。图生视频或视频修改时传 URL / Data URL，最多 7 项；JSON 中不要使用 input_reference
input_reference	file 或 string，可重复	否	multipart 请求使用。可传本地图片、本地视频、图片 URL、视频 URL 或 Data URL，最多 7 项
n	integer	否	视频模型只支持 1 或不传；n > 1 会返回错误

调用示例

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni_flash-10s",
    "prompt": "生成一段 10 秒产品广告视频，镜头从正面缓慢推进，背景干净",
    "size": "1280x720",
    "images": [
      "https://example.com/reference-1.jpg"
    ]
  }'

Omni multipart 参考图 / 视频修改

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  --form 'model="omni_flash-10s"' \
  --form 'prompt="参考素材生成一段产品广告视频"' \
  --form 'size="1280x720"' \
  --form 'input_reference=@"/path/to/reference.jpg"'

同一个 input_reference 字段可以重复多次。传本地视频文件时也使用 input_reference=@"/path/to/input.mp4"，配合提示词做视频修改。

任务查询

项目	内容
Method	GET
Path	/v1/videos/{task_id}
用途	查询视频异步任务

路径参数

参数	类型	必填	说明
task_id	string	是	提交接口返回的 id；部分上游也可能返回 task_id

状态字段

status	客户端处理
queued	任务排队中，继续轮询
processing	任务处理中，继续轮询
in_progress	任务处理中，继续轮询
running	任务处理中，继续轮询
completed	任务完成，读取视频结果
failed	任务失败，读取 error 或 error.message

建议每 5 秒左右轮询一次。视频任务通常比图片任务更久，客户端应设置更长超时时间。

结果字段

完成后优先从这些字段读取视频地址：video_url、url、content_url、metadata.video_url、metadata.url、data[].video_url、data[].url、videos[].url。

调用示例

TASK_ID="task_xxxxxxxxxxxxx"

curl -X GET "$BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

视频任务响应示例

{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video",
  "model": "omni_flash-10s",
  "status": "queued",
  "progress": 0,
  "created_at": 1709876543,
  "size": "1280x720"
}

{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video",
  "model": "veo_3_1-lite-fl",
  "status": "completed",
  "progress": 100,
  "created_at": 1709876543,
  "completed_at": 1709876600,
  "size": "1280x720",
  "video_url": "https://example.com/output.mp4"
}

{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video",
  "model": "veo_3_1-lite-fl",
  "status": "failed",
  "progress": 100,
  "error": {
    "message": "上游任务失败原因",
    "code": "upstream_error"
  }
}

常见注意点

• 视频生成全部是异步任务，不会像 image2 同步接口一样直接返回成品。
• 视频模型不支持本地批量 n > 1；如需多条视频，请由客户端多次提交任务。
• JSON 请求使用 images 传参考 URL / Data URL；multipart 请求使用可重复的 input_reference 字段传文件或文本。
• 参考图、参考视频 URL 必须是服务端能访问的直链；需要登录的页面链接、内网地址和本地路径通常不可用。
• 模型是否开放会随站点后台配置、上游资源和风控策略变化。生产环境建议做好模型不可用时的降级逻辑。
• 生成结果地址通常有有效期，任务完成后建议尽快下载保存。