Gemini 3.1 Flash Image API 调用

图像模型 gemini-3.1-flash-image（Nano Banana 2）走 Gemini 原生协议，不使用 OpenAI Images 端点：

Base URL：https://api.teamorouter.com
端点：POST https://api.teamorouter.com/v1beta/models/{model}:generateContent
鉴权：Authorization: Bearer sk-teamo-xxxxxx

调用前先用 GET /v1/models 查询模型是否可用，实际可用的模型与路由能力以实时返回为准。

一、生成图片

bash

curl https://api.teamorouter.com/v1beta/models/gemini-3.1-flash-image:generateContent \
  -H "Authorization: Bearer sk-teamo-xxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "生成一张 16:9 的极简科技海报"}]}
    ],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
    }
  }'

返回的图片是 Base64，位于 candidates[0].content.parts[].inlineData：

json

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgo..."
            }
          }
        ]
      }
    }
  ]
}

遍历全部 parts 查找 inlineData，不要假设图片总是第一项；不要把完整 Base64 写进日志。

二、请求参数

字段	常用值	说明
`contents[].role`	`user`	消息角色
`contents[].parts[].text`	Prompt 字符串	描述主体、风格、构图、文字和限制条件
`contents[].parts[].inlineData`	`mimeType` + Base64 `data`	编辑图片时传入原图
`generationConfig.responseModalities`	`["IMAGE"]` 或 `["TEXT", "IMAGE"]`	控制返回图片、文字
`generationConfig.imageConfig.aspectRatio`	`1:1`、`16:9`、`9:16` 等	输出宽高比
`generationConfig.imageConfig.imageSize`	`512`、`1K`、`2K`、`4K`	输出分辨率，默认 `1K`

分辨率档位

下表以 1:1 为例，其他宽高比会得到对应的非正方形尺寸：

`imageSize`	1:1 输出尺寸	图片输出 tokens（约）	推荐场景
`512`	512 × 512	747	预览、草稿、低成本批量试稿
`1K`	1024 × 1024	1120	默认档，社媒图与普通商品图
`2K`	2048 × 2048	1680	海报、详情页、含较多文字的图片
`4K`	4096 × 4096	2520	高清交付、印刷或后期裁切

支持的宽高比：1:1、1:4、1:8、2:3、3:2、3:4、4:1、4:3、4:5、5:4、8:1、9:16、16:9、21:9。

生产代码请使用大写 1K、2K、4K；网关实测兼容小写 2k，但不建议依赖该行为。

三、Python 接入

bash

pip install requests

python

import base64
import os
from pathlib import Path

import requests

BASE_URL = "https://api.teamorouter.com"
API_KEY = os.environ["TEAMO_API_KEY"]
MODEL = "gemini-3.1-flash-image"

response = requests.post(
    f"{BASE_URL}/v1beta/models/{MODEL}:generateContent",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "contents": [
            {
                "role": "user",
                "parts": [{"text": "生成一张 16:9 的极简科技海报"}],
            }
        ],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"},
        },
    },
    timeout=300,
)
response.raise_for_status()
result = response.json()

parts = result["candidates"][0]["content"]["parts"]
image_part = next(part for part in parts if "inlineData" in part)
image_bytes = base64.b64decode(image_part["inlineData"]["data"])
Path("image.png").write_bytes(image_bytes)

四、JavaScript / TypeScript 接入

Node.js 18+ 可以直接使用 fetch：

javascript

import fs from "node:fs";

const baseURL = "https://api.teamorouter.com";
const apiKey = process.env.TEAMO_API_KEY;
const model = "gemini-3.1-flash-image";

const response = await fetch(
  `${baseURL}/v1beta/models/${model}:generateContent`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      contents: [
        {
          role: "user",
          parts: [{ text: "生成一张 16:9 的极简科技海报" }],
        },
      ],
      generationConfig: {
        responseModalities: ["IMAGE"],
        imageConfig: { aspectRatio: "16:9", imageSize: "2K" },
      },
    }),
    signal: AbortSignal.timeout(300_000),
  },
);

if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const result = await response.json();
const parts = result.candidates?.[0]?.content?.parts ?? [];
const image = parts.find((part) => part.inlineData?.data);
if (!image) throw new Error("响应中没有图片块");

fs.writeFileSync("image.png", Buffer.from(image.inlineData.data, "base64"));

五、编辑图片

图片编辑使用同一个端点，在 parts 中同时传入文字指令和 Base64 原图：

json

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "保留主体和构图，把背景改成日落海滩，不添加文字"},
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "<BASE64_IMAGE>"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["IMAGE"],
    "imageConfig": {"imageSize": "2K"}
  }
}

六、生产接入建议

启动时或定时调用 /v1/models，不要只依赖静态模型表；只展示实时列表中存在的模型。
生图响应较慢，客户端超时建议设置为 300 秒。
仅对 429 和可恢复的 5xx 做指数退避；400 通常表示请求或路由问题，重试无意义。
API Key 只放在服务端环境变量或密钥管理系统中，不写前端、不入库、不记日志。
校验 HTTP 状态码、candidates、finishReason、inlineData.mimeType 和 Base64 解码结果。
限制并发数、输出分辨率、参考图数量和每日额度。

七、常见错误

401 / authentication failed

确认请求头是 Authorization: Bearer sk-teamo-xxxxxx，Key 完整且没有多余空格。怀疑泄露时立即在控制台删除并新建。

400 / invalid endpoint format

gemini-3.1-flash-image 使用 Gemini 原生地址 https://api.teamorouter.com/v1beta/models/{model}:generateContent，不要在前面额外添加 /v1。

404 或模型不存在

先查询 /v1/models。模型不在实时列表中时应视为当前网关尚未开放，不要继续重试。

请求成功但没有图片

确认 responseModalities 包含 IMAGE，遍历所有 parts 查找 inlineData，同时检查 finishReason 与安全拦截信息。

准备好了？三步即可开始登录控制台 · 购买额度 · 创建 API Key

获取 API Key 查看定价

DiscordGet community help instantly

Join Discord