sglang /v1/videos 视频生成接口 完整文档解析

一、接口基础信息

• 请求方式：POST
• 接口路径：/v1/videos
• 接口用途：提交任务创建 AI 生成视频任务
• 请求编码格式：multipart/form-data（表单文件上传格式）
• 无 URL Query 参数，所有入参全部放在请求体表单内

二、请求体全部入参说明

表格

三、返回状态码与响应结构

1. 200 成功提交任务（入参校验通过，任务进入队列）

json

{
  "id": "string",                  // 任务唯一ID，后续查进度/查结果必备
  "object": "video",               // 对象固定标识
  "model": "sora-2",               // 使用的模型名称
  "status": "queued",              // 任务状态：queued排队 / running生成中 / completed完成 / failed失败
  "progress": 0,                   // 生成进度 0~100
  "created_at": 0,                 // 任务创建时间戳
  "size": "",                      // 输出分辨率
  "seconds": "4",                  // 设定视频时长
  "quality": "standard",           // 输出画质等级
  "url": "string",                 // 生成后视频可访问下载链接
  "remixed_from_video_id": "string",// 溯源上一条衍生视频ID
  "completed_at": 0,               // 任务完成时间戳
  "expires_at": 0,                 // 链接过期时间戳
  "error": {},                     // 错误详情，失败时填充
  "file_path": "string",           // 单文件服务器路径
  "file_paths": ["string"],        // 多视频输出文件路径数组
  "num_outputs": 0,                // 实际输出视频条数
  "peak_memory_mb": 0,             // 推理峰值显存占用MB
  "inference_time_s": 0            // 推理耗时秒数
}

2. 422 参数校验错误

入参类型非法、必填项缺失、数值越界、格式错误时返回：

json

{
  "detail": [
    {
      "loc": ["参数层级", 索引],
      "msg": "具体错误说明",
      "type": "错误类型",
      "input": "传入的错误值",
      "ctx": {}
    }
  ]
}

四、curl 请求示例（可直接复制调试）

bash

运行

curl --location --request POST 'http://接口域名/v1/videos' \
--form 'prompt="A cat walking on grass, cinematic lighting"' \
--form 'model="sora-2"' \
--form 'seconds="4"' \
--form 'size="1080x1920"' \
--form 'fps="24"' \
--form 'negative_prompt="blurry, deformed, watermark"' \
--form 'guidance_scale=7.5' \
--form 'num_inference_steps=30'

五、常规业务调用流程

1. 调用本接口提交生成任务，拿到返回的 id
2. 轮询任务查询接口（一般为 /v1/videos/{task_id}）获取 status 与 progress
3. 状态变为 completed 后，读取 url / file_paths 获取成品视频
4. 若 status=failed，读取 error 字段排查失败原因