Google Gemini Omni Flash 视频生成接口:6 / 8 / 10 秒,720P / 1080P,横屏或竖屏,按秒计费,固定带声音。支持文生视频、首帧、首尾帧和最多 3 张参考图。异步任务,失败不收费。
在 Playground 试用 →快速开始
三步跑通:提交任务 → 查询结果 → 拿到视频链接。把 YOUR_API_KEY 换成你的 Key,下面的命令可以直接运行。
第 1 步 · 提交任务(立刻返回任务号,HTTP 202)
curl https://kovapi.com/v1/videos/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gemini-omni-flash", "prompt": "一杯冰咖啡放在木桌上,冰块缓缓转动,水珠沿杯壁滑落", "duration": 8, "resolution": "720P", "size": "16:9"}'返回(HTTP 202)
{
"id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
"object": "video.generation.job",
"status": "queued",
"created": 1791281400,
"model": "gemini-omni-flash"
}第 2 步 · 每 5–10 秒查询一次,直到 status 变成 succeeded 或 failed
curl https://kovapi.com/v1/videos/jobs/img_5c2e8f1a9b3d7e6f0a4c8b2d \ -H "Authorization: Bearer YOUR_API_KEY"
成功时的返回
{
"id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
"object": "video.generation.job",
"status": "succeeded",
"created": 1791281400,
"model": "gemini-omni-flash",
"data": [
{"url": "https://img.kovapi.com/i/8c1f0e5d2b7a49e3a6d0c4f1b9e2a7d5.mp4"}
],
"usage": {"clips": 1, "model": "gemini-omni-flash"}
}第 3 步 · data[0].url 就是成片(MP4),保留 7 天;需要长期使用,请下载到你自己的存储。
完整示例(Python:提交 → 等待 → 保存到本地)
import time
import requests
BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
# 1. 提交任务
job = requests.post(f"{BASE}/videos/generations", headers=HEADERS, json={
"model": "gemini-omni-flash",
"prompt": "一杯冰咖啡放在木桌上,冰块缓缓转动,水珠沿杯壁滑落",
"duration": 8,
"resolution": "720P",
"size": "16:9",
}).json()
if "error" in job:
raise SystemExit(job["error"]["message"])
# 2. 每 10 秒查询一次,最多等一小时
deadline = time.time() + 3600
while job["status"] not in ("succeeded", "failed") and time.time() < deadline:
time.sleep(10)
job = requests.get(f"{BASE}/videos/jobs/{job['id']}", headers=HEADERS).json()
# 3. 下载视频
if job["status"] == "succeeded":
url = job["data"][0]["url"]
with open("gemini-omni-flash.mp4", "wb") as f:
f.write(requests.get(url).content)
print("saved", url)
elif job["status"] == "failed":
print("failed:", job["error"]["code"], job["error"]["message"])
else:
print("still", job["status"], job["id"])排队时,查询结果里还有 queue_position(前面还有几个任务)和 eta_seconds(预计还要等几秒)。超过你设的等待时间也不要重新提交:任务还在,稍后用同一个任务号接着查。
认证
Authorization: Bearer YOUR_API_KEY Content-Type: application/json
在控制台创建 API Key 后即可调用。
规格速览
| 时长 | 6 / 8 / 10 秒 |
| 分辨率 | 720P / 1080P |
| 画面比例 | 16:9 / 9:16 |
| 参考图 | 最多 3 张 · 1 张作首帧,2 张作首尾帧,3 张作参考 |
| 参考视频 | 不支持 |
| 参考音频 | 不支持 |
| 声音 | 固定带声音,不能关(传 audio: false 会被拒绝) |
| 提示词长度 | 最多 20,000 个字符(中英文一样计) |
| 计费方式 | 按秒:每秒单价 × 下单的秒数 |
请求参数
POST /v1/videos/generations 的请求体(JSON):
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型 id:gemini-omni-flash。 |
| prompt | string | 是 | 画面、镜头和动作的描述,最多 20,000 个字符(中英文一样计)。 |
| duration | integer | 否 | 时长(秒),只能是 6 / 8 / 10,不传为 6。 |
| resolution | string | 否 | 分辨率:720P / 1080P,不传为 720P。请带上 P(720 这样不带 P 的写法会被拒绝)。 |
| size | string | 否 | 画面比例:16:9 / 9:16,不传为 16:9。也可以写作 aspect_ratio。 |
| images | array | 否 | 参考图,最多 3 张:1 张作首帧;2 张作首尾帧;3 张作参考图。只有一张时也可以放在 image。 |
| image_role | string | 否 | 参考图怎么用:first_frame(首帧或首尾帧,最多 2 张)或 reference(1–3 张参考图,人物或风格会出现在视频里,但不作为某一帧)。不传时 1–2 张按首帧、3 张按参考。 |
| audio | boolean | 否 | 成片固定带声音,不能关闭;传 false 会被拒绝(400),可以不传。 |
| callback_url | string | 否 | 任务结束时把结果推送到这个地址,见下文的 Webhook。 |
| n | integer | 否 | 每个任务出 1 条视频,不用传。传了大于 1 的值也只出 1 条,但提交时会按 n 条预扣,任务结束后退回多扣的部分。 |
其他字段(如 seed、negative_prompt、fps、watermark)不会转发,也不影响价格;成片一律是 MP4,通过 url 返回。
价格
按秒计费:费用 = 所选分辨率的每秒单价 × 下单的秒数。提交时按这个金额预扣,成功按同样的金额结算,失败全额退回。1 积分 = $0.005。
| 分辨率 | 积分 / 秒 | 美元 / 秒 | 8 秒一条 |
|---|---|---|---|
| 720P | 7 | $0.035 | $0.28 |
| 1080P | 10 | $0.05 | $0.40 |
参考素材
- 不带图是文生视频;1 张图作首帧;2 张图作首尾帧;3 张图,或加
image_role: reference的 1–3 张图,作参考图。 - 不支持参考视频和参考音频。时长只能是 6、8 或 10 秒,固定带声音。
- 每张图可以是公网图片链接、
data:URI 或 base64,单张不超过 16MB,多张用数组放在images里。提交时我们先把图片转存好再排队;读不到的图片会直接返回 400,message写明是第几张,这一单不计费。 - 我们转存的参考素材和成片都保留 7 天。
参考图:产品出现在竖屏视频里
curl https://kovapi.com/v1/videos/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gemini-omni-flash", "prompt": "这款香水瓶在大理石台面上旋转,光线从侧面扫过", "images": ["https://example.com/product.png"], "image_role": "reference", "duration": 8, "size": "9:16"}'image_role: reference 让图片作参考图,而不是首帧;不加时 1 张图作首帧。
任务状态与返回字段
GET /v1/videos/jobs/{id} 返回这些状态,各字段的说明见 异步任务。每 5–10 秒查一次,或者用下面的 Webhook 等推送。查询不收费,同一个账号的任何 Key 都能查。
| 状态 | 含义 |
|---|---|
| queued | 排队中。返回里带 queue_position(前面还有几个任务)和 eta_seconds(预计等待秒数)。 |
| processing | 生成中。 |
| succeeded | 已完成。结果在 data[0].url,计费明细在 usage。 |
| failed | 失败。原因在 error,预扣的积分已全额退回。 |
processing有时会回到queued:例如服务繁忙、成片正在重新取回,或者服务重启。任务没能完成时,网关可能自动重新生成;无论重试几次,一个任务只扣一次费用。- 同一个账号最多 50 个任务同时生成,更多的任务按提交顺序排队;排队超过 15 分钟还没开始的任务会自动失败并全额退款。任务记录保留 3 天,视频链接保留 7 天。
出片时间
一般 1–3 分钟。
错误与退款
提交时出错会直接返回 HTTP 4xx / 5xx,不建任务、不扣费;提交成功后的失败写在查询结果里,预扣的积分全额退回。全部错误码见 错误码。
提交时返回的错误
| HTTP | code | 原因 | 怎么办 |
|---|---|---|---|
| 400 | invalid_request | 参数不合法:时长、分辨率、比例或素材数量超出这个模型的范围,提示词太长,参考图或参考视频读不到,或者给固定带声音的模型传了 audio: false 等。message 写明原因。 | 按 message 修改后重新提交。 |
| 400 | invalid_callback_url | callback_url 不是公网的 http(s) 地址,或超过 2000 个字符。 | 换成能从公网访问的地址。 |
| 400 | model_not_found | 型号写错、没有传 model,或这个型号不能用在这个接口上(例如拿对话模型调生图接口)。 | 以 GET /v1/models 或 API 手册 里的模型 id 为准。 |
| 401 | invalid_api_key | Key 不存在、已删除或已停用,或者账号已停用。 | 到控制台「API Keys」页面检查这把 Key。 |
| 402 | insufficient_quota | 余额不够预扣这一单。网关先按这一单可能的最高费用预扣,同时发很多请求时也可能出现。 | 如果是并发突发,稍等几秒重试;否则充值。 |
| 429 | rate_limit_exceeded | 超过了这把 Key 设置的每分钟请求数(按最近 60 秒计)。不带 Retry-After。 | 等几秒再试,或在控制台调高这把 Key 的上限。 |
| 503 | model_maintenance | 型号维护中,暂停接单,期间不会改由其他模型作答。 | 维护结束后重试,进度见 服务状态。 |
| 503 | service_unavailable | 我们这边临时出错,例如保存参考素材失败。这一单没有创建任务,也没有扣费。 | 稍后重试。 |
任务失败(status 为 failed)
| code | 什么时候出现 | 怎么办 |
|---|---|---|
| content_policy | 提示词或参考图没有通过模型方的内容审核。 | 改写提示词或更换素材后再提交;原样重交还会被拒。 |
| invalid_request | 模型方不接受这组参数(例如这个模式和分辨率的组合)。message 写明原因。 | 按 message 调整参数后再提交。 |
| wait_timeout | 视频:超过 120 分钟仍未生成结果,按超时处理,积分全额退还;之后如果生成成功,视频免费交付。 | 重新提交。 |
| upstream_error | 其他失败:自动重试后仍然失败、排队 15 分钟还没开始、上游拒绝但没有说明原因等,message 写明具体情况。 | 通常重新提交就能成功。 |
请按 code 判断,不要匹配 message 的文字。遇到不认识的 code(或者没有 code),按 upstream_error 处理:重新提交通常就能成功。失败的任务一律全额退款。
用 Webhook 代替轮询
提交时加上 callback_url,任务一结束(成功或失败),网关就把和查询接口完全一样的结果推送到这个地址,带签名,失败会自动重试。也可以在控制台「设置 → Webhook」里配一个账户级地址。 Webhook 文档 →
curl https://kovapi.com/v1/videos/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gemini-omni-flash", "prompt": "一杯冰咖啡放在木桌上,冰块缓缓转动,水珠沿杯壁滑落", "duration": 8, "resolution": "720P", "size": "16:9", "callback_url": "https://your-domain.com/webhook"}'