API 协议

Gemini Omni:参数、场景与调用指南

预览指南

粘贴给 AI,帮助理解文档并完成接入。 仅包含文档与示例,不包含真实密钥。

预览指南

Gemini Omni:参数、场景与调用指南

直接答案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。生成含音轨的视频不代表支持独立参考音频输入。
任务 / 素材 IDprevious_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 水印,没有关闭开关。
字段类型用法与限制
Authorizationheader string必填。Bearer <本站 API Key>;JSON 请求使用 Content-Type: application/json。
modelstring必填,gemini-omni-1.1-flash 或 gemini-omni-1.2-flash。
promptstring本站文本快捷方式,与 input 互斥;可配 input_reference。
inputstring / object[]官方文本或结构化多模态输入;本站不接受与 prompt/input_reference 重复。
input[].typestring必填 text/image/video;当前 API 不支持独立音频输入。
input[].textstringtype=text 时必填,用自然语言说明首帧、尾帧、参考、编辑目标;不要使用已弃用的 <FIRST_FRAME> 等控制标签。
input[].mime_typestring图片/视频必填且与内容一致,例如 image/png、image/jpeg、video/mp4。
input[].uristring本站适配器接受并转发图片或视频的公开 HTTP(S) URI;但既有 1.1 视频 URI 实测受理后在上游生成阶段失败,不能据转发成功认定可出片,1.2 未验收。
input[].datastring媒体原始 Base64 字节,不带 data URI 前缀;与 uri 二选一。视频示例使用此字段;这不代表已通过出片验收,已知持久化与生成失败限制见条件示例。
input_referencestring本站单图快捷方式,配 prompt;URL 后缀须可识别为 JPG/PNG/WebP,否则用 input 并显式 mime_type。
secondsinteger / string本站时长快捷方式,默认 10;1.1 为 3–10 秒,1.2 普通生成 3–15 秒;首尾帧及本站已有任务接续仍至多 10 秒。
sizestring本站像素尺寸快捷方式,横竖屏对应 360p/720p/1080p/4k;默认 1280x720。与 response_format 的对应设置不要重复。
response_format.typestring本站固定 video,由适配器补全。
response_format.durationstring例如 3s、8s;与 seconds 二选一,适用相同版本和模式时长限制。
response_format.resolutionstring360p/720p/1080p/4k,默认 720p;不要与 size 重复。
response_format.aspect_ratiostring16:9(默认)或 9:16。
response_format.deliverystring本站固定 uri,使用成功任务的视频 URL;官方可直接返回 Base64,但本站示例不支持切换为内联输出。
response_format.fpsinteger本站兼容项,只接受 24;模型固定帧率,不是官方 response_format 字段,转发前移除。
generation_config.video_config.taskstring可选 text_to_video/image_to_video/reference_to_video/edit/extend;优先用自然语言,只有模型无法选对模式时再指定,指定后会收紧素材约束。
generation_config.temperature / generation_config.top_pnumber官方 Omni 明确不支持,即使本站对象接受也不应发送。
generation_config.seed / generation_config.max_output_tokensinteger本站允许转发的通用 Interactions 配置,但当前 Omni 指南未确认视频效果或取值范围;不作为可用的视频控制,已从普通示例移除。
previous_interaction_idstring本站必须使用本人可访问、已成功且同渠道/兼容凭据的 task_ ID;会映射为官方 interaction ID。每次接续 ≤10 秒,不是上传视频 URL。
background / stream / storeofficial 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

资料与适用范围

Gemini Omni

适用场景

  • 选择视频模型和素材协议
  • 排查参数与任务失败

API 协议

  • /v1/videos

常见问题

拿到 task_id 就代表生成成功吗?

不代表。保存本站任务 ID,查询到成功终态并确认结果可读取后才算完成;failed 要查看错误,不要自动重建任务。

本地图片、视频和 WAV 能直接填写路径吗?

不能。URL 字段需要服务可读取的媒体地址;localhost、电脑路径及需要浏览器登录的链接不可用。Kling 本地 PCM WAV 的 multipart 音色上传需本站先启用该接口(2026-11-15 两站实测均为 404);其他素材按该系列上传或素材流程处理。

能把不同模型的参数和任务 ID 互换吗?

不能假定兼容。核对精确型号、入口、大小写、媒体角色及互斥字段。编辑、草稿和音色都要求对应类型、本人可访问的成功任务;官方能力也不等于本站已验收。

官方来源

  1. Gemini Omni 官方