Token Switch 文档中心

中文

English

中文

English

Appearance

Gemini 图像生成 ​

使用本接口输入文本描述或参考图片，创建图像生成任务，支持文生图（Text-to-Image）与图生图（图像编辑 / Image Editing）。Gemini 图像模型统称 Nano Banana，内置思考（Thinking）过程，生成的图像以 Base64 编码返回，并带有 SynthID 水印。

接口地址 ​

http
POST /v1beta/models/<Model ID>:generateContent

认证 ​

方式说明
Bearer Token在请求头中携带 Authorization: Bearer <API_key> 用于验证账户信息。

鉴权说明： 如遇到不能识别 Authorization 参数的情形，可将鉴权信息通过 x-goog-api-key 请求头传递：

http
x-goog-api-key: <API Key>

请求头 ​

参数名类型必填说明
Content-Typestring是请求体的媒介类型，请设置为 application/json
Authorizationstring是Bearer API_key，用于验证账户信息

说明： 模型 ID 以 URL 路径中的 <Model ID> 占位符指定（如 /v1beta/models/ge-3.1-fl-im:generateContent），请求体中无需再传模型字段。

请求体 ​

参数名类型必填默认值说明
contentsarray是-输入内容列表，可包含文本与图片，详情见下方子表格
generationConfig.responseModalitiesarray是["TEXT"]输出模态，图像生成需设置为 ["IMAGE"]；需要同时返回文本与图像时设置为 ["TEXT","IMAGE"]
generationConfig.imageConfigobject否-图像生成配置（宽高比、分辨率、人物等），详情见下方子表格
toolsarray否-工具配置，如 [{ "googleSearch": {} }] 可基于实时信息联网生成图像

contents 详细参数 ​

参数名类型必填说明
contents[].rolestring否消息角色，取值 user / model；省略时默认为 user
contents[].partsarray是内容片段列表，支持文本与图片，详情见下方 parts 子表格

parts 详细参数 ​

参数名类型必填说明
parts[].textstring否文本提示词，用于描述期望生成的图像或编辑指令
parts[].inline_dataobject否内嵌图片数据，用于图生图（图像编辑）场景，与 text 二选一或同时使用
parts[].inline_data.mime_typestring条件必填图片 MIME 类型，如 image/png、image/jpeg、image/webp
parts[].inline_data.datastring条件必填图片的 Base64 编码内容（不含 data:...;base64, 前缀）

imageConfig 详细参数 ​

参数名类型必填默认值说明
imageConfig.aspectRatiostring否1:1生成图像的宽高比，可选值见下方列表
imageConfig.imageSizestring否1K输出图像分辨率，取值 1K、2K、4K，ge-3.1-fl-im 额外支持 0.5K（512px）。K 必须大写，小写（如 1k）会被拒绝
imageConfig.personGenerationstring否dont_allow是否允许生成人物图像，取值：dont_allow（禁止生成人物）、allow_adult（允许生成成年人）、allow_all（允许生成所有人物，包括儿童）

宽高比（aspectRatio）取值 ​

  • ge-3.1-fl-im / ge-3-pr-im / ge-2.5-fl-im：1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9
  • ge-3.1-fl-im 额外支持：1:4、1:8、4:1、8:1

请求示例 ​

文生图 ​

通过 responseModalities 请求图像输出，使用文本提示词生成一张图像。

bash
curl --location --request POST 'https://neolink.com/api/v1beta/models/<Model ID>:generateContent' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "contents": [
             {
                 "parts": [
                     {
                         "text": "一只可爱的橘猫，戴着圆框眼镜，坐在窗台边看报纸，午后阳光洒落"
                     }
                 ]
             }
         ],
         "generationConfig": {
             "responseModalities": ["IMAGE"],
             "imageConfig": {
                 "aspectRatio": "1:1",
                 "imageSize": "2K",
                 "personGeneration": "dont_allow"
             }
         }
     }'
python
import base64
import requests

url = "https://neolink.com/api/v1beta/models/<Model ID>:generateContent"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "contents": [
        {
            "parts": [
                {
                    "text": "一只可爱的橘猫，戴着圆框眼镜，坐在窗台边看报纸，午后阳光洒落"
                }
            ]
        }
    ],
    "generationConfig": {
        "responseModalities": ["IMAGE"],
        "imageConfig": {
            "aspectRatio": "1:1",
            "imageSize": "2K",
            "personGeneration": "dont_allow"
        }
    }
}

resp = requests.post(url, headers=headers, json=payload, timeout=60)
resp.raise_for_status()
data = resp.json()

# 提取返回图像并保存
for part in data["candidates"][0]["content"]["parts"]:
    if "inlineData" in part:
        image = part["inlineData"]["data"]
        with open("output.png", "wb") as f:
            f.write(base64.b64decode(image))
        break

图生图（图像编辑） ​

在 parts 中同时传入参考图片（inline_data）与编辑指令文本，模型基于参考图执行图像编辑。

Base64 编码说明： inline_data.data 为图片文件进行 Base64 编码后的字符串，参考脚本如下：

bash
#!/usr/bin/env bash
set -euo pipefail
IMAGE_PATH="./input.jpg"

if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
    B64FLAGS="--input"
else
    B64FLAGS="-w0"
fi
base64 $B64FLAGS "$IMAGE_PATH" > base64.txt
bash
curl --location --request POST 'https://neolink.com/api/v1beta/models/<Model ID>:generateContent' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "contents": [
             {
                 "parts": [
                     {
                         "text": "将图片中的背景替换为海边日落，画面保持写实风格"
                     },
                     {
                         "inline_data": {
                             "mime_type": "image/jpeg",
                             "data": "<Base64 Code>"
                         }
                     }
                 ]
             }
         ],
         "generationConfig": {
             "responseModalities": ["IMAGE"],
             "imageConfig": {
                 "aspectRatio": "16:9",
                 "personGeneration": "dont_allow"
             }
         }
     }'
python
import base64
import requests

url = "https://neolink.com/api/v1beta/models/<Model ID>:generateContent"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

# 读取本地图片并编码
with open("input.jpg", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode("utf-8")

payload = {
    "contents": [
        {
            "parts": [
                {
                    "text": "将图片中的背景替换为海边日落，画面保持写实风格"
                },
                {
                    "inline_data": {
                        "mime_type": "image/jpeg",
                        "data": image_base64
                    }
                }
            ]
        }
    ],
    "generationConfig": {
        "responseModalities": ["IMAGE"],
        "imageConfig": {
            "aspectRatio": "16:9",
            "personGeneration": "dont_allow"
        }
    }
}

resp = requests.post(url, headers=headers, json=payload, timeout=60)
resp.raise_for_status()
data = resp.json()

# 提取返回图像并保存
for part in data["candidates"][0]["content"]["parts"]:
    if "inlineData" in part:
        image = part["inlineData"]["data"]
        with open("output.png", "wb") as f:
            f.write(base64.b64decode(image))
        break

支持模型Id： ​

  • ge-3.1-fl-im（Nano Banana 2）——综合性能与成本的最佳平衡，最推荐的图像模型。支持最高 4K、512px 小图，最多 10 个物体 / 4 个角色的一致性参考，支持 Google 搜索与图片搜索互联生成、视频转图像
  • ge-3.1-fl-li-im（Nano Banana 2 Lite）——最快最便宜的图像模型，仅支持 1K 分辨率，不支持联网搜索与多轮编辑，最多 14 个物体的高保真参考
  • ge-3-pr-im（Nano Banana Pro）——专业级图像模型，最高 4K，适合复杂指令与专业素材生产。支持最多 6 个物体 / 5 个角色 / 3 个风格参考，支持交错输出文本与图像、联网搜索
  • ge-2.5-fl-im（Nano Banana）——前代模型，固定 1024px 分辨率，最多 3 张参考图，建议迁移到 Nano Banana 2 Lite

<Model ID> 需替换为具体模型 ID，即 列出模型 返回的 name 去掉 models/ 前缀后的名称，如 ge-3.1-fl-im；具体可用模型、分辨率与参考图数量以平台实际为准。

响应体 ​

参数名类型说明
candidatesarray生成的候选结果列表
candidates[].contentobject模型生成的内容
candidates[].content.rolestring消息角色，固定为 model
candidates[].content.partsarray内容片段列表，图像生成时包含 inlineData
candidates[].content.parts[].inlineData.mimeTypestring生成图像的 MIME 类型，如 image/png
candidates[].content.parts[].inlineData.datastring生成图像的 Base64 编码数据
candidates[].finishReasonstring停止原因：STOP（正常结束）/ MAX_TOKENS / SAFETY / RECITATION / IMAGE_SAFETY / PROHIBITED_CONTENT 等
usageMetadataobjectToken 用量信息
usageMetadata.promptTokenCountint输入 Prompt 的 token 数
usageMetadata.candidatesTokenCountint生成的响应 token 数
usageMetadata.totalTokenCountint输入与输出的总 token 数
modelVersionstring实际使用的模型版本

响应示例 ​

json
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "<Base64 Code>"
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 11,
    "candidatesTokenCount": 1290,
    "totalTokenCount": 1301
  },
  "modelVersion": "ge-3.1-fl-im"
}

说明：

  • 返回的图像数据为 Base64 编码字符串（inlineData.data 字段），需在客户端解码后使用或保存为图片文件，解码参考脚本见上文"图生图（图像编辑）"一节。
  • 图像模型内置思考（Thinking）过程，默认开启，用于先优化构图再输出最终图像；所有生成图像均带 SynthID 水印。
  • 通过 tools 启用 Google 搜索可基于实时信息生成图像（ge-3.1-fl-im 还支持 Google 图片搜索），该能力在 ge-3.1-fl-li-im 上不支持。