Gemini 图片 API 中转，是应用与 Gemini 图片模型之间的一层 API 网关。 接入时需要确认三个要素：能输出图片的模型 ID、中转服务的请求格式，以及获取实际图片的方式。只给文本客户端换一个 Base URL，不能证明它已经支持生图。

OmniaKey 公开文档中的图片流程是 创建任务 → 轮询状态 → 下载图片，创建入口为 POST /v1/media/tasks。本文按这套流程说明接入步骤，同时说明它与 Google 原生接口、OpenAI 兼容接口的区别。

文档核验日期：2026 年 10 月 14 日。本文由 OmniaKey 根据 Google 和 OmniaKey 的公开文档编写；本次没有发起付费图片生成，也没有测量供应商速度或画质。模型出现在目录中，不代表每个 Key 都有权限或当前一定有可用渠道。

先确认你需要哪一种中转

这里的“中转”指处理模型请求、鉴权与响应的应用层 API 服务。网络代理可以转发流量，但不会自动把一种图片接口转换成另一种。应以服务实际公布的接口规范为准。

接口类型	请求格式	从哪里拿到图片
Gemini GenerateContent	`/v1beta/models/MODEL:generateContent`，使用 `contents` 和模型支持的 `generationConfig` 字段	`candidates[].content.parts[].inlineData` 等图片内容块
OpenAI 兼容中转	供应商规定的端点与图片请求格式	供应商规定的图片数据或 URL，需要核对响应结构
OmniaKey 图片任务	`/v1/media/tasks`，使用 `model`、`type`、`operation`、`input`、`parameters`	先返回任务 ID；状态为 `succeeded` 后读取 `assets[]`

Google 当前的图片生成指南以 Interactions API 为例；GenerateContent 参考文档则定义另一套规范。不要混用两者的字段和响应解析方式，也不要默认中转服务同时支持两者。

还要区分图片理解与图片生成：能接收图片并描述内容的模型，可能只输出文本。文本调用成功，不能证明生图或编辑可用。“兼容 OpenAI”也不等于某个图片渠道支持所有 OpenAI SDK 方法。

选择具体图片模型，不要只填 Gemini

Google 的模型说明区分了以下 ID：

Nano Banana 2.1： gemini-nano-banana-2.1，Google 建议新建通用图片工作流优先评估的版本。
Nano Banana Pro： gemini-3-pro-image，用于评估要求更高的视觉任务，是独立模型。
Nano Banana 2： gemini-3.1-flash-image，上一代模型，并非 2.1 的别名。

从准备调用的服务中复制准确 ID，并核对权限、生成与编辑能力、尺寸和计费单位。OmniaKey 的 2.1 任务使用 parameters.aspect_ratio 与 parameters.image_size，输出档位为 1K、2K、4K。这些字段不能直接换成 Google 原生的 imageConfig，也不能照搬 GPT Image 的 size、quality。

当前网关配置可查 Nano Banana 2.1 模型页。需要进一步选型，可看 2.1 与 Pro 的对比。

通过 OmniaKey 生成一张图片

以下命令需要 Bash、cURL、jq，以及保存在本地 OMNIAKEY_API_KEY 环境变量中的 OmniaKey API Key。请在后端或开发机运行，不要把 Key 放进浏览器代码。示例使用简单的英文提示词，先验证接口流程，再评估画质。

1. 创建并保存任务

为这次图片请求选择唯一的 Idempotency-Key。示例是便于识别的演示值：新任务先换一个值，重试同一个任务时保持 Key 和请求体完全不变。应用应在发请求前保存这两项。

bash

curl --fail-with-body --silent --show-error \
  https://api.omniakey.com/v1/media/tasks \
  -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: gemini-image-demo-20261014-001" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "type": "image",
    "operation": "generate",
    "input": {"prompt": "A blue ceramic cup on a white studio table, no text"},
    "parameters": {"aspect_ratio": "1:1", "image_size": "1K"}
  }' -o task.json

只有 cURL 成功且 task.json 中存在 id，才继续操作。新任务返回 202 Accepted；相同 Key 与请求体重放时返回原任务，状态码为 200。这表示任务已被接受，不表示图片已完成，详见任务生命周期文档。

2. 用已保存的 ID 轮询

下面的 Bash 示例设置了轮询次数上限。达到上限后，仍可用保存的 ID 继续查询；它不会取消任务，也不会重新创建。

bash

TASK_ID="$(jq -er '.id' task.json)" || exit 1
for attempt in {1..60}; do
  curl --fail-with-body --silent --show-error \
    "https://api.omniakey.com/v1/media/tasks/$TASK_ID" \
    -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
    -o result.json || exit 1
  STATUS="$(jq -er '.status' result.json)" || exit 1
  case "$STATUS" in
    succeeded) break ;;
    failed|canceled) jq '.error' result.json; exit 1 ;;
    queued|processing) sleep 3 ;;
    *) exit 1 ;;
  esac
done

如果创建请求超时，尚未拿到 ID，应使用相同请求体和幂等键恢复。一旦拿到 ID，就查询原任务。更换 Key 可能产生第二个计费任务。恢复受保留期限制：文档规定任务记录在创建后保留 24 小时。

3. 仅下载成功任务的结果

bash

jq -e '.status == "succeeded"' result.json >/dev/null || exit 1
ASSET_URL="$(jq -er '.assets[0].url' result.json)" || exit 1
curl --fail --location --silent --show-error \
  "$ASSET_URL" -o generated-image

根据资源的 mime_type 添加正确文件扩展名，并检查文件能否打开、尺寸是否符合预期。签名 URL 会过期，在任务与资源仍有效时重新查询可获得新链接。需要长期使用的图片请及时下载，签名链接不是永久存储地址。

携带参考图进行编辑

使用 operation: "edit"，在 input.image 中传内联 Base64；支持多参考图的场景使用 input.images。编辑指令仍放在 input.prompt。完整格式见图片 API 文档。

任务接口的整个请求体上限为 1 MiB，包括 Base64 数据。必要时先压缩或缩小参考图。Google 直连接口的上传限制不能替代中转接口的限制。先用一张小图验证一个明确修改，再检查需要保留的部分。

修改提示词、参考图、模型或参数都属于新请求，需要新的幂等键。沿用旧 Key 发送不同请求体会得到 409 idempotency_key_reused。

按故障发生的层级排查

现象	优先检查	下一步
`401` / `403`	Key、域名、鉴权格式、模型权限	先修正凭据或权限
`400` / `404`	端点、模型 ID、字段、任务归属	核对接口文档，不猜模型别名
`413`	包括 Base64 在内的请求体大小	缩小输入图片后再提交
`409 idempotency_key_reused`	相同 Key 是否对应不同请求体	恢复任务用原请求体，新任务用新 Key
`429`	额度、请求速率、并发	读取错误说明，降低负载，适用时采用有界退避
`503`	配置问题还是临时容量不足	OmniaKey 的 `worker_disabled`、`no_available_channel` 需检查配置或渠道可用性
只有文字或输出为空	生图能力、安全反馈、响应解析	GenerateContent 检查 `promptFeedback`、`finishReason` 和全部内容块
轮询超时	任务是否仍在运行	用同一 ID 恢复，不因本地等待结束而重建

Google 错误排查文档解释的是 Google 自身行为，中转会增加另一层。请在脱敏日志中记录 HTTP 状态、错误码、任务 ID 和耗时，不记录 Key 或私有参考图。只拿到 200 JSON，还不能算获得可用图片。

比较成本，并验收接入结果

Google 直连价格与中转报价是两种不同服务。批量调用前查看 OmniaKey 当前价格和对应模型的计费单位；不要用文本 token 单价计算图片输出，也不要默认 Gemini 消费者订阅能抵扣中转调用。

实用口径是：实际扣费总额 ÷ 验收通过的图片数。计入收费重试和生成成功但被人工淘汰的图片。这是预算公式，不是实测结果，也不证明某家一定便宜。

放量前至少验证五种小场景：

文本生图返回能打开的图片，格式与尺寸符合预期。
单参考图编辑完成指定修改，并保留关键细节。
相同 Key 与请求体重放得到同一个任务 ID。
本地轮询超时后，可以按 ID 继续查询，不创建新任务。
错误参数或不可用模型返回可理解的错误，而非虚假成功。

记录模型 ID、参数、耗时、最终状态、扣费与验收结果。发送正式业务素材前，确认服务如何处理提示词与参考图片。

常见问题

原来的 SDK 只换 Base URL 就能用吗？

只有中转服务明确支持该 SDK 所需的端点、字段和图片响应格式时才成立。必须验证图片操作本身，不能以文本聊天成功替代。

中转能取消 Gemini 的限制吗？

不能。供应商限制、模型能力、中转限制与账号权限可能同时生效。网关不代表无限生图，也不自动证明地区可用性。

应该先用哪个模型？

先查当前模型目录，再用小任务评估可用图片模型。Nano Banana 2.1 指南介绍模型变化；本文重点是 API 接入与验收。

资料与下一步

主要依据为 Google 的图片指南、GenerateContent 参考、错误排查指南，以及文中链接的 OmniaKey 图片和任务文档。Google 链接为英文资料。接口核验于 2026 年 10 月 14 日，运行示例前请确认当前模型权限。

创建 OmniaKey API Key 阅读图片 API 文档

Gemini 图片 API 中转接入指南