# 139 分组 · 香蕉 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
# 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"
```

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

```json
{
  "models": [{
    "name": "models/gemini-nano-banana-2.1",
    "supportedGenerationMethods": ["generateContent", "streamGenerateContent"]
  }]
}
```

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

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

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

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

| 模型 ID | 用途 |
| --- | --- |
| `gemini-nano-banana-2.1` | 香蕉 2.1，本页默认示例 |
| `gemini-3.1-flash-image-preview` | Flash 图片 |
| `gemini-3.1-flash-image` | Flash 图片 |
| `gemini-3-pro-image-preview` | Pro 图片 |
| `gemini-3-pro-image` | Pro 图片 |

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

## 2. 文生图

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

```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"}
  }
}
```

```bash
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 对应写法：

```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` 项。

```json
{
  "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](gemini-image.py?v=20261007-mime)，仅使用 Python 3 标准库。先按前文设置 `BASE_URL` 和 `API_KEY`，再运行：

```bash
# 获取模型
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. 参数与图片响应

| 字段 | 说明 |
| --- | --- |
| `contents[].parts[].text` | 提示词，说明保留哪些元素、修改哪些元素 |
| `contents[].parts[].inlineData` | 参考图片；包含 `mimeType`、`data` |
| `generationConfig.responseModalities` | 本页采用 `["TEXT", "IMAGE"]` |
| `generationConfig.imageConfig.imageSize` | 分辨率档位，`1K` / `2K` / `4K`，使用大写；以具体模型及渠道支持为准 |
| `generationConfig.imageConfig.aspectRatio` | 宽高比，例如 `1:1`、`3:2`、`16:9`；本页验收使用 `3:2` |

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

成功响应的图片在 `candidates[].content.parts[].inlineData.data`，格式由 `mimeType` 标识：

```json
{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{"inlineData": {"mimeType": "image/jpeg", "data": "OUTPUT_IMAGE_BASE64"}}]
    },
    "finishReason": "STOP"
  }]
}
```

遍历所有 `parts`，不要假设第一项就是图片。原生响应采用 Base64，客户端可自行保存；本页不使用 OpenAI Images 的 `response_format: "url"` 参数。

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

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

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

| 输入 | `mimeType` | 本页复测样本 |
| --- | --- | --- |
| PDF | `application/pdf` | 两页，28,525 字节，每页带不同编号、颜色和形状 |
| MP4 视频 | `video/mp4` | 6 秒，640×480，H.264，20,709 字节，三个连续场景 |

### 6.1 PDF 参考生图

端点和鉴权：

```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
```

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

```json
{
  "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](gemini-image.py?v=20261007-mime)，把 PDF 放到当前目录。设置前文的 `BASE_URL` 和 `API_KEY` 后，这条命令在 PowerShell、Bash 均可运行：

```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`：

```json
{
  "contents": [{
    "role": "user",
    "parts": [
      {"inlineData": {"mimeType": "video/mp4", "data": "VIDEO_BASE64"}},
      {"text": "观看完整视频，先按出现顺序列出各场景中的编号、颜色和形状，再生成一张按该顺序排列的参考图。"}
    ]
  }],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {"aspectRatio": "3:2", "imageSize": "1K"}
  }
}
```

可运行示例：

```bash
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`，并调整提示词。

```powershell
$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`，并按 `inlineData.mimeType` 保存。示例跳过 `thought: true` 的中间内容。HTTP 200 后还需检查是否有最终图片。

| 测试 | 结果 | 耗时 | 输出 |
| --- | --- | --- | --- |
| 两页 PDF | 编号、顺序、颜色和形状核验通过 | 31.89 秒 | 1 张 JPEG，1264×848 |
| 三场景 MP4 | 编号、顺序、颜色和形状核验通过 | 20.76 秒 | 1 张 JPEG，1264×848 |


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

### 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 输入](https://ai.google.dev/gemini-api/docs/generate-content/document-processing)、[官方视频输入](https://ai.google.dev/gemini-api/docs/generate-content/video-understanding)、[文件输入方式](https://ai.google.dev/gemini-api/docs/generate-content/file-input-methods)。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`**。同一扩展名下的不同编码或复杂文件仍可能有差异。

| 文件 | `mimeType` | 本站验证结果 | Python 示例参数 |
| --- | --- | --- | --- |
| PNG | `image/png` | 已有单图参考验证 | `--image reference.png` |
| JPG / JPEG | `image/jpeg` | 200，读出附件编号并返回图片 | `--image reference.jpg` |
| WebP | `image/webp` | 200，读出附件编号并返回图片 | `--image reference.webp` |
| PDF | `application/pdf` | 两页 PDF 和约 15.49 MiB、30 页 PDF 通过 | `--pdf reference.pdf` |
| MP4 | `video/mp4` | H.264，6 秒和 180 秒视频通过 | `--video reference.mp4` |
| MOV | `video/quicktime` | H.264 样本通过 | `--video reference.mov` |
| WebM | `video/webm` | VP9 样本通过 | `--video reference.webm` |
| TXT | `text/plain` | UTF-8 内联附件通过 | `--attachment text/plain reference.txt` |
| CSV | `text/csv` | UTF-8 内联附件通过 | `--attachment text/csv reference.csv` |
| JSON | `application/json` | UTF-8 内联附件通过 | `--attachment application/json reference.json` |

“通过”指请求成功、返回至少一张最终图片，并从正常文字回答中核对出只存在于附件中的编号。基础 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 字符串不会转换文件格式。

其他格式的状态：

| 文件 | 正确 MIME / 接入方式 | 当前状态 |
| --- | --- | --- |
| Markdown | 原文件为 `text/markdown`；也可读取 UTF-8 内容放入 `parts[].text` | 原文件内联测试与一次复测均为 429，支持情况待确认；文本接入机制已通过 TXT 样本验证 |
| DOCX | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | 测试与一次复测均为 429，支持情况待确认；接入时可先导出 PDF |
| HEIC / HEIF | `image/heic` / `image/heif` | Google 图片文档列出，本站未实测 |
| MPEG / AVI / FLV / WMV / 3GPP | 分别为 `video/mpeg`、`video/avi`、`video/x-flv`、`video/wmv`、`video/3gpp` | Google 视频文档列出，本站未实测；当前脚本只接收已验证的 MP4 / MOV / WebM |
| XLSX / PPTX / DOC / ZIP / GIF / SVG | 按真实文件格式处理 | 本轮未验证；表格可导出 CSV，文档/演示可导出 PDF，图片可转换 PNG |
| MP3 / WAV 等音频 | 取决于具体模型 | 2.1 官方输入类型列为文字、图片、视频、PDF，未列音频；本站未验证音频，不作支持承诺 |

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

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

```bash
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 图片输入](https://ai.google.dev/gemini-api/docs/generate-content/image-understanding)、[Google 视频输入](https://ai.google.dev/gemini-api/docs/generate-content/video-understanding)、[2.1 模型输入类型](https://ai.google.dev/gemini-api/docs/models/gemini-nano-banana-2.1)。官方列出的通用格式不等于本站各模型均已验收。

### 6.7 公开文件 URL 与 Files 上传

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

```json
{
  "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 是不同流程。

协议参考：[官方文件输入方式](https://ai.google.dev/gemini-api/docs/generate-content/file-input-methods)、[官方 Files API](https://ai.google.dev/api/files)。

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

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

| 2.1 测试 | 结果 | 耗时 |
| --- | --- | --- |
| 30 页 PDF，16,244,899 字节（约 15.49 MiB），有效内容位于第 1 / 15 / 30 页 | 200，读出三个编号并返回图片 | 47.63 秒 |
| 180 秒 MP4，三个不同场景 | 200，读出三个场景编号并返回图片 | 47.30 秒 |
| PDF + MP4 + JPEG 同一请求 | 200，读出各输入中的编号并返回图片 | 55.23 秒 |
| 公开 HTTPS PDF URL | 200，读出 PDF 编号并返回图片 | 52.06 秒 |
| 公开 HTTPS MP4 URL | 200，读出视频编号并返回图片 | 105.31 秒 |
| UTF-8 内容放入 `parts[].text` | 200，读出文本编号并返回图片 | 49.85 秒 |

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

| 模型 | PDF | MP4 |
| --- | --- | --- |
| `gemini-3.1-flash-image-preview` | 200，返回图片；文字编号核对通过 | 200，返回图片；图片内容需单独核对 |
| `gemini-3.1-flash-image` | 200，返回图片；图片内容需单独核对 | 200，返回图片；文字编号核对通过 |
| `gemini-3-pro-image-preview` | 200，返回图片；图片内容需单独核对 | 200，返回图片；图片内容需单独核对 |
| `gemini-3-pro-image` | 502，本次失败，未确认格式支持 | 502，本次失败，未确认格式支持 |


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 次独立请求，无自动重试。

| 请求 | 实际输入 | 最终结果 | 耗时 |
| --- | --- | --- | --- |
| A 第一次 | 灰六边形 → 蓝三角形 → 橙方块 | 200；三组编号、颜色、形状、顺序均核对通过 | 23.86 秒 |
| B 第一次 | 灰六边形 → 紫星形 → 绿菱形 | 200；三组编号、颜色、形状、顺序均核对通过 | 22.92 秒 |
| A 第二次 | 与 A 第一次相同 | 200；再次核对通过，版式略有变化 | 40.29 秒 |
| B 第二次 | 与 B 第一次相同 | 200；再次核对通过，版式略有变化 | 29.45 秒 |
| A 场景倒序 | 橙方块 → 蓝三角形 → 灰六边形 | 200；输出场景及编号顺序随视频反转 | 30.02 秒 |
| 仅首帧 PNG | 只有灰六边形 `KITE-5729` | 200；只生成对应的一个场景，未补出后续场景 | 21.18 秒 |
| 无附件 | 仅相同提示词 | 200；文字及图片均为 `NO_REFERENCE`，未出现测试编号或图形 | 18.09 秒 |
| 损坏视频 | 普通文字字节冒充 `video/mp4` | 400 / `INVALID_ARGUMENT`，无图片 | 10.82 秒 |

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

**可查看的证据：** [视频 A](parameter-test-fixtures/video-proof-20261007/a.mp4)、[视频 B](parameter-test-fixtures/video-proof-20261007/b.mp4)、[倒序视频](parameter-test-fixtures/video-proof-20261007/reverse.mp4)、[完整测试记录（提示词、请求 ID、耗时与图片哈希）](parameter-test-fixtures/video-proof-20261007/evidence.json)。以下图片均为实际素材或接口返回结果。

A 视频的三个源场景：

![A 视频源场景：灰六边形 KITE-5729、蓝三角形 MOSS-8146、橙方块 FERN-3068](parameter-test-fixtures/video-proof-20261007/a-source.jpg)

A 第一次生成结果：

![A 视频生图：三个场景的编号、颜色、形状及顺序与素材一致](parameter-test-fixtures/video-proof-20261007/a1-image-1.jpg)

B 视频的三个源场景：

![B 视频源场景：相同灰六边形首帧，后续为紫星形 IRIS-9623、绿菱形 REED-4517](parameter-test-fixtures/video-proof-20261007/b-source.jpg)

B 第一次生成结果：

![B 视频生图：后续场景随视频内容变为紫星形和绿菱形](parameter-test-fixtures/video-proof-20261007/b1-image-1.jpg)

倒序视频生成结果：

![倒序视频生图：橙方块 FERN-3068、蓝三角形 MOSS-8146、灰六边形 KITE-5729](parameter-test-fixtures/video-proof-20261007/reverse-image-1.jpg)

其余输出：[A 第二次](parameter-test-fixtures/video-proof-20261007/a2-image-1.jpg)、[B 第二次](parameter-test-fixtures/video-proof-20261007/b2-image-1.jpg)、[仅首帧](parameter-test-fixtures/video-proof-20261007/first-frame-image-1.jpg)、[无附件](parameter-test-fixtures/video-proof-20261007/no-reference-image-1.jpg)。

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

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


## 7. 错误处理与验收

| 现象 | 检查方法 |
| --- | --- |
| 401 / 403 | 检查本站 Key、绑定分组、状态和访问权限 |
| 模型列表为空 / 模型不可用 | 用同一 Key 重新获取模型列表，检查模型完整名称 |
| 400 | 检查 JSON、Base64、真实 MIME、参数大小写 |
| 413 | 请求体超过入口限制，减少附件体积；Base64 会增加请求大小 |
| 429 | 降低并发，结合 `Retry-After` 和当前额度安排重试 |
| 451 / 内容被拦截 | 检查返回错误与内容限制；不代表模型列表或跨域故障 |
| 502 / 503 / 504 | 保留时间、模型、HTTP 状态与请求 ID，排查上游和账号状态 |
| 200 但没有图片 | 检查 `promptFeedback`、`candidates[].finishReason` 和全部 `parts` |

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

## 8. Google 官方文档

- [Models：模型列表与模型详情](https://ai.google.dev/api/models)
- [GenerateContent 请求与响应字段](https://ai.google.dev/api/generate-content)
- [GenerateContent 生图与图片编辑](https://ai.google.dev/gemini-api/docs/generate-content/image-generation)
- [文件输入方式](https://ai.google.dev/gemini-api/docs/generate-content/file-input-methods)
- [Files API](https://ai.google.dev/api/files)

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