# 香蕉 2.1 {#香蕉-21--常用接口与请求格式 .rd-guide-title} 使用 `gemini-nano-banana-2.1` 生成图片，或上传图片、PDF、视频作为参考。 ## 1 快速开始 {#quickstart} 使用 **139 分组**的 API Key。示例生成一张 **1K** 图片，保存并打开；按分组价格计费。 选下面一种方式运行即可，切换示例并重新发送会产生新的调用。 ### 1.1 Python 3：完整流程 {#quick-python} 适用于 Windows、macOS 和 Linux。只使用 Python 标准库，无需安装 SDK。 将下面的代码保存为 `banana-21-quickstart.py`，在终端运行 `python3 banana-21-quickstart.py`（Windows 可用 `py -3 banana-21-quickstart.py`），按提示输入 API Key。程序会打印文件路径，并尝试用浏览器打开本地结果。 ``` python import base64 import getpass import json from pathlib import Path from urllib.error import HTTPError from urllib.request import Request, urlopen import uuid import webbrowser URL = 'https://yyds.seqnode.com/v1beta/models/gemini-nano-banana-2.1:generateContent' PAYLOAD = { "contents": [ { "role": "user", "parts": [ { "text": "一只戴蓝色围巾的白色小狐狸，浅灰背景，柔和光线，无文字。" } ] } ], "generationConfig": { "responseModalities": [ "IMAGE" ], "imageConfig": { "aspectRatio": "1:1", "imageSize": "1K" } } } def main(): api_key = getpass.getpass("输入 API Key：").strip() if not api_key: raise ValueError("请输入有效的 API Key。") headers = {"x-goog-api-key": api_key} headers["Content-Type"] = "application/json; charset=utf-8" headers["User-Agent"] = "YM2API-Quickstart/1.0" request = Request(URL, data=json.dumps(PAYLOAD, ensure_ascii=False).encode("utf-8"), headers=headers) with urlopen(request, timeout=300) as response: result = json.load(response) encoded = next((part["inlineData"]["data"] for candidate in result.get("candidates", []) for part in candidate.get("content", {}).get("parts", []) if not part.get("thought") and part.get("inlineData", {}).get("data")), None) if not encoded: raise ValueError("响应没有最终图片。请检查响应和使用记录，再决定是否重试。") data = base64.b64decode(encoded, validate=True) if data.startswith(b"\x89PNG\r\n\x1a\n"): extension = ".png" elif data.startswith(b"\xff\xd8\xff"): extension = ".jpg" elif len(data) >= 12 and data[:4] == b"RIFF" and data[8:12] == b"WEBP": extension = ".webp" else: raise ValueError("返回数据不是可识别的 PNG、JPEG 或 WebP。") path = Path.cwd() / ("banana-21-" + uuid.uuid4().hex + extension) with path.open("xb") as output: output.write(data) print(f"图片已保存：{path}") if not webbrowser.open(path.as_uri()): print("请到以上路径手动打开图片。") if __name__ == "__main__": try: main() except HTTPError as error: print(f"HTTP {error.code}：{error.read(2000).decode('utf-8', errors='replace')}") raise SystemExit(1) except Exception as error: print(f"运行失败：{error}") raise SystemExit(1) ``` [下载 Python 示例](banana-21-quickstart.py)。如未自动打开结果，按输出路径手动打开。 ### 1.2 PowerShell 7：完整流程 {#quick-powershell} 适合已有 PowerShell 7 的 Windows 用户。复制整段代码到终端，只按提示输入 API Key。 ``` powershell $apiKey = Read-Host "输入 API Key" -MaskInput if ([string]::IsNullOrWhiteSpace($apiKey)) { throw "请输入有效的 API Key。" } $model = "gemini-nano-banana-2.1" $payload = @{ contents = @(@{ role = "user" parts = @(@{ text = "一只戴蓝色围巾的白色小狐狸，浅灰背景，柔和光线，无文字。" }) }) generationConfig = @{ responseModalities = @("IMAGE") imageConfig = @{ aspectRatio = "1:1"; imageSize = "1K" } } } $request = @{ Uri = "https://yyds.seqnode.com/v1beta/models/${model}:generateContent" Method = "Post" Headers = @{ "x-goog-api-key" = $apiKey } ContentType = "application/json; charset=utf-8" Body = [Text.Encoding]::UTF8.GetBytes(($payload | ConvertTo-Json -Depth 12)) TimeoutSec = 300 ErrorAction = "Stop" } $result = Invoke-RestMethod @request $image = $result.candidates.content.parts | Where-Object { $_.inlineData.data -and -not $_.thought } | Select-Object -First 1 if (-not $image) { $detail = $result | ConvertTo-Json -Depth 12 throw "响应中没有图片。检查以下响应中的 finishReason 或 promptFeedback：`n$detail" } $extension = @{ "image/png" = ".png"; "image/jpeg" = ".jpg"; "image/webp" = ".webp" }[$image.inlineData.mimeType] if (-not $extension) { throw "未识别的图片格式：$($image.inlineData.mimeType)" } $bytes = [Convert]::FromBase64String($image.inlineData.data) if ($bytes.Length -eq 0) { throw "图片数据为空。请保留响应排查。" } $file = Join-Path $PWD ("banana-21-" + [guid]::NewGuid().ToString("N") + $extension) $stream = [IO.File]::Open($file, [IO.FileMode]::CreateNew) try { $stream.Write($bytes, 0, $bytes.Length) } finally { $stream.Dispose() } Write-Host "图片已保存：$file" Invoke-Item -LiteralPath $file -ErrorAction Continue ``` [下载 PowerShell 示例](banana-21-quickstart.ps1)。 ### 1.3 cURL / JSON：检查原始请求 {#quick-http} JSON 是请求体，需要由 cURL、Postman 或 Apifox 发送。先将下面内容保存为 UTF-8 的 `banana-21-request.json`，也可[下载请求 JSON](banana-21-request.json)。 ``` json { "contents": [ { "role": "user", "parts": [ { "text": "一只戴蓝色围巾的白色小狐狸，浅灰背景，柔和光线，无文字。" } ] } ], "generationConfig": { "responseModalities": [ "IMAGE" ], "imageConfig": { "aspectRatio": "1:1", "imageSize": "1K" } } } ``` 在该文件所在目录，用 Bash（Linux、macOS 或 Git Bash）运行下面的命令，只输入 API Key。响应保存到 `response.json`，已有同名文件会被覆盖；终端显示 HTTP 状态码。 ``` bash read -rsp 'API Key: ' API_KEY; printf '\n' curl --silent --show-error --fail-with-body --max-time 300 "https://yyds.seqnode.com/v1beta/models/gemini-nano-banana-2.1:generateContent" \ -H "x-goog-api-key: $API_KEY" \ -H 'Content-Type: application/json' \ --data-binary '@banana-21-request.json' \ --output response.json --write-out 'HTTP %{http_code}\n' unset API_KEY ``` Postman / Apifox：新建 **POST** 请求，URL 填 `https://yyds.seqnode.com/v1beta/models/gemini-nano-banana-2.1:generateContent`，Body 选择 **raw → JSON** 并粘贴上面的 JSON；请求头设置 `Content-Type: application/json` 和 `x-goog-api-key: YOUR_API_KEY`，将 `YOUR_API_KEY` 替换为自己的 Key。 HTTP 200 后，还需确认响应包含图片数据。cURL 保存的是 JSON；Python 和 PowerShell 示例会自动解码并保存图片。 ## 2 接入信息与场景选择 {#1-推荐接口} **请求地址：** `POST https://yyds.seqnode.com/v1beta/models/gemini-nano-banana-2.1:generateContent`。 **鉴权：** `x-goog-api-key: YOUR_API_KEY`。JSON 请求使用 `Content-Type: application/json`；上传表单时让客户端自动设置请求头。 本页快速开始已经包含完整地址。客户端自动拼接路径时，核对最终 URL，避免重复添加 `/v1` 或 `/v1beta`。分组由 API Key 决定，不在请求体中填写 `group_id`。 **文生图、图生图、PDF 和视频参考，统一推荐本站已验证的 Gemini 原生 `generateContent` 接口。** 默认模型为 `gemini-nano-banana-2.1`，请求体为 JSON，图片以 Base64 返回。 ``` http POST https://yyds.seqnode.com/v1beta/models/gemini-nano-banana-2.1:generateContent x-goog-api-key: YOUR_API_KEY Content-Type: application/json ``` 用途 推荐方式 ------------------------- ------------------------------------------------------------------------------------- 文生图 `parts[].text` 图片 / PDF / 视频参考 `parts[].inlineData`，本地文件转 Base64 已有公开 PDF / MP4 直链 `parts[].fileData`，填写 MIME 和 HTTPS URL 获取当前 Key 的模型 `GET /v1beta/models`，请求头 `x-goog-api-key` OpenAI 客户端获取模型 `GET /v1/models`，请求头 `Authorization: Bearer YOUR_API_KEY`；这个入口用于模型发现 Gemini 客户端 Base URL 通常填 `https://yyds.seqnode.com`；若客户端要求完整 API 前缀，填 `https://yyds.seqnode.com/v1beta`，避免重复添加 `/v1beta`。生图按本页协议，不混入 `response_format` 等 OpenAI Images 字段。本站 Files 上传流程尚未接通，优先使用上述两种附件方式。 ### 2.1 OpenAI Images 兼容格式 {#openai-images} 以上接口使用 139 分组 API Key，请求头为 Authorization: Bearer YOUR_API_KEY，模型填 gemini-nano-banana-2.1。2026-10-15 已完成公网实际生图验证。 | 用途 | POST 路径 | 请求格式 | |---|---|---| | 文生图 | /v1/images/generations | JSON | | 图生图 | /v1/images/edits | JSON：images[].image_url 支持 data URL 或公开 HTTPS 图片直链 | | 上传图片编辑 | /v1/images/edits | multipart/form-data：image 或 image[] 文件字段 | 文生图请求示例： ```json { "model": "gemini-nano-banana-2.1", "prompt": "一只蓝色陶瓷杯，白色桌面，柔和自然光。", "size": "1024x1024", "n": 1, "response_format": "url" } ``` 发送到 /v1/images/edits 的 JSON 示例： ```json { "model": "gemini-nano-banana-2.1", "prompt": "只把杯子改为红色，保持其余内容。", "size": "1024x1024", "n": 1, "response_format": "url", "images": [ { "image_url": "data:image/jpeg;base64,图片Base64" } ] } ``` response_format 支持 url 和 b64_json，默认 b64_json。size 可填 1K、2K、4K 或宽x高；宽高用于选择比例和分辨率档位，实际像素以返回图片为准。每次 n=1、stream=false。图片参考接受 PNG、JPEG、WebP，最多 14 张、合计 20 MiB；本轮实测为单张 JPEG。mask 局部蒙版暂未接通。 思考签名、多轮对话，以及 PDF、视频等非图片附件，请继续使用下方 Gemini 原生接口，并在多轮请求中回传完整模型内容和 thoughtSignature。Images 接口每次需提交提示词和参考图片。 url 返回本站域名的随机图片地址；本次响应、下载头和图片数据中未发现上游域名或密钥。持有链接即可下载，不等于私有鉴权存储。 ### 2.2 Chat Completions 兼容格式 {#openai-chat} POST /v1/chat/completions，使用同一把 139 分组 Key 和 Bearer 鉴权。支持普通 JSON 响应和 stream=true 的 SSE 响应；图片位于 message.content 的 Markdown 图片链接中，流式客户端按顺序拼接 delta.content。generationConfig 是本站兼容扩展，使用 SDK 时可通过 extra_body 传入。 ```json { "model": "gemini-nano-banana-2.1", "messages": [ { "role": "user", "content": "画一只蓝色陶瓷杯，白色桌面。" } ], "generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" } }, "stream": false } ``` 思考签名的完整回传与多轮修改仍推荐 Gemini 原生 contents 协议。 ## 3 文生图 {#2-文生图} 仅使用提示词生成图片，发送 JSON 到接入信息中的 `generateContent` 地址。模型名位于 URL。 ---------------------------------------------------------------------------------------------------------------------------------- 参数 填写要求 用途 / 示例 -------------------------------------------- -------------------------- ---------------------------------------------------------- `contents[].role` 本页示例填写 `user` 用户输入 `contents[].parts[].text` 填写提示词 说明主体、场景或编辑目标 `generationConfig.responseModalities` 示例显式填写 `["IMAGE"]` 需要文字时使用 `["TEXT", "IMAGE"]`；仍需检查实际返回内容 `generationConfig.imageConfig.imageSize` 可选，示例显式填写 档位名称中的 `K` 大写；支持范围按本页说明 `generationConfig.imageConfig.aspectRatio` 可选，示例显式填写 例如 `1:1`；实际像素与比例、模型有关 ---------------------------------------------------------------------------------------------------------------------------------- 将下列内容保存为 UTF-8 的 `request.json`，发送到上述 POST 地址： ``` json { "contents": [{ "role": "user", "parts": [{"text": "生成一张白色背景的黄色陶瓷杯产品照片，柔和自然光。"}] }], "generationConfig": { "responseModalities": ["TEXT", "IMAGE"], "imageConfig": {"imageSize": "1K", "aspectRatio": "3:2"} } } ``` **响应：** 图片在 `candidates[].content.parts[]` 中，[读取并保存最终图片](#5-返回图片)。 ## 4 图生图、PDF 与视频参考 {#pdf-video-input} **接口：** 与文生图相同，使用 JSON。参考文件只影响输入内容，输出仍是图片；每个附件占一个 part。 -------------------------------------------------------------------------------------------------------- 输入参数 何时填写 说明 ----------------------- ----------------------------- -------------------------------------------------- `parts[].text` 所有场景 说明参考文件用途及需要生成的图片 `parts[].inlineData` 本地文件 填写 `mimeType` 和纯 Base64 `data` `parts[].fileData` 已验证的公开 PDF / MP4 直链 填写 `mimeType` 和 `fileUri`；链接应直接返回文件 -------------------------------------------------------------------------------------------------------- 三种输入采用相同结构，只需替换 `mimeType`、文件 Base64 和提示词。以下是**图片参考**的完整请求体： ``` json { "contents": [{ "role": "user", "parts": [ {"inlineData": {"mimeType": "image/png", "data": "FILE_BASE64"}}, {"text": "保留参考图片中的主体、颜色和形状，将背景换成浅蓝色。"} ] }], "generationConfig": { "responseModalities": ["TEXT", "IMAGE"], "imageConfig": {"imageSize": "1K", "aspectRatio": "3:2"} } } ``` 输入 将 `mimeType` 替换为 提示词示例 ---------- ---------------------- ---------------------------------------------------- JPG 图片 `image/jpeg` 保留人物或产品，调整背景 PDF `application/pdf` 读取各页内容，生成一张信息图 MP4 视频 `video/mp4` 按视频场景出现顺序生成参考图，保留主体、颜色和编号 **请求 4K：** 将 `imageSize` 改成 `"4K"`。视频是参考输入，结果仍是图片。本站视频参考 4K 已实测返回 **5056 × 3392 JPEG**，这是本次 3:2 样本的尺寸，不是所有请求的固定尺寸。 **多附件：** 在同一个 `parts` 数组中增加多个 `inlineData` 项，每个文件一项；可混合图片、PDF 和视频。最大数量和复杂素材的还原效果以实际模型表现为准。 **公开文件 URL：** 将上例的 `inlineData` 那一项替换为下面结构。本站已验证公开 PDF / MP4 直链；链接需直接返回文件，不是登录页或网页预览。 ``` json { "fileData": { "mimeType": "application/pdf", "fileUri": "https://yyds.seqnode.com/api-docs/parameter-test-fixtures/mime-20261007/fixture.pdf" } } ``` **响应：** 与文生图一致；[读取最终图片](#5-返回图片)，不要把视频参考输入当作视频输出。 ## 5 读取响应、保存与查看图片 {#5-返回图片} ``` json { "candidates": [{ "content": { "role": "model", "parts": [{ "inlineData": {"mimeType": "image/jpeg", "data": "OUTPUT_IMAGE_BASE64"} }] }, "finishReason": "STOP" }] } ``` 遍历 `candidates[].content.parts[]`，跳过 `thought: true` 项；找到最终图片 `inlineData.data`，Base64 解码后按返回的 `mimeType` 保存，如 `image/jpeg` → `.jpg`、`image/png` → `.png`。文字与图片可能同时返回，不要默认第一项就是图片。 本接口返回图片 Base64；业务需要 URL 时，解码后上传到自己的对象存储或文件服务，再返回可访问地址。 ### 5.1 流式输出、思考签名与多轮改图 {#signed-stream} 使用 139 分组的本站 API Key。Gemini 原生流式端点为 POST /v1beta/models/gemini-nano-banana-2.1:streamGenerateContent?alt=sse，响应类型为 text/event-stream；请求体使用 contents，不需要额外添加 stream=true。 下面的 cURL 适用于 Bash / macOS / Linux。YOUR_API_KEY 替换为本站 Key；-N 关闭客户端输出缓冲。Windows 可直接使用后面的 Python 示例。 ```bash curl -N "https://yyds.seqnode.com/v1beta/models/gemini-nano-banana-2.1:streamGenerateContent?alt=sse" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: text/event-stream" \ --data-binary '{ "contents": [ { "role": "user", "parts": [ { "text": "画一只蓝色陶瓷杯，桌上放一个橙子，柔和自然光。" } ] } ], "generationConfig": { "responseModalities": [ "IMAGE" ], "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" } } }' ``` SSE 响应结构示意（占位符不是可回传的真实值）： ```text data: {"candidates": [{"content": {"role": "model", "parts": [{"inlineData": {"mimeType": "image/jpeg", "data": "<完整图片Base64>"}, "thoughtSignature": "<原样保存的签名>"}]}, "finishReason": "STOP"}]} ``` 以空行分隔 SSE 事件，解析 data: 后的 JSON。读取 candidates[0].content.parts 中的 inlineData 图片和 thoughtSignature。忽略以冒号开头的心跳注释；不要把每个网络数据块当成一条完整 JSON。 2026-10-15 直连当前上游渠道，对两个模型各完成三轮流式改图：蓝杯子 → 红杯子 → 加勺子，六次均成功并返回签名。本次每个响应只在生成完成后发送一个完整 data 事件，没有逐段图片或思考文本输出；SSE 协议不保证更早出图，其他请求的事件数量可能不同。思考签名是需要回传的上下文数据，并不等于可读的思考文本。 本站端点的补充验证本次首轮收到 HTTP 429，未完成本站多轮验证；以下代码是接入示例，上述六次成功记录来自上游直连测试。遇到 429 请检查分组、额度和并发状态，不要持续自动重发。 下一轮仍请求相同流式端点。按 user → model → user 顺序组织历史，保留上一轮全部 model parts 的原始顺序与字段，包括图片及 thoughtSignature；不要截断、解码、改写签名，也不要将带签名的 part 与其他 part 合并。以下 JSON 仅展示单图片响应的结构；实际代码应回传完整模型内容。 ```json { "contents": [ { "role": "user", "parts": [ { "text": "画一只蓝色陶瓷杯，桌上放一个橙子，柔和自然光。" } ] }, { "role": "model", "parts": [ { "inlineData": { "mimeType": "image/jpeg", "data": "<上一轮完整图片Base64>" }, "thoughtSignature": "<上一轮原始签名>" } ] }, { "role": "user", "parts": [ { "text": "把上一张图的杯子改成红色，保持橙子、桌面和构图不变。" } ] } ], "generationConfig": { "responseModalities": [ "IMAGE" ], "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" } } } ``` 签名可能很大，本次样本约 129 万～191 万字符；不要按普通短 token 限长。多轮历史中的图片和签名会增加请求体大小。 [下载 Python 3 流式多轮示例](banana-signed-stream.py) ```bash python3 banana-signed-stream.py --model gemini-nano-banana-2.1 ``` Windows 使用 py -3 替代 python3。程序提示输入隐藏的本站 Key，也可读取 YM2API_KEY 环境变量；默认连续调用三次、每次生成一张 1K 图片，按分组价格计费。只测试首轮可加 --turns 1。程序仅依赖标准库，图片保存到新建的 banana-stream-* 目录，签名只保存在运行内存中，不打印或写入文件。 示例支持多个 SSE 事件，按顺序保留所有 parts；HTTP 错误、SSE error、非 STOP 结束、缺少最终图片或后续轮次所需签名时停止。不会自动重试，避免重复生成。 URL 返回与签名多轮的区别：POST /v1/images/generations 设置 response_format="url" 后，返回 created 和 data[].url；当前实测返回本站随机图片地址，不含 thoughtSignature。图片 URL 可作为图片编辑的参考图，但仅保留该 URL 不会保留原生签名对话历史。Chat Completions 的 Markdown 图片链接也不应当作完整 Gemini model content 回传。 ```json { "created": 1792070510, "data": [ { "url": "https://yyds.seqnode.com/随机标识.jpg" } ] } ``` [Google 官方：图片生成与思考签名](https://ai.google.dev/gemini-api/docs/generate-content/image-generation#thought-signatures) ## 6 格式、尺寸与可选参数 {#mime-types} 文件 正确 `mimeType` 使用建议 --------------------- --------------------------------- ---------------------------------------------------------- PNG `image/png` 图标、文字、截图或带透明通道的源文件 JPG / JPEG `image/jpeg` 普通照片，体积通常较小 WebP `image/webp` 已有 WebP 可直接提交 PDF `application/pdf` 文档、报告、演示材料 MP4 `video/mp4` 视频优先使用已验证的 H.264 MP4 TXT / Markdown 内容 放入 `parts[].text` 简单文字无需转 Base64 CSV / JSON 文件 `text/csv` / `application/json` UTF-8 附件已实测，按"图生图、PDF 与视频参考"一节内联提交 MOV、WebM、其他 MIME 的详细状态见[完整格式表](group139-banana21-api-details.html#mime-types)。DOCX 目前尚未验证成功，文档输入优先用 PDF。 - 字段准确拼写为 **`mimeType`**，大小写保持一致；JPG 使用 `image/jpeg`。 - `data` 放完整文件的 Base64，**不带** `data:...;base64,` 前缀。修改 MIME 或文件后缀不会转换文件格式。 - 整个 HTTP 请求的 `Content-Type` 始终是 `application/json`，与附件 MIME 分开。 - `imageSize` 使用 `1K` / `2K` / `4K`。建议先以 `1K` 调通，再按交付需求提高；当前视频样本验证了 1K 与 4K。 - `aspectRatio` 表示宽高比，本页采用已验证的 `3:2`。实际像素请以返回文件为准。 ### 6.1 可选：Thinking 2.1 官方支持 `minimal`、`medium`（默认）、`high` 三档。常规接入可先省略 Thinking 配置；`minimal` 偏向较低延迟，`high` 增加思考量，效果仍需结合具体任务评估。以下按官方原生 REST 示例，将配置放在 `generationConfig` 中： ``` json { "generationConfig": { "responseModalities": ["TEXT", "IMAGE"], "imageConfig": {"imageSize": "4K", "aspectRatio": "3:2"}, "thinkingConfig": {"thinkingLevel": "High", "includeThoughts": false} } } ``` 这是替换前述 `generationConfig` 的片段，发送时保留 `contents`。`includeThoughts: false` 控制是否返回思考内容，并不关闭模型思考。**Thinking 属于渠道相关能力，当前并非所有上游都已验证可控。** 2026-10-07 对照测试中，一路上游的 Medium / High 返回思考项与 thinking tokens，隐藏输出生效，非法档位返回 400；当前默认优先路由只返回图片，未报告思考项或 thinking tokens，非法档位也返回 200。后者的参数疑似被忽略或兼容层未完整实现，尚无证据认定手动档位生效，也不据此断定模型内部完全没有思考。常规生图先使用默认配置；依赖 Thinking 控制的应用需确认所用渠道。[官方模型说明](https://ai.google.dev/gemini-api/docs/models/gemini-nano-banana-2.1)、[原生接口 Thinking 配置](https://ai.google.dev/gemini-api/docs/generate-content/image-generation#controlling_thinking_levels)。 ## 7 附件调用工具与批量调试 {#6-直接调用示例} 下载 [Python 3 示例](gemini-image.py?v=20261007-mime)，仅使用标准库，自动处理 Base64 并保存图片。先设置环境变量： ``` powershell # Windows PowerShell $env:BASE_URL = "https://yyds.seqnode.com" $env:API_KEY = "YOUR_API_KEY" ``` ``` bash # macOS / Linux Bash export BASE_URL="https://yyds.seqnode.com" export API_KEY="YOUR_API_KEY" ``` 常用命令（两种环境均适用）： ``` bash python gemini-image.py --list-models python gemini-image.py --prompt "生成一张陶瓷杯产品照片。" --output text-result python gemini-image.py --image reference.png --prompt "保留主体，换成浅蓝色背景。" --output image-result python gemini-image.py --image first.png --image second.jpg --prompt "把两张参考图融合为一张海报。" --output multi-result python gemini-image.py --pdf reference.pdf --prompt "根据文档生成信息图。" --output pdf-result python gemini-image.py --video reference.mp4 --size 4K --ratio 3:2 --prompt "按视频场景顺序生成参考图，保留编号、颜色和形状。" --output video-4k ``` 也可直接发送 `request.json`。以下单行命令在 PowerShell / Bash 均可用，Windows 如有同名别名则使用 `curl.exe`： ``` bash curl --fail-with-body --max-time 180 "https://yyds.seqnode.com/v1beta/models/gemini-nano-banana-2.1:generateContent" -H "x-goog-api-key: YOUR_API_KEY" -H "Content-Type: application/json" --data-binary "@request.json" -o response.json ``` ## 8 常见问题与验证记录 {#video-reference-proof} 现象 建议检查 ------------------------ --------------------------------------------------- 401 / 403 Key、绑定分组与额度/权限 400 JSON、MIME、Base64、文件是否有效 413 减小附件；Base64 会增加约三分之一体积 429 检查额度、并发及上游状态，避免循环重发 502 / 503 / 504 / 超时 保存请求 ID，先核对用量与上游状态，再决定是否重试 200 但结果不对 检查最终图片和参考内容，不能只看状态码 已完成视频 A/B 两轮、倒序、首帧、无附件及损坏文件共 8 次对照，并逐张核对输出。另有 PDF、长视频、混合附件、URL 和 MIME 测试。详见[测试方法、素材与结果](group139-banana21-api-details.html#video-reference-proof)，以及[本次 4K 视频参考原图](parameter-test-fixtures/video-proof-20261007/a4k-image-1.jpg)。这些是具体样本验证，不代表所有视频、文件大小或模型都已完整验收。 [完整说明与测试记录](group139-banana21-api-details.html) · [Google 原生视频输入文档](https://ai.google.dev/gemini-api/docs/generate-content/video-understanding) 旧版章节索引 [1. 获取当前 Key 可用模型 ·](group139-banana21-api-details.html#1-%E8%8E%B7%E5%8F%96%E5%BD%93%E5%89%8D-key-%E5%8F%AF%E7%94%A8%E6%A8%A1%E5%9E%8B){#1-获取当前-key-可用模型} [3. 图生图与多张参考图 ·](group139-banana21-api-details.html#3-%E5%9B%BE%E7%94%9F%E5%9B%BE%E4%B8%8E%E5%A4%9A%E5%BC%A0%E5%8F%82%E8%80%83%E5%9B%BE){#3-图生图与多张参考图} [4. 可运行的 Python 示例 ·](group139-banana21-api-details.html#4-%E5%8F%AF%E8%BF%90%E8%A1%8C%E7%9A%84-python-%E7%A4%BA%E4%BE%8B){#4-可运行的-python-示例} [5. 参数与图片响应 ·](group139-banana21-api-details.html#5-%E5%8F%82%E6%95%B0%E4%B8%8E%E5%9B%BE%E7%89%87%E5%93%8D%E5%BA%94){#5-参数与图片响应} [6.1 PDF 参考生图 ·](group139-banana21-api-details.html#61-pdf-%E5%8F%82%E8%80%83%E7%94%9F%E5%9B%BE){#61-pdf-参考生图} [6.2 视频参考生图 ·](group139-banana21-api-details.html#62-%E8%A7%86%E9%A2%91%E5%8F%82%E8%80%83%E7%94%9F%E5%9B%BE){#62-视频参考生图} [6.3 PowerShell 直接构建请求 ·](group139-banana21-api-details.html#63-powershell-%E7%9B%B4%E6%8E%A5%E6%9E%84%E5%BB%BA%E8%AF%B7%E6%B1%82){#63-powershell-直接构建请求} [6.4 返回值与本次验收 ·](group139-banana21-api-details.html#64-%E8%BF%94%E5%9B%9E%E5%80%BC%E4%B8%8E%E6%9C%AC%E6%AC%A1%E9%AA%8C%E6%94%B6){#64-返回值与本次验收} [6.5 大小、格式与兼容边界 ·](group139-banana21-api-details.html#65-%E5%A4%A7%E5%B0%8F%E6%A0%BC%E5%BC%8F%E4%B8%8E%E5%85%BC%E5%AE%B9%E8%BE%B9%E7%95%8C){#65-大小格式与兼容边界} [6.7 公开文件 URL 与 Files 上传 ·](group139-banana21-api-details.html#67-%E5%85%AC%E5%BC%80%E6%96%87%E4%BB%B6-url-%E4%B8%8E-files-%E4%B8%8A%E4%BC%A0){#67-公开文件-url-与-files-上传} [6.8 大文件、多附件及其他模型实测 ·](group139-banana21-api-details.html#68-%E5%A4%A7%E6%96%87%E4%BB%B6%E5%A4%9A%E9%99%84%E4%BB%B6%E5%8F%8A%E5%85%B6%E4%BB%96%E6%A8%A1%E5%9E%8B%E5%AE%9E%E6%B5%8B){#68-大文件多附件及其他模型实测} [7. 错误处理与验收 ·](group139-banana21-api-details.html#7-%E9%94%99%E8%AF%AF%E5%A4%84%E7%90%86%E4%B8%8E%E9%AA%8C%E6%94%B6){#7-错误处理与验收} [8. Google 官方文档 ·](group139-banana21-api-details.html#8-google-%E5%AE%98%E6%96%B9%E6%96%87%E6%A1%A3){#8-google-官方文档}