创建视频任务
提交一个视频生成任务。请求立即返回 202 Accepted，携带任务 id 与轮询地址——生成过程异步执行。轮询任务或接收 webhook，再用 查询任务状态 读取结果。
POST https://api.ofox.io/v1/videos请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | ✅ | 模型 slug，如 bytedance/seedance-2.5、bytedance/seedance-2.0 |
prompt | string | ✅ | 视频文本描述 |
duration | integer | — | 视频秒数 |
resolution | string | — | 480p / 720p / 1080p / 1K / 2K / 4K |
aspect_ratio | string | — | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9 / 9:21 |
size | string | — | 精确像素 WIDTHxHEIGHT（如 1280x720），替代 resolution + aspect_ratio |
frame_images | array | — | 帧控制（图生视频 / 首尾帧）。传入即视为 image-to-video，见下 |
input_references | array | — | 引导 subject / 风格（参考图生视频），非精确帧锚点，见下 |
real_person | boolean | — | 默认 false。真人参考图设为 true，服务端会在生成前自动预处理；至少需要一张图片引用 |
generate_audio | boolean | — | 支持音频输出的模型默认 true |
seed | integer | — | 确定性生成种子（不保证所有 provider 支持） |
callback_url | string | — | 终态 webhook 通知地址，必须 HTTPS（见 Webhook） |
provider | object | — | type 指定承载供应商，options 透传 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。
real_person：真人参考图
Ofox 一步式直传流程、与 Seedance 人像资产入库的对比，以及图片被拒后的实用调整建议，见真人参考图。
当参考图包含可识别的真人形象时，将顶层 real_person 设为 true。Ofox 会在提交生成任务前，对所选参考字段中的每张图片自动进行脱敏预处理。默认值为 false，现有请求行为不变。
{
"model": "bytedance/seedance-2.0",
"prompt": "让画面中的人物走过电影感夜市",
"real_person": true,
"input_references": [
{
"type": "image_url",
"image_url": { "url": "https://example.com/person.jpg" }
}
]
}real_person 可与 frame_images 或 input_references 中的图片配合使用，但这两个字段仍然互斥。请求中至少需要一张图片，否则返回 400 invalid_request。
预处理可以减少上游反深伪审核的误拒，但不会绕过内容政策，也不保证一定通过。上游仍可能拒绝任务；拒绝后不计费，可修正输入或重试。图片输入问题见real_person 图片预处理错误。
模式判定（隐式）
无 gen_mode 字段。模式由传入的输入字段隐式判定：
| 模式 | 判定条件 |
|---|---|
text2video | 不传 frame_images 与 input_references |
img2video | frame_images 含 1 个 first_frame |
img2video_end | frame_images 含 first_frame + last_frame |
imgref2video | input_references 仅图片 |
mixref2video | input_references 内含图 / 音 / 视混合 |
响应
202 Accepted——任务受理，返回 status: "pending" 与 polling_url：
{
"id": "9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718",
"status": "pending",
"polling_url": "https://api.ofox.io/v1/videos/9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718"
}轮询 polling_url（或等待 webhook）直到任务进入终态——见 查询任务状态。
请求示例大全
一套 /v1/videos schema 覆盖全部生成模式，模式由输入字段隐式判定。下方每个示例均可直接运行。
文生视频
不传 frame_images / input_references → 文生视频。
# 可选：指定供应商；不传则由平台自动分流
# "provider": { "type": "byteplus" }
curl -X POST https://api.ofox.io/v1/videos \
-H "Authorization: Bearer $OFOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "bytedance/seedance-2.5",
"prompt": "A golden retriever running on the beach at sunset",
"duration": 5,
"resolution": "1080p",
"aspect_ratio": "16:9",
"generate_audio": true
}'可叠加选项
以下字段正交于生成模式——可叠加在上面任意一种请求体上。
Webhook（callback_url）
任务进入终态时在你的地址收到一次 POST 推送，替代轮询。
{
"model": "bytedance/seedance-2.5",
"prompt": "...",
"callback_url": "https://your-app.example/webhooks/ofox-video"
}callback_url 必须 HTTPS。推送体与签名见 Webhook。