← 返回 API 文档 · 下载 Markdown

← 返回常用接口与请求格式

← 检测报告

香蕉 2.1 · 详细说明与测试记录

更新：2026-10-07。本站 Host：https://yyds.seqnode.com。使用本站绑定 139 分组 的 API Key；分组由 Key 决定，请求体无需填写 group_id。

本页采用 Google Gemini generateContent 请求与响应结构。Google 最新文档也介绍 Interactions API；本站本页验证的是 generateContent，不要混用 input、response_format 等 Interactions 字段。

1. 获取当前 Key 可用模型

Gemini 客户端的 Base URL 填本站 Host，由客户端追加 /v1beta。如果客户端明确要求完整 API 前缀，填 https://yyds.seqnode.com/v1beta，避免重复拼接版本路径。

# Bash：使用本站 API Key

export BASE_URL="https://yyds.seqnode.com"

export API_KEY="YOUR_API_KEY"

curl --fail-with-body "$BASE_URL/v1beta/models" \
  -H "x-goog-api-key: $API_KEY"

响应结构示例（只展示一项；以实际返回为准）：

{

  "models": [{

    "name": "models/gemini-nano-banana-2.1",

    "supportedGenerationMethods": ["generateContent", "streamGenerateContent"]

  }]

}

通过 models[].name 获取名称。拼接生成地址时取去掉 models/ 的模型 ID。列表只表示当前 Key 可见模型，生成还受额度、账号状态和上游可用性影响。

OpenAI 类客户端的“获取模型”使用以下兼容入口，读取 data[].id：

curl --fail-with-body "$BASE_URL/v1/models" \
  -H "Authorization: Bearer $API_KEY"

这个列表入口适用于模型发现；后续生图按本页 Gemini 协议调用。两种列表可能包含不同别名，建议使用下表完整模型名。

模型列表、别名与可用范围以当前 Key 返回为准。香蕉 2.1 当前配置为 0.05 / 张，实际扣费以当前渠道价格及用户倍率为准；本页不将该价格套用到 Flash / Pro。

2. 文生图

把下面 JSON 保存成 UTF-8 文件 request.json。

{

  "contents": [{

    "role": "user",

    "parts": [{"text": "Create a product photo of a yellow ceramic mug on a wooden desk."}]

  }],

  "generationConfig": {

    "responseModalities": ["TEXT", "IMAGE"],

    "imageConfig": {"aspectRatio": "3:2", "imageSize": "1K"}

  }

}

curl --fail-with-body --max-time 180 \
  "$BASE_URL/v1beta/models/gemini-nano-banana-2.1:generateContent" \
  -H "x-goog-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json -o response.json

Windows PowerShell 对应写法：

$env:BASE_URL = "https://yyds.seqnode.com"

$env:API_KEY = "YOUR_API_KEY"

curl.exe --fail-with-body --max-time 180 `

  "$env:BASE_URL/v1beta/models/gemini-nano-banana-2.1:generateContent" `

  -H "x-goog-api-key: $env:API_KEY" `

  -H "Content-Type: application/json" `

  --data-binary "@request.json" -o response.json

3. 图生图与多张参考图

端点、鉴权和 generationConfig 与文生图一致。在同一个 parts 数组中加入图片，每张参考图各占一个 inlineData 项。

{

  "contents": [{

    "role": "user",

    "parts": [

      {"text": "Combine both reference images into one clean product layout; preserve their colors and shapes."},

      {"inlineData": {"mimeType": "image/png", "data": "FIRST_IMAGE_BASE64"}},

      {"inlineData": {"mimeType": "image/jpeg", "data": "SECOND_IMAGE_BASE64"}}

    ]

  }],

  "generationConfig": {

    "responseModalities": ["TEXT", "IMAGE"],

    "imageConfig": {"aspectRatio": "3:2", "imageSize": "1K"}

  }

}

data 填原始图片的 Base64，不加 data:image/png;base64, 前缀。mimeType 应与真实文件格式一致。这里采用 JSON 请求，参考图数量由 inlineData 项数决定。

需要五张参考图时，按同一结构放入五项；接收上限与素材保留效果受模型和上游约束，本页没有为香蕉 2.1 承诺未经验证的最大参考图数量。

4. 可运行的 Python 示例

下载 gemini-image.py，仅使用 Python 3 标准库。先按前文设置 BASE_URL 和 API_KEY，再运行：

# 获取模型

python gemini-image.py --list-models



# 文生图；输出 result-1.jpg 或 result-1.png 等

python gemini-image.py --output result



# 单图参考

python gemini-image.py --image reference.png --prompt "Keep the subject and change the background to pale blue." --output edit



# 多图参考：每张图片重复一次 --image

python gemini-image.py --image first.png --image second.jpg --prompt "Combine both references into one composition." --output multi

脚本按图片真实格式构建 inlineData，自动保存响应图片，HTTP 错误会显示状态码与错误正文。输出采用独占创建；若文件已存在，请更换 --output。请求超时后先核对用量记录，再决定是否重试，以免重复生成。

5. 参数与图片响应

1K 是分辨率档位，不等于固定 1024×1024。实际像素取决于比例和上游输出；如业务要求精确像素，请解码后检查图片尺寸。

请求体顶层加 "response_format": "b64_json" 时，图片在 candidates[].content.parts[].inlineData.data，格式由 mimeType 标识：

{

  "candidates": [{

    "content": {

      "role": "model",

      "parts": [{"inlineData": {"mimeType": "image/jpeg", "data": "OUTPUT_IMAGE_BASE64"}}]

    },

    "finishReason": "STOP"

  }]

}

遍历所有 parts，不要假设第一项就是图片。139 分组未指定格式时默认返回链接：图片项为 {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://img.yydsbest.com/…"}}，另附 ![image](链接) 文本项，链接 1 小时内有效。示例脚本两种返回都会保存。

6. PDF 与视频输入：完整示例

适用：2 号站、139 分组、gemini-nano-banana-2.1。将 PDF 或视频作为参考输入，输出仍然是图片和文字；这不是视频生成接口。

请求遵循 Google generateContent 的内联附件格式：文件原始字节编码成 Base64，放入 contents[].parts[].inlineData。无需预先调用 Files 上传接口。

6.1 PDF 参考生图

端点和鉴权：

POST https://yyds.seqnode.com/v1beta/models/gemini-nano-banana-2.1:generateContent

x-goog-api-key: YOUR_API_KEY

Content-Type: application/json

请求结构示例；PDF_BASE64 应替换成完整 PDF 的 Base64，不是文件路径或 URL：

{

  "contents": [{

    "role": "user",

    "parts": [

      {"inlineData": {"mimeType": "application/pdf", "data": "PDF_BASE64"}},

      {"text": "读取附件 PDF 的每一页。先按页序列出编号、颜色和形状，再生成一张保留这些信息的参考图。"}

    ]

  }],

  "generationConfig": {

    "responseModalities": ["TEXT", "IMAGE"],

    "imageConfig": {"aspectRatio": "3:2", "imageSize": "1K"}

  }

}

下载更新后的 gemini-image.py，把 PDF 放到当前目录。设置前文的 BASE_URL 和 API_KEY 后，这条命令在 PowerShell、Bash 均可运行：

python gemini-image.py --pdf reference.pdf --prompt "Read every page of the PDF. List the exact labels, colors and shapes in page order, then generate a reference-sheet image preserving them." --size 1K --ratio 3:2 --output pdf-result

脚本自动读取 PDF、编码、请求并保存图片，例如 pdf-result-1.jpg。PDF 在请求中直接传入模型，示例脚本没有先做 OCR 或转成图片。

6.2 视频参考生图

请求端点不变，附件使用 video/mp4：

{

  "contents": [{

    "role": "user",

    "parts": [

      {"inlineData": {"mimeType": "video/mp4", "data": "VIDEO_BASE64"}},

      {"text": "观看完整视频，先按出现顺序列出各场景中的编号、颜色和形状，再生成一张按该顺序排列的参考图。"}

    ]

  }],

  "generationConfig": {

    "responseModalities": ["TEXT", "IMAGE"],

    "imageConfig": {"aspectRatio": "3:2", "imageSize": "1K"}

  }

}

可运行示例：

python gemini-image.py --video reference.mp4 --prompt "Watch the entire video. List the exact labels, colors and shapes in chronological order, then generate a reference-sheet image preserving them." --size 1K --ratio 3:2 --output video-result

脚本发送完整 MP4 文件，示例本身不抽帧。优先从短小的 H.264 MP4 开始接入；MOV（H.264）及 WebM（VP9）也已验证；音轨理解、其他编码和时间戳精度尚未验收。

6.3 PowerShell 直接构建请求

如需用 curl.exe 发送，可用以下脚本生成 UTF-8 JSON。PDF 使用下面的文件名和 MIME；视频将它们分别改为 reference.mp4、video/mp4，并调整提示词。

$env:BASE_URL = "https://yyds.seqnode.com"

$env:API_KEY = "YOUR_API_KEY"

$inputPath = "reference.pdf"

$mime = "application/pdf"

$encoded = [Convert]::ToBase64String([IO.File]::ReadAllBytes((Resolve-Path $inputPath).Path))

$body = @{

  contents = @(@{

    role = "user"

    parts = @(

      @{ inlineData = @{ mimeType = $mime; data = $encoded } },

      @{ text = "读取附件内容，先描述关键信息，再据此生成一张参考图。" }

    )

  })

  generationConfig = @{

    responseModalities = @("TEXT", "IMAGE")

    imageConfig = @{ aspectRatio = "3:2"; imageSize = "1K" }

  }

}

$body | ConvertTo-Json -Depth 12 | Set-Content -Encoding utf8NoBOM request.json

curl.exe --fail-with-body --max-time 180 `

  "$env:BASE_URL/v1beta/models/gemini-nano-banana-2.1:generateContent" `

  -H "x-goog-api-key: $env:API_KEY" `

  -H "Content-Type: application/json" `

  --data-binary "@request.json" -o response.json

上述写法适用于 PowerShell 7。响应文件中的图片需按第 5 节解码；使用 Python 示例时会自动保存。文件内的换行、中文等内容由 Base64 编码处理，不应手工拼进 JSON 字符串。

6.4 返回值与本次验收

文字读取 candidates[].content.parts[].text，最终图片读取 inlineData.data 或下载 fileData.fileUri，并按对应的 mimeType 保存。示例跳过 thought: true 的中间内容。HTTP 200 后还需检查是否有最终图片。

编号只出现在附件里，没有写进测试提示词。核验同时检查正常文字回答中的编号顺序，以及生成图片的编号、颜色和形状，确认附件内容被读取。

6.5 大小、格式与兼容边界

• data 使用完整文件的 Base64，不加 data:...;base64, 前缀。MIME 必须和实际格式一致。
• Python 示例支持 --image、--pdf、--video、--attachment MIME FILE 和 --text-file。检查文件标识、MIME 对应关系、UTF-8 及 JSON 格式；文件内部结构和视频编码仍由上游校验。
• Base64 通常会使数据体积增加约三分之一，还需加上 JSON 开销。本站入口配置的 256 MiB 请求体上限不代表模型、上游或长视频的可用上限。
• 已补测约 15.49 MiB 的 30 页 PDF、180 秒 MP4，以及 PDF + MP4 + JPEG 混合输入。它们均成功返回图片并读出附件编号；这不是最大大小、时长或数量上限。实际复杂素材仍需验证。
• 示例请求超时为 180 秒，不自动重试。超时后先核对请求和用量记录，避免重复生成。
• 当前 GET /v1beta/files 返回 404，POST /upload/v1beta/files 返回网页而非有效上传会话。官方 SDK 的 files.upload() → fileData.fileUri 流程尚未接通；本页支持已实测的 inlineData 和公开 HTTPS 文件 URL 的 fileData（见 6.7）。
• Google 文件链接、YouTube URL、视频裁剪和自定义采样率等其他输入方式，本轮未验证。

协议参考：官方 PDF 输入、官方视频输入、文件输入方式。Google 的限制说明不自动等同于本站当前上游的限制。

原生单模型详情 GET /v1beta/models/{model} 的支持情况也不同：0 号站 2.1 已验证，2 号站该详情仍返回 404。获取可用模型请使用已验证的列表端点。

6.6 MIME 类型与其他文件支持

字段的准确写法是 mimeType，注意大小写；不是 minetype 或 mimetype。本节结果来自 2026-10-07 二号站、139 分组、gemini-nano-banana-2.1。同一扩展名下的不同编码或复杂文件仍可能有差异。

“通过”指请求成功、返回至少一张最终图片，并从正常文字回答中核对出只存在于附件中的编号。基础 PDF / MP4 另已人工核对生成图片；新增类型没有逐张验收所有视觉细节。测试使用 1K、3:2，不代表所有分辨率、参数组合或编码均已通过。

三个 MIME 概念需要分开：HTTP 请求头 Content-Type: application/json 表示整个请求是 JSON；parts[].inlineData.mimeType / fileData.mimeType 表示输入文件格式；响应 inlineData.mimeType 表示生成图片的格式。JPG 应填 image/jpeg，MOV 应填 video/quicktime；修改后缀或 MIME 字符串不会转换文件格式。

其他格式的状态：

429 是本次请求失败状态，不能单凭它判定 Markdown 或 DOCX 格式被拒绝。保留请求 ID 排查额度、路由和上游；不要自动循环重发。

下载本页 Python 示例后可运行：

python gemini-image.py --attachment text/csv reference.csv --prompt "读取表格内容，生成一张信息图。" --output csv-result

python gemini-image.py --attachment application/json reference.json --prompt "读取 JSON 中的信息，生成一张示意图。" --output json-result

python gemini-image.py --text-file reference.md --prompt "根据文档内容生成一张示意图。" --output text-result

python gemini-image.py --video reference.webm --prompt "根据视频场景生成一张参考图。" --output webm-result

--text-file 将 UTF-8 文件内容作为文字发送，不包含原文档版式或嵌入图片。--attachment 当前接受上表已验证的 10 种 MIME；未知 MIME、明显不匹配的文件标识及无效 JSON 会在本地报错。多个附件可重复相应参数。

格式参考：Google 图片输入、Google 视频输入、2.1 模型输入类型。官方列出的通用格式不等于本站各模型均已验收。

6.7 公开文件 URL 与 Files 上传

公开 HTTPS 文件 URL 已验证 PDF 和 MP4。 将文件放到上游能访问、无需登录、直接返回文件字节的地址；返回登录页或 HTML 预览页的链接不是文件直链。请求仍发送到 POST /v1beta/models/gemini-nano-banana-2.1:generateContent：

{

  "contents": [{

    "role": "user",

    "parts": [

      {"fileData": {"mimeType": "application/pdf", "fileUri": "https://yyds.seqnode.com/api-docs/parameter-test-fixtures/mime-20261007/fixture.pdf"}},

      {"text": "读取 PDF 每页的编号、颜色和形状，再生成一张参考图。"}

    ]

  }],

  "generationConfig": {

    "responseModalities": ["TEXT", "IMAGE"],

    "imageConfig": {"imageSize": "1K", "aspectRatio": "3:2"}

  }

}

上面是本站公开的合成测试 PDF。MP4 示例直链为 https://yyds.seqnode.com/api-docs/parameter-test-fixtures/mime-20261007/fixture.mp4，对应 MIME 为 video/mp4。这些 URL 样本验证了文件获取和内容读取；私有链接、签名 URL、重定向、大体积 URL 输入尚未逐项验证。

Files 上传仍未接通： GET /v1beta/files 为 404；官方 resumable 上传的初始化请求 POST /upload/v1beta/files 返回 HTML，缺少 X-Goog-Upload-URL。因此 HTTP 200 不表示上传成功，当前不要按本站已支持 files.upload() 来接入。公开 HTTPS fileData.fileUri 与 Google Files 上传得到的 URI 是不同流程。

协议参考：官方文件输入方式、官方 Files API。

6.8 大文件、多附件及其他模型实测

以下均为 2026-10-07 的单次样本结果，不是平台上限或时延承诺。附件编号未出现在提示词中。

同分组其他模型使用相同 PDF / MP4 样本和原生端点测试：

Pro 非 preview 两次请求均为 502，尚未确认原因，不能据此判定 PDF 或 MP4 格式本身不支持。不同模型的响应可能只含图片，缺少文字编号不等于没有读取附件；本表按实际证据标注，不将 HTTP 200 直接等同于内容验收通过。

6.9 视频是否真正参与生图：对照与重复验证

2026-10-07 补测结论：在本组受控样本中，2.1 确实把视频中首帧之后的内容用于生成图片，并保留了场景顺序。 本轮检查最终图片中的编号、颜色、形状与左右顺序，而不只看 HTTP 状态或文字回答。

测试使用二号站 139 分组的 gemini-nano-banana-2.1，原生 generateContent，完整视频通过 inlineData + video/mp4 传入，输出 1K、3:2。三段视频均为 9 秒、640×480、12 fps、H.264、无音轨，每个静态场景持续 3 秒。客户端没有抽帧后改用图片提交。

对照设计： A、B 视频第一帧及首个场景完全相同，后两个场景不同。提示词完全一致，只要求按顺序复现参考内容，不含编号、颜色或具体形状。A、B 分别请求两次，再请求 A 的场景倒序版本；另加仅首帧图片、无附件、损坏视频三项对照。共 8 次独立请求，无自动重试。

5 次有效视频请求的生成图片全部完成视觉核对；这是小样本结果，不是对所有视频的成功率承诺。A 第二次文字回答将一个编号换行拆开，生成图片上的编号仍正确；判定时区分文字排版和最终图片。

可查看的证据： 视频 A、视频 B、倒序视频、完整测试记录（提示词、请求 ID、耗时与图片哈希）。以下图片均为实际素材或接口返回结果。

A 视频的三个源场景：

A 第一次生成结果：

B 视频的三个源场景：

B 第一次生成结果：

倒序视频生成结果：

其余输出：A 第二次、B 第二次、仅首帧、无附件。

接入验收标准： 先检查 HTTP / 错误，再检查最终图片，最后核对参考素材中特有的内容。无附件对照也返回了一张图片，因此“HTTP 200 + 有图片”不足以证明参考输入生效。

本轮证明的是这些视频场景影响了最终生图，且效果超出仅首帧参考；未核实上游内部采用何种抽帧或视频处理方式。快速运动、短暂闪现、精确时间定位、音轨、真实人物身份与复杂长视频的还原质量仍需专项验证。原先 180 秒视频测试只证明样本编号被读取并返回图片，不等同于逐帧理解整段长视频。文档覆盖了当前接入路径及已验证范围，尚不表示所有文件、模型与内容质量均已完整验收。

7. 错误处理与验收

验收范围：139 分组模型列表、香蕉 2.1 的 1K 文生图与附件参考输入，以及 6.6—6.8 的 MIME、文件 URL、大文件、长视频、多附件和其他模型测试。本页示例不代表所有参数组合和高级功能均已验证。

8. Google 官方文档

• Models：模型列表与模型详情
• GenerateContent 请求与响应字段
• GenerateContent 生图与图片编辑
• 文件输入方式
• Files API

官方资料用于解释协议；本站支持范围以本页实测说明和当前 Key 为准。