Skip to Content
API 参考视频生成创建视频任务

创建视频任务

提交一个视频生成任务。请求立即返回 202 Accepted，携带任务 id 与轮询地址——生成过程异步执行。轮询任务或接收 webhook，再用 查询任务状态 读取结果。

POST https://api.ofox.ai/v1/videos

请求参数

参数类型必填说明
modelstring✅模型 slug，如 google/veo-3.1、bytedance/seedance-2.0
promptstring✅视频文本描述
durationinteger—视频秒数
resolutionstring—480p / 720p / 1080p / 1K / 2K / 4K
aspect_ratiostring—16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9 / 9:21
sizestring—精确像素 WIDTHxHEIGHT（如 1280x720），替代 resolution + aspect_ratio
frame_imagesarray—帧控制（图生视频 / 首尾帧）。传入即视为 image-to-video，见下
input_referencesarray—引导 subject / 风格（参考图生视频），非精确帧锚点，见下
generate_audioboolean—支持音频输出的模型默认 true
seedinteger—确定性生成种子（不保证所有 provider 支持）
callback_urlstring—终态 webhook 通知地址，必须 HTTPS（见 Webhook）
providerobject—provider 特有参数透传，见 Provider 透传

frame_images[] 元素

每个元素锚定输出的一帧，frame_type 取 first_frame 或 last_frame。

{
  "type": "image_url",
  "image_url": { "url": "https://example.com/first.jpg" },
  "frame_type": "first_frame"
}

input_references[] 元素

按 type 传图片 / 音频 / 视频参考（引导 subject / 风格 / 一致性，非精确帧锚点）：

{ "type": "image_url", "image_url": { "url": "https://example.com/subject.jpg" } }
{ "type": "audio_url", "audio_url": { "url": "https://example.com/voice.mp3" } }
{ "type": "video_url", "video_url": { "url": "https://example.com/ref.mp4" } }
媒体type数量上限其他约束
图片image_url≤ 9—
音频audio_url≤ 3单段 ≤ 15 秒
视频video_url≤ 1—

超出任一上限返回 400 too_many_references（见 错误码）。

frame_images 与 input_references 互斥——一个请求只能用其中一种，不能同时传。同时传返回 400 references_conflict。

模式判定（隐式）

无 gen_mode 字段。模式由传入的输入字段隐式判定：

模式判定条件
text2video不传 frame_images 与 input_references
img2videoframe_images 含 1 个 first_frame
img2video_endframe_images 含 first_frame + last_frame
imgref2videoinput_references 仅图片
mixref2videoinput_references 内含图 / 音 / 视混合

响应

202 Accepted——任务受理，返回 status: "pending" 与 polling_url：

{
  "id": "9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718",
  "status": "pending",
  "polling_url": "https://api.ofox.ai/v1/videos/9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718"
}

轮询 polling_url（或等待 webhook）直到任务进入终态——见 查询任务状态。

请求示例大全

一套 /v1/videos schema 覆盖全部生成模式，模式由输入字段隐式判定。下方每个示例均可直接运行。

不传 frame_images / input_references → 文生视频。

Terminal
curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1",
    "prompt": "A golden retriever running on the beach at sunset",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

可叠加选项

以下字段正交于生成模式——可叠加在上面任意一种请求体上。

任务进入终态时在你的地址收到一次 POST 推送，替代轮询。

{
  "model": "google/veo-3.1",
  "prompt": "...",
  "callback_url": "https://your-app.example/webhooks/ofox-video"
}

callback_url 必须 HTTPS。推送体与签名见 Webhook。

Provider 透传

provider 特有参数通过 provider.options.<slug> 传递——仅匹配到的 provider 会收到。像 watermark 这类参数并非所有模型都支持，因此放进 provider 透传而非顶层字段（对齐 OpenRouter 的 provider 透传设计）。各模型支持哪些透传参数以模型能力为准。

{
  "model": "alibaba/wan-2.7",
  "prompt": "...",
  "provider": {
    "options": {
      "dashscope": { "watermark": false, "audio_setting": "..." }
    }
  }
}
Last updated on
概览查询任务