视频生成总览

大约 5 分钟

视频生成总览

Sora-2、Veo 3.1、Grok-Video 都走同一个视频任务接口。视频生成不是同步接口，正确流程是：创建任务、保存任务 ID、轮询状态、完成后下载视频。

接口结论

Base URL：https://www.yuzhixiaolongxia.com/v1
创建任务：POST /v1/videos
查询任务：GET /v1/videos/{task_id}
下载视频：GET /v1/videos/{task_id}/content
认证方式：HTTP Header Authorization: Bearer <你的 API 令牌>
令牌分组：sora-veo-grok-video
任务模式：异步任务（提交 -> 轮询 -> 下载）

接入注意

这组视频模型不要按聊天接口调用，也不要用 /v1/chat/completions。
创建任务成功只代表平台已受理，不代表视频已经生成成功。
图生视频必须显式传 image、images 或 input_reference，只在 prompt 里写“这张图片”不会自动带图。
API Key 只能放服务端或本地工具配置里，不要写进前端代码、公开仓库或截图。

当前可用模型与售价

模型 ID	定位	输入能力	常用时长 / 尺寸	当前售价
`sora-2`	标准 Sora-2 视频	文生 / 图生	`4` / `8` / `12` 秒，`1280x720` 或 `720x1280`	`0.308 元/秒`
`sora-2-pro`	高规格 Sora-2 视频	文生 / 图生	`4` / `8` / `12` 秒，可用高规格尺寸	`0.308 元/秒`，高规格尺寸会放大预扣
`veo3.1-fast`	Veo 3.1 快速版	文生 / 图生	建议 `8` 秒，适合试稿	`0.308 元/秒`
`veo3.1-pro`	Veo 3.1 高质版	文生 / 图生	建议 `8` 秒，适合终稿	`1.538 元/秒`
`grok-video`	Grok 视频	文生 / 图生	建议 `10` / `15` / `30` 秒	`0.431 元/秒`

价格以模型广场和控制台调用日志为准。接入程序里不要把旧价格表写死，调用前可以让运营从模型广场复核一次。

异步工作流

POST /v1/videos                   -> 创建任务，返回 id/task_id
GET  /v1/videos/{task_id}         -> 轮询任务状态
GET  /v1/videos/{task_id}/content -> 下载 mp4 文件

建议创建任务后等 8-10 秒再首次查询，之后每 8-15 秒轮询一次。不要因为一次 queued 或 in_progress 就重复提交，否则可能产生多笔预扣。

高规格模型排队更久，偶发 failed 或 task timeout 时按失败任务处理：记录响应体，等待退款入账，再降低时长 / 尺寸或换快速模型重试。

通用请求字段

字段	类型	必填	说明
`model`	string	是	只能填当前真实可用模型 ID
`prompt`	string	是	视频描述，写清主体、动作、镜头、画面比例
`seconds`	string/int	否	视频秒数。建议显式传，便于对账
`duration`	int	否	兼容字段；新接入优先用 `seconds`
`size`	string	否	画面尺寸/规格。不同模型接受范围不同，见模型专页
`image`	string	否	单张参考图 URL 或 base64
`images`	string[]	否	多张参考图 URL/base64 列表
`input_reference`	file/string	否	multipart 文件字段，或兼容的参考图字段

图生视频规则很简单：要让模型看图，必须真的传 image、images 或 input_reference。prompt 里可以写 “use image 1”，但那只是引用，不会替你上传图片。

响应与状态机

创建任务响应里优先读 id，如果只有 task_id 也要兼容：

{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1717000000,
  "seconds": "8"
}

status	本地动作
`queued` / `pending`	排队中，继续轮询
`in_progress` / `processing`	生成中，继续轮询
`completed` / `succeeded` / `success`	读取视频 URL 或调用下载接口
`unknown`	有视频 URL 就按完成处理；没有 URL 继续轮询
`failed` / `cancelled`	停止轮询，保存错误信息，等待预扣回退

完成后视频地址可能出现在 metadata.url、data[0].url、result_url、url、video_url、output_url、download_url 等字段。拿不到 URL 时再调用 /content 兜底下载。

最小 curl 示例

curl -X POST "https://www.yuzhixiaolongxia.com/v1/videos" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A cinematic close-up of a steaming bowl of crawfish, steam rising, slow camera push in, realistic food commercial style",
    "seconds": "8",
    "size": "1280x720"
  }'

查询任务：

curl "https://www.yuzhixiaolongxia.com/v1/videos/task_xxx" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

下载视频：

curl -L "https://www.yuzhixiaolongxia.com/v1/videos/task_xxx/content" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  --output result.mp4

图生视频示例

JSON 图片 URL：

curl -X POST "https://www.yuzhixiaolongxia.com/v1/videos" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-fast",
    "prompt": "Use image 1 as the first frame. The camera stays fixed, the person smiles and waves, realistic indoor lighting",
    "seconds": "8",
    "size": "1280x720",
    "images": [
      "https://example.com/reference.jpg"
    ]
  }'

multipart 本地文件：

curl -X POST "https://www.yuzhixiaolongxia.com/v1/videos" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -F "model=grok-video" \
  -F "prompt=Use the uploaded image as the scene. The camera slowly pans right, natural motion" \
  -F "seconds=10" \
  -F "input_reference=@reference.jpg"

计费口径

视频任务创建时会按请求参数预扣，任务失败后会回退预扣。估算公式：

预扣金额 = 当前售价（元/秒） × seconds × 尺寸系数

不传 seconds 时会使用模型默认秒数；为了对账清楚，生产接入必须显式传 seconds。
常规尺寸的尺寸系数为 1。
sora-2-pro 的 1792x1024 / 1024x1792 属于高规格尺寸，预扣会高于常规尺寸。
最终扣费和退款以控制台「调用日志」为准。

常见错误

错误/现象	常见原因	处理方式
`prompt is required`	请求已进入视频端点，但没传 `prompt`	补 `prompt`
`model not found`	模型 ID 拼错	只用本页列出的 5 个 ID，并从模型广场复制
`401`	令牌错误	重新创建令牌并完整复制
`403 quota_exceeded`	余额不足	充值后重试
图生视频没参考图效果	没传图片字段，只在 prompt 写“这张图片”	传 `image`、`images` 或 `input_reference`
任务 `failed` / `task timeout`	队列繁忙、高规格任务等待过久或内容不适合生成	保存错误响应，等退款后降低规格或换快速模型重试
一直 `queued`	还在排队	不要重复提交；超过 5 分钟再按超时策略处理

下一步

上一步：绘图模型总览