API 协议
Gemini Omni:参数、场景与调用指南
预览指南
粘贴给 AI,帮助理解文档并完成接入。 仅包含文档与示例,不包含真实密钥。
直接答案prompt 与 input 二选一;input 为文本或素材数组。input_reference 仅接收 JPG/PNG/WebP 图片 URI,不能放视频或 task_id。
更新 · 审核信息
模型定位与适用场景
视频生成与多轮编辑系列。本站的图片参考、外部视频输入和已有任务编辑使用不同字段;协议可解析不代表该场景已通过出片验收。
本指南核对本站请求契约,不代表所有场景均已完成收费出片验收。使用模型广场显示的精确模型、分组和有效端点;示例中的 example.com 素材与占位任务 ID 必须替换。先以最小请求确认可用,再逐项添加参考素材和高级参数。价格以模型广场及实际账单为准。
型号与入口
gemini-omni-1.1-flash, gemini-omni-1.2-flash
POST /v1/videos
参考素材格式
| 素材 | 字段 | 传输格式 | 文件准备与限制 |
|---|---|---|---|
| 图片参考 | input_reference 或 input[] (type=image) | input_reference 仅 JPG/PNG/WebP HTTP(S) 图片 URL;input 图片项可用 uri,或 mime_type + 原始 Base64 data,二选一。 | data 不带 data:image/...;base64, 前缀;MIME 用 image/jpeg、image/png、image/webp。图片 URL 的支持不能外推到视频。 |
| 参考 / 编辑视频 | input[]: type=video, mime_type=video/mp4, data | 本示例将视频转为原始 Base64 放 data,不传完整 data:video/mp4;base64,...。适配器也转发 uri,但既有视频 URL 实测生成失败;本示例同样未通过出片验收。 | 本地 MP4 读取二进制后编码;只有 URL 时先在自己的程序下载再编码。prompt 与 input 二选一。大内联视频目前存在任务保存失败,未完成普遍可用验收。 |
| 参考音频 | — | 当前视频入口 input 仅接受 text/image/video,未开放 audio 项、reference_audio 或 voice_id。 | 生成含音轨的视频不代表支持独立参考音频输入。 |
| 任务 / 素材 ID | previous_interaction_id + generation_config.video_config.task | 使用本人可访问的成功本站 task_ ID;不是视频 URL,也不是 input[].data。 | edit/extend 的任务接续与上传参考视频是两条不同流程;已有编辑 400 记录,不能用 Base64 参考测试替代编辑验收。 |
参数与组合限制
- prompt 与 input 二选一;input 为文本或素材数组。input_reference 仅接收 JPG/PNG/WebP 图片 URI,不能放视频或 task_id。
- 1.1 支持 3–10 秒,1.2 支持 3–15 秒;延展和已有任务续作最多 10 秒。默认 10 秒、720p;不要发送 watermark。
- 参考视频示例使用 input[].type=video、mime_type=video/mp4、data=原始Base64。适配器也接受视频 uri,但既有视频 URL 实测在上游生成阶段失败;这两种形式都不能宣称已通过出片验收。
- 已有任务使用顶层 previous_interaction_id,值为本人可访问且成功的本站 task_ ID;不是 input_reference。edit/extend 放 generation_config.video_config.task。
- 图片和视频项均可被适配器解析为 uri 或原始 Base64 data;视频示例使用 data,但尚未通过出片验收。data 不带 data URL 前缀,mime_type 单独填写。本站没有通用 Google Files 上传入口。
- 2026-11-15 业务站 1.1 Flash 对照测试:3 秒文生成功;公网视频输入、previous_interaction_id 加 task=edit 均受理后失败,终态为 Synchronous video request failed (HTTP 400)。1.2 和 extend 未在本轮实测,不外推结论。
- 2026-11-15 Base64 对照:业务站 1.1 的小 MP4 能建任务,但仍在生成阶段失败(HTTP 400);较大内联视频在保存任务时失败。因此修正传输格式不等于参考视频已验收,1.2 尚未实测。
- 官方 1.2 参考图最多 6 张;3–10 秒输出可参考最多 3 段各 ≤3 秒视频,11–15 秒输出最多 1 段。编辑输入视频 ≤15 秒;延长每次 3–10 秒、总长 ≤30 秒。本站仍需满足上方素材传输与验收限制。
- 官方不支持音频参考、声音编辑、system instructions 或 negative prompt 独立字段;所有输出均含不可见 SynthID 水印,没有关闭开关。
| 字段 | 类型 | 用法与限制 |
|---|---|---|
Authorization | header string | 必填。Bearer <本站 API Key>;JSON 请求使用 Content-Type: application/json。 |
model | string | 必填,gemini-omni-1.1-flash 或 gemini-omni-1.2-flash。 |
prompt | string | 本站文本快捷方式,与 input 互斥;可配 input_reference。 |
input | string / object[] | 官方文本或结构化多模态输入;本站不接受与 prompt/input_reference 重复。 |
input[].type | string | 必填 text/image/video;当前 API 不支持独立音频输入。 |
input[].text | string | type=text 时必填,用自然语言说明首帧、尾帧、参考、编辑目标;不要使用已弃用的 <FIRST_FRAME> 等控制标签。 |
input[].mime_type | string | 图片/视频必填且与内容一致,例如 image/png、image/jpeg、video/mp4。 |
input[].uri | string | 本站适配器接受并转发图片或视频的公开 HTTP(S) URI;但既有 1.1 视频 URI 实测受理后在上游生成阶段失败,不能据转发成功认定可出片,1.2 未验收。 |
input[].data | string | 媒体原始 Base64 字节,不带 data URI 前缀;与 uri 二选一。视频示例使用此字段;这不代表已通过出片验收,已知持久化与生成失败限制见条件示例。 |
input_reference | string | 本站单图快捷方式,配 prompt;URL 后缀须可识别为 JPG/PNG/WebP,否则用 input 并显式 mime_type。 |
seconds | integer / string | 本站时长快捷方式,默认 10;1.1 为 3–10 秒,1.2 普通生成 3–15 秒;首尾帧及本站已有任务接续仍至多 10 秒。 |
size | string | 本站像素尺寸快捷方式,横竖屏对应 360p/720p/1080p/4k;默认 1280x720。与 response_format 的对应设置不要重复。 |
response_format.type | string | 本站固定 video,由适配器补全。 |
response_format.duration | string | 例如 3s、8s;与 seconds 二选一,适用相同版本和模式时长限制。 |
response_format.resolution | string | 360p/720p/1080p/4k,默认 720p;不要与 size 重复。 |
response_format.aspect_ratio | string | 16:9(默认)或 9:16。 |
response_format.delivery | string | 本站固定 uri,使用成功任务的视频 URL;官方可直接返回 Base64,但本站示例不支持切换为内联输出。 |
response_format.fps | integer | 本站兼容项,只接受 24;模型固定帧率,不是官方 response_format 字段,转发前移除。 |
generation_config.video_config.task | string | 可选 text_to_video/image_to_video/reference_to_video/edit/extend;优先用自然语言,只有模型无法选对模式时再指定,指定后会收紧素材约束。 |
generation_config.temperature / generation_config.top_p | number | 官方 Omni 明确不支持,即使本站对象接受也不应发送。 |
generation_config.seed / generation_config.max_output_tokens | integer | 本站允许转发的通用 Interactions 配置,但当前 Omni 指南未确认视频效果或取值范围;不作为可用的视频控制,已从普通示例移除。 |
previous_interaction_id | string | 本站必须使用本人可访问、已成功且同渠道/兼容凭据的 task_ ID;会映射为官方 interaction ID。每次接续 ≤10 秒,不是上传视频 URL。 |
background / stream / store | official controls | 本站异步视频仅兼容 background=true、stream=false,执行方式由渠道管理;store 不开放。不要照搬官方 Interactions 的其他执行模式。 |
场景与代码示例
本地 MP4 转 Base64 请求(仅生成 JSON)
运行下面任一脚本,读取本地 action.mp4 并写入 request.json;不会发送请求或计费。已有 URL 请先在自己的程序下载为本地文件,不能把 URL 字符串编码来冒充视频字节。MIME 必须与文件一致。当前较大 Base64 输入存在任务保存失败,小样本生成也仍有 400;不要自动重试 POST。编码后的 1 MiB 检查只是当前请求上限,不保证更小请求可成功。
import base64
import json
from pathlib import Path
# Use a small local MP4. This prepares JSON; it does not submit a paid task.
video = Path("action.mp4").read_bytes()
if not video:
raise ValueError("Empty video")
request = {
"model": "gemini-omni-1.1-flash", # Selected marketplace model
"input": [
{"type": "text", "text": "参考视频动作,创作新的花园场景。"},
{"type": "video", "mime_type": "video/mp4",
"data": base64.b64encode(video).decode("ascii")},
],
"seconds": "3",
"size": "640x360",
}
encoded = json.dumps(request, ensure_ascii=False).encode("utf-8")
# Current request-path ceiling, NOT a guarantee that smaller inputs will succeed.
if len(encoded) > 1024 * 1024:
raise ValueError("Encoded JSON exceeds the current 1 MiB request-path ceiling")
with Path("request.json").open("xb") as output:
output.write(encoded)
# No top-level prompt, no uri, no data:video/mp4;base64, prefix.
import { readFileSync, writeFileSync } from 'node:fs';
// Prepare JSON only; this does not submit a paid task.
const video = readFileSync('action.mp4');
if (!video.length) throw new Error('Empty video');
const request = {
model: 'gemini-omni-1.1-flash', // Selected marketplace model
input: [
{ type: 'text', text: '参考视频动作,创作新的花园场景。' },
{ type: 'video', mime_type: 'video/mp4', data: video.toString('base64') },
],
seconds: '3',
size: '640x360',
};
const encoded = JSON.stringify(request);
// Current request-path ceiling, NOT a guarantee of successful generation.
if (Buffer.byteLength(encoded) > 1024 * 1024) {
throw new Error('Encoded JSON exceeds the current 1 MiB request-path ceiling');
}
writeFileSync('request.json', encoded, { flag: 'wx' });
// No top-level prompt, no uri, no data:video/mp4;base64, prefix.
需验证调用时,使用本页总览中的提交、轮询和下载脚本读取 request.json;只有一个 POST,之后凭本站任务 ID 查询。
文生视频
适用型号:gemini-omni-1.1-flash, gemini-omni-1.2-flash
POST /v1/videos
{
"model": "gemini-omni-1.2-flash",
"prompt": "一颗玻璃球沿木制轨道滚动,连续镜头。",
"seconds": "8",
"size": "1280x720"
}
curl
curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "gemini-omni-1.2-flash",
"prompt": "一颗玻璃球沿木制轨道滚动,连续镜头。",
"seconds": "8",
"size": "1280x720"
}'
python
import json
import os
import requests
url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
if not os.environ.get(name, "").strip():
raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"gemini-omni-1.2-flash\",\"prompt\":\"一颗玻璃球沿木制轨道滚动,连续镜头。\",\"seconds\":\"8\",\"size\":\"1280x720\"}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))
javascript
// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
"model": "gemini-omni-1.2-flash",
"prompt": "一颗玻璃球沿木制轨道滚动,连续镜头。",
"seconds": "8",
"size": "1280x720"
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));
单图参考
适用型号:gemini-omni-1.1-flash, gemini-omni-1.2-flash
POST /v1/videos
{
"model": "gemini-omni-1.2-flash",
"prompt": "保持图片中的人物外观,让人物向镜头挥手。",
"input_reference": "https://example.com/subject.png",
"seconds": "8",
"size": "720x1280"
}
curl
curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "gemini-omni-1.2-flash",
"prompt": "保持图片中的人物外观,让人物向镜头挥手。",
"input_reference": "https://example.com/subject.png",
"seconds": "8",
"size": "720x1280"
}'
python
import json
import os
import requests
url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
if not os.environ.get(name, "").strip():
raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"gemini-omni-1.2-flash\",\"prompt\":\"保持图片中的人物外观,让人物向镜头挥手。\",\"input_reference\":\"https://example.com/subject.png\",\"seconds\":\"8\",\"size\":\"720x1280\"}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))
javascript
// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
"model": "gemini-omni-1.2-flash",
"prompt": "保持图片中的人物外观,让人物向镜头挥手。",
"input_reference": "https://example.com/subject.png",
"seconds": "8",
"size": "720x1280"
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));
多图与精确输出格式
适用型号:gemini-omni-1.1-flash, gemini-omni-1.2-flash
POST /v1/videos
{
"model": "gemini-omni-1.2-flash",
"input": [
{
"type": "text",
"text": "人物在第二张图的场景中行走。"
},
{
"type": "image",
"mime_type": "image/png",
"uri": "https://example.com/subject.png"
},
{
"type": "image",
"mime_type": "image/png",
"uri": "https://example.com/end.png"
}
],
"response_format": {
"type": "video",
"duration": "8s",
"resolution": "720p",
"aspect_ratio": "16:9",
"delivery": "uri"
}
}
curl
curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "gemini-omni-1.2-flash",
"input": [
{
"type": "text",
"text": "人物在第二张图的场景中行走。"
},
{
"type": "image",
"mime_type": "image/png",
"uri": "https://example.com/subject.png"
},
{
"type": "image",
"mime_type": "image/png",
"uri": "https://example.com/end.png"
}
],
"response_format": {
"type": "video",
"duration": "8s",
"resolution": "720p",
"aspect_ratio": "16:9",
"delivery": "uri"
}
}'
python
import json
import os
import requests
url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
if not os.environ.get(name, "").strip():
raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"gemini-omni-1.2-flash\",\"input\":[{\"type\":\"text\",\"text\":\"人物在第二张图的场景中行走。\"},{\"type\":\"image\",\"mime_type\":\"image/png\",\"uri\":\"https://example.com/subject.png\"},{\"type\":\"image\",\"mime_type\":\"image/png\",\"uri\":\"https://example.com/end.png\"}],\"response_format\":{\"type\":\"video\",\"duration\":\"8s\",\"resolution\":\"720p\",\"aspect_ratio\":\"16:9\",\"delivery\":\"uri\"}}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))
javascript
// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
"model": "gemini-omni-1.2-flash",
"input": [
{
"type": "text",
"text": "人物在第二张图的场景中行走。"
},
{
"type": "image",
"mime_type": "image/png",
"uri": "https://example.com/subject.png"
},
{
"type": "image",
"mime_type": "image/png",
"uri": "https://example.com/end.png"
}
],
"response_format": {
"type": "video",
"duration": "8s",
"resolution": "720p",
"aspect_ratio": "16:9",
"delivery": "uri"
}
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));
Base64 视频参考
适用型号:gemini-omni-1.1-flash, gemini-omni-1.2-flash
POST /v1/videos
先将 MP4 转为不带前缀的 Base64,替换 data 占位符;不支持公网视频 URL。2026-11-15 业务站 1.1 小样本仍在生成阶段 HTTP 400,较大输入保存任务失败;1.2 未实测,当前不承诺参考视频可用。
{
"model": "gemini-omni-1.2-flash",
"input": [
{
"type": "text",
"text": "参考片段中的动作,创作新的花园场景。"
},
{
"type": "video",
"mime_type": "video/mp4",
"data": "REPLACE_WITH_RAW_BASE64_MP4"
}
],
"seconds": "8",
"size": "1280x720"
}
已有任务编辑(条件场景)
适用型号:gemini-omni-1.1-flash, gemini-omni-1.2-flash
POST /v1/videos
需成功且可接续的本站任务;2026-11-15 业务站 1.1 Flash 使用正确字段及新生成源任务仍在生成阶段 HTTP 400。1.2 未实测,当前不承诺编辑可用。
{
"model": "gemini-omni-1.2-flash",
"prompt": "保留人物动作,把天空改为夕阳。",
"previous_interaction_id": "task_REPLACE_WITH_SUCCESSFUL_VIDEO",
"seconds": "8",
"size": "1280x720",
"generation_config": {
"video_config": {
"task": "edit"
}
}
}
已有任务延展(条件场景)
适用型号:gemini-omni-1.1-flash, gemini-omni-1.2-flash
POST /v1/videos
续作最多 10 秒;任务权限和服务接续条件必须满足,出片仍待验证。
{
"model": "gemini-omni-1.2-flash",
"prompt": "继续上一段镜头,人物走向远处。",
"previous_interaction_id": "task_REPLACE_WITH_SUCCESSFUL_VIDEO",
"seconds": "8",
"generation_config": {
"video_config": {
"task": "extend"
}
}
}
任务结果与下载
保存提交返回的 id 或 task_id。统一视频查询使用 GET /v1/videos/{task_id},等待 queued / in_progress 到 completed 或 failed;完成后读取 video_url(部分响应同时在 metadata.url 提供)。本站相对路径需与调用域名拼接,/content 入口使用本站 Key;外部下载 URL 不携带本站 Key。结果可能过期,请及时下载。网络超时保留任务 ID 继续 GET,不自动重试创建 POST。
统一视频完整 Python / JavaScript 轮询下载示例
常见问题定位
| 现象 | 检查方式 |
|---|---|
| Error validating image / 图片 URI 错误 | 视频或任务 ID 是否误填到了图片字段;检查媒体 URL 是否返回真实素材 |
| unsupported content type / 字段不支持 | 检查系列、版本和 content/contents/input 的准确类型;不要把音频 URL 填入 voice_id |
| 400 参数冲突 | 检查 prompt 与 input、首尾帧与多参考、秒数与 response_format 的互斥项 |
| HTTP 成功但任务 failed | 记录本站任务 ID、时间、模型、域名和已脱敏参数;按任务错误定位,不能依据提交 200 宣称成功 |
| 404 或不可访问任务 | 确认域名、Key 权限、本站任务类型;不要使用其他站点或官方任务 ID |
| 本地文件无法访问 | 使用系列明确支持的上传方式,或提供可读取的 HTTPS 媒体 URL |
资料与适用范围
适用场景
- 选择视频模型和素材协议
- 排查参数与任务失败
API 协议
/v1/videos
常见问题
拿到 task_id 就代表生成成功吗?
不代表。保存本站任务 ID,查询到成功终态并确认结果可读取后才算完成;failed 要查看错误,不要自动重建任务。
本地图片、视频和 WAV 能直接填写路径吗?
不能。URL 字段需要服务可读取的媒体地址;localhost、电脑路径及需要浏览器登录的链接不可用。Kling 本地 PCM WAV 的 multipart 音色上传需本站先启用该接口(2026-11-15 两站实测均为 404);其他素材按该系列上传或素材流程处理。
能把不同模型的参数和任务 ID 互换吗?
不能假定兼容。核对精确型号、入口、大小写、媒体角色及互斥字段。编辑、草稿和音色都要求对应类型、本人可访问的成功任务;官方能力也不等于本站已验收。
关联指南
官方来源
- Gemini Omni 官方
兔子API