图片编辑 API 参考

Nano Banana 2 图片编辑 API 参考与在线调试 — 输入图片 + 指令生成新图片

POST /v1beta/models/gemini-3.1-flash-image-preview:generateContent

图片编辑：根据指令编辑现有图片

cURL

curl --request POST \
  --url https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contents": [
    {
      "parts": [
        {
          "text": "把这两张图里的人物合成到同一个办公室场景中，做着搞怪表情"
        },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "<BASE64_DATA_IMG_1>"
          }
        },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "<BASE64_DATA_IMG_2>"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "IMAGE"
    ],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "2K"
    }
  }
}
'

import requests

url = "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent"

payload = {
    "contents": [{ "parts": [{ "text": "把这两张图里的人物合成到同一个办公室场景中，做着搞怪表情" }, { "inlineData": {
                        "mimeType": "image/png",
                        "data": "<BASE64_DATA_IMG_1>"
                    } }, { "inlineData": {
                        "mimeType": "image/png",
                        "data": "<BASE64_DATA_IMG_2>"
                    } }] }],
    "generationConfig": {
        "responseModalities": ["IMAGE"],
        "imageConfig": {
            "aspectRatio": "16:9",
            "imageSize": "2K"
        }
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    contents: [
      {
        parts: [
          {text: '把这两张图里的人物合成到同一个办公室场景中，做着搞怪表情'},
          {inlineData: {mimeType: 'image/png', data: '<BASE64_DATA_IMG_1>'}},
          {inlineData: {mimeType: 'image/png', data: '<BASE64_DATA_IMG_2>'}}
        ]
      }
    ],
    generationConfig: {
      responseModalities: ['IMAGE'],
      imageConfig: {aspectRatio: '16:9', imageSize: '2K'}
    }
  })
};

fetch('https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'contents' => [
        [
                'parts' => [
                                [
                                                                'text' => '把这两张图里的人物合成到同一个办公室场景中，做着搞怪表情'
                                ],
                                [
                                                                'inlineData' => [
                                                                                                                                'mimeType' => 'image/png',
                                                                                                                                'data' => '<BASE64_DATA_IMG_1>'
                                                                ]
                                ],
                                [
                                                                'inlineData' => [
                                                                                                                                'mimeType' => 'image/png',
                                                                                                                                'data' => '<BASE64_DATA_IMG_2>'
                                                                ]
                                ]
                ]
        ]
    ],
    'generationConfig' => [
        'responseModalities' => [
                'IMAGE'
        ],
        'imageConfig' => [
                'aspectRatio' => '16:9',
                'imageSize' => '2K'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent"

	payload := strings.NewReader("{\n  \"contents\": [\n    {\n      \"parts\": [\n        {\n          \"text\": \"把这两张图里的人物合成到同一个办公室场景中，做着搞怪表情\"\n        },\n        {\n          \"inlineData\": {\n            \"mimeType\": \"image/png\",\n            \"data\": \"<BASE64_DATA_IMG_1>\"\n          }\n        },\n        {\n          \"inlineData\": {\n            \"mimeType\": \"image/png\",\n            \"data\": \"<BASE64_DATA_IMG_2>\"\n          }\n        }\n      ]\n    }\n  ],\n  \"generationConfig\": {\n    \"responseModalities\": [\n      \"IMAGE\"\n    ],\n    \"imageConfig\": {\n      \"aspectRatio\": \"16:9\",\n      \"imageSize\": \"2K\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"contents\": [\n    {\n      \"parts\": [\n        {\n          \"text\": \"把这两张图里的人物合成到同一个办公室场景中，做着搞怪表情\"\n        },\n        {\n          \"inlineData\": {\n            \"mimeType\": \"image/png\",\n            \"data\": \"<BASE64_DATA_IMG_1>\"\n          }\n        },\n        {\n          \"inlineData\": {\n            \"mimeType\": \"image/png\",\n            \"data\": \"<BASE64_DATA_IMG_2>\"\n          }\n        }\n      ]\n    }\n  ],\n  \"generationConfig\": {\n    \"responseModalities\": [\n      \"IMAGE\"\n    ],\n    \"imageConfig\": {\n      \"aspectRatio\": \"16:9\",\n      \"imageSize\": \"2K\"\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"contents\": [\n    {\n      \"parts\": [\n        {\n          \"text\": \"把这两张图里的人物合成到同一个办公室场景中，做着搞怪表情\"\n        },\n        {\n          \"inlineData\": {\n            \"mimeType\": \"image/png\",\n            \"data\": \"<BASE64_DATA_IMG_1>\"\n          }\n        },\n        {\n          \"inlineData\": {\n            \"mimeType\": \"image/png\",\n            \"data\": \"<BASE64_DATA_IMG_2>\"\n          }\n        }\n      ]\n    }\n  ],\n  \"generationConfig\": {\n    \"responseModalities\": [\n      \"IMAGE\"\n    ],\n    \"imageConfig\": {\n      \"aspectRatio\": \"16:9\",\n      \"imageSize\": \"2K\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

200

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "<string>"
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 258
  }
}

右侧的交互式 Playground 支持下拉选择参数。请在 Authorization 中填入你的 API Key（格式：Bearer sk-xxx），即可一键发送请求测试。

场景说明：本页用于「图片编辑」，必须上传一张待编辑的图片（base64 编码）+ 编辑指令。如果只想根据文本生成新图片，请使用 文生图接口。

🖥️ 浏览器 Playground 限制（重要）

本接口的响应里包含 base64 编码的图片（inlineData.data，数 MB 量级）。受浏览器渲染限制，右侧 Playground 在收到响应后可能弹出 请求时发生错误: unable to complete request ——实际请求已经成功，只是浏览器无法把这么长的 base64 显示出来。

推荐做法（小白零踩坑）：

• 直接复制下方”代码示例”中的 Python / Node.js / cURL 到本地运行，代码会自动 base64.b64decode 并把图片保存为本地文件。
• 如要在浏览器里试 Playground，用极小的参考图（< 50KB） 并把 imageSize 设为最小档（如 512 / 1K）。

⚠️ parts 数组结构（重要，多图编辑必看）

每个 part 只能是 text 或 inlineData 中的一个，二者不能同时出现在同一个 part 里。这与谷歌官方 gemini-3.1-flash-image-preview 的契约一致。

正确：一个 text part（编辑指令）+ N 个 inlineData part（每张图一个）：

"contents": [{
  "parts": [
    {"text": "把这两张图里的人物合成到同一个办公室场景中"},
    {"inlineData": {"mimeType": "image/png", "data": "<BASE64_DATA_IMG_1>"}},
    {"inlineData": {"mimeType": "image/png", "data": "<BASE64_DATA_IMG_2>"}}
  ]
}]

错误（每个 part 同时塞了 text 和 inlineData，会导致非预期行为）：

"contents": [{
  "parts": [
    {"inlineData": {...}, "text": "这是提示词吗 1"},
    {"inlineData": {...}, "text": "这是提示词吗 2"}
  ]
}]

🖼️ 关于 inlineData.data 字段

本接口是 JSON 格式（非 multipart 文件上传），所以 Playground 无法直接选择本地文件，需要先把图片转成 Base64 字符串再粘贴到 data 输入框。

一行命令转换 + 自动复制到剪贴板：

# macOS
base64 -i your-image.jpg | tr -d '\n' | pbcopy

# Linux
base64 -w0 your-image.jpg | xclip -selection clipboard

# Windows PowerShell
[Convert]::ToBase64String([IO.File]::ReadAllBytes("your-image.jpg")) | Set-Clipboard

执行后直接在 Playground 的 data 字段 Cmd+V / Ctrl+V 粘贴即可。同时记得把 mimeType 切换为对应的 image/jpeg 或 image/png。

建议：测试用小图（< 200KB），避免 base64 字符串过长导致浏览器卡顿。频繁测试图片编辑更推荐用下方代码示例直接在本地运行。

​

代码示例

​

Python

import requests
import base64

API_KEY = "sk-your-api-key"

# 读取待编辑的图片
with open("input.jpg", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={
        "contents": [{
            "parts": [
                {"text": "请把背景模糊化，突出前景的人物"},
                {"inlineData": {"mimeType": "image/jpeg", "data": image_b64}}
            ]
        }],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
        }
    },
    timeout=300
).json()

img_data = response["candidates"][0]["content"]["parts"][0]["inlineData"]["data"]
with open("edited.png", 'wb') as f:
    f.write(base64.b64decode(img_data))
print("编辑后的图片已保存至 edited.png")

​

Node.js

import fs from "fs";

const API_KEY = "sk-your-api-key";
const imageB64 = fs.readFileSync("input.jpg").toString("base64");

const response = await fetch(
  "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      contents: [{
        parts: [
          { text: "请把背景模糊化，突出前景的人物" },
          { inlineData: { mimeType: "image/jpeg", data: imageB64 } }
        ]
      }],
      generationConfig: {
        responseModalities: ["IMAGE"],
        imageConfig: { aspectRatio: "16:9", imageSize: "2K" }
      }
    })
  }
);

const data = await response.json();
const imgBase64 = data.candidates[0].content.parts[0].inlineData.data;
fs.writeFileSync("edited.png", Buffer.from(imgBase64, "base64"));

​

cURL

# 注意：需要先将图片转为 base64 字符串
# IMAGE_B64=$(base64 -i input.jpg | tr -d '\n')

curl -X POST "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {"text": "请把背景模糊化，突出前景的人物"},
        {"inlineData": {"mimeType": "image/jpeg", "data": "'"$IMAGE_B64"'"}}
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
    }
  }'

​

多图编辑示例

把多张图作为输入合成或对比时，只用一个 text part（编辑指令），后面追加多个 inlineData part（每张图一个）。

​

Python（多图）

import requests
import base64

API_KEY = "sk-your-api-key"

def to_b64(path):
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode()

# 准备多张图（这里以 2 张为例，最多可上传多张）
images = ["person1.png", "person2.png"]
parts = [{"text": "把这两张图里的人物合成到同一个办公室场景中，做着搞怪表情"}]
for path in images:
    parts.append({"inlineData": {"mimeType": "image/png", "data": to_b64(path)}})

response = requests.post(
    "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={
        "contents": [{"parts": parts}],
        "generationConfig": {
            "responseModalities": ["TEXT", "IMAGE"],
            "imageConfig": {"aspectRatio": "5:4", "imageSize": "2K"}
        }
    },
    timeout=300
).json()

img_data = response["candidates"][0]["content"]["parts"][0]["inlineData"]["data"]
with open("merged.png", "wb") as f:
    f.write(base64.b64decode(img_data))

​

cURL（多图，对齐谷歌官方格式）

curl -X POST "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {"text": "An office group photo of these people, they are making funny faces."},
        {"inlineData": {"mimeType": "image/png", "data": "<BASE64_DATA_IMG_1>"}},
        {"inlineData": {"mimeType": "image/png", "data": "<BASE64_DATA_IMG_2>"}},
        {"inlineData": {"mimeType": "image/png", "data": "<BASE64_DATA_IMG_3>"}}
      ]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "5:4", "imageSize": "2K"}
    }
  }'

​

参数说明速查

参数	类型	必填	说明
contents[].parts	array	是	由「1 个 text part + N 个 inlineData part」组成。每个 part 只能含 text 或 inlineData 之一，不可同时出现
contents[].parts[].text	string	是	编辑指令（建议只放在第一个 part 中）
contents[].parts[].inlineData.mimeType	string	是	image/jpeg 或 image/png
contents[].parts[].inlineData.data	string	是	图片的 Base64 编码（多图编辑时重复多个 inlineData part）
generationConfig.responseModalities	array	是	通常为 ["IMAGE"]
generationConfig.imageConfig.aspectRatio	string	否	14 种宽高比，默认 1:1
generationConfig.imageConfig.imageSize	string	否	512 / 1K / 2K / 4K，默认 1K
generationConfig.thinkingConfig.thinkingLevel	string	否	minimal（快速）/ High（深度推理）
generationConfig.thinkingConfig.includeThoughts	boolean	否	是否返回思维过程文本

​

多轮对话式编辑

Nano Banana 2（gemini-3.1-flash-image-preview）支持真正的对话式多轮编辑：把模型每一轮产出的图片，作为 role: "model" 的 inlineData 追加回 contents，再发下一条 user 指令。模型会基于完整对话历史继续修改并累积效果（例如先改沙发颜色、再加配饰，前一步的改动会保留）。

这与”逆向”图像模型不同：原生 Gemini 格式会真正读取对话历史里 model 角色的图片。要保持跨轮一致性、逐步精调，推荐用下面这种对话历史回填的写法。

import requests, base64

API_KEY = "sk-your-api-key"
URL = "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent"
H = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
CFG = {"responseModalities": ["IMAGE"], "imageConfig": {"aspectRatio": "1:1", "imageSize": "2K"}}

contents = []  # 全程维护同一个对话历史

def turn(instruction, save_to):
    contents.append({"role": "user", "parts": [{"text": instruction}]})
    data = requests.post(URL, headers=H,
                         json={"contents": contents, "generationConfig": CFG}, timeout=300).json()
    part = next(p for p in data["candidates"][0]["content"]["parts"] if "inlineData" in p)
    contents.append({"role": "model", "parts": [part]})   # 关键：把产出的图回填进历史
    with open(save_to, "wb") as f:
        f.write(base64.b64decode(part["inlineData"]["data"]))
    return part

turn("生成一只橙色的猫，坐在蓝色沙发上，简笔画风格", "step1.png")
turn("把沙发改成红色，猫和构图保持不变", "step2.png")       # 基于上一轮的图修改
turn("给猫戴一顶黄色小帽子，其它保持不变", "step3.png")       # 继续累积，红沙发会保留

从已有图片开始多轮：第一轮的 user 消息里放 inlineData（你自己的图）+ 指令即可编辑现有照片，之后每轮照样把模型产出回填进 contents。

两种多轮写法：

• 对话历史回填（上面，推荐）：contents 保留 user/model 交替历史，跨轮累积修改、画面更稳。
• 重新喂图（简化版）：每轮只发单条 user 消息（text + 上一张图的 inlineData），做单步编辑也可以，但不携带更早的上下文。

授权

Authorization · string · header · 必填

在 API易控制台获取的 API Key

请求体

application/json

contents · object[] · 必填

内容数组，包含编辑指令和待编辑的图片

Show child attributes

generationConfig · object · 必填

Show child attributes

响应

200

application/json

成功生成图片

candidates · object[]

生成结果数组

Show child attributes

usageMetadata · object

Show child attributes