Image Editing API Reference - API易文档中心

Image Editing: Edit an existing image with text instructions

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": "Combine the people from these two images into one office scene, making funny faces"
        },
        {
          "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"
    }
  }
}
'

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

POST

v1beta

models

gemini-3.1-flash-image-preview:generateContent

Image Editing: Edit an existing image with text instructions

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": "Combine the people from these two images into one office scene, making funny faces"
        },
        {
          "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"
    }
  }
}
'

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

The interactive Playground on the right supports dropdown selection for parameters. Enter your API Key in the Authorization field (format: Bearer sk-xxx) to send test requests with one click.

Scope: This page is for image editing. You must provide an input image (base64-encoded) along with edit instructions. To generate a new image from text only, use the Text-to-Image endpoint.

🖥️ Browser Playground limitation (important)This endpoint returns a base64-encoded image (inlineData.data, typically several MB) in the response. Due to browser rendering limits, the Playground on the right may show 请求时发生错误: unable to complete request after the response arrives — the request actually succeeded; the browser just can’t render such a long base64 string.Recommended workflow (beginner-friendly):

Copy the Python / Node.js / cURL sample below and run it locally. The code automatically base64.b64decodes the response and writes the image to a file.
If you must use the in-browser Playground, use a tiny reference image (< 50KB) and set imageSize to the smallest tier (e.g. 512 / 1K).

⚠️ parts array structure (important — read this for multi-image edits)Each part must be either a text or an inlineData, never both. This matches Google’s official gemini-3.1-flash-image-preview contract.Correct: one text part (the instruction) + N inlineData parts (one per image):

"contents": [{
  "parts": [
    {"text": "Combine the people from these two images into one office scene"},
    {"inlineData": {"mimeType": "image/png", "data": "<BASE64_DATA_IMG_1>"}},
    {"inlineData": {"mimeType": "image/png", "data": "<BASE64_DATA_IMG_2>"}}
  ]
}]

Incorrect (each part contains both text and inlineData — produces undefined behavior):

"contents": [{
  "parts": [
    {"inlineData": {...}, "text": "is this the prompt 1"},
    {"inlineData": {...}, "text": "is this the prompt 2"}
  ]
}]

🖼️ About the inlineData.data fieldThis endpoint uses JSON format (not multipart file upload), so the Playground cannot directly select local files. You need to convert your image to a Base64 string first, then paste it into the data input.One-line command: convert + copy to clipboard:

# 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

After running, just Cmd+V / Ctrl+V paste into the data field in the Playground. Also remember to set mimeType to the matching image/jpeg or image/png.Recommendation: Use small images (< 200KB) for testing to avoid browser lag from long base64 strings. For frequent image editing tests, use the code examples below to run locally instead.

Code Examples

Python

import requests
import base64

API_KEY = "sk-your-api-key"

# Read the image to edit
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": "Please blur the background to highlight the person in the foreground"},
                {"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 image saved to 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: "Please blur the background to highlight the person in the foreground" },
          { 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

# Note: convert image to base64 first
# 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": "Please blur the background to highlight the person in the foreground"},
        {"inlineData": {"mimeType": "image/jpeg", "data": "'"$IMAGE_B64"'"}}
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
    }
  }'

Multi-Image Editing

When merging or comparing several input images, use a single text part (the instruction) followed by multiple inlineData parts (one per image).

Python (multi-image)

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()

# Prepare multiple images (2 here as an example)
images = ["person1.png", "person2.png"]
parts = [{"text": "Combine the people from these images into one office scene, making funny faces"}]
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 (multi-image, mirrors Google’s official format)

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

Parameter Quick Reference

Parameter	Type	Required	Description
`contents[].parts`	array	Yes	Composed of 1 text part + N inlineData parts. Each part contains either `text` or `inlineData` — never both
`contents[].parts[].text`	string	Yes	Edit instruction (place it in the first part only)
`contents[].parts[].inlineData.mimeType`	string	Yes	`image/jpeg` or `image/png`
`contents[].parts[].inlineData.data`	string	Yes	Base64-encoded image (repeat one inlineData part per image for multi-image edits)
`generationConfig.responseModalities`	array	Yes	Usually `["IMAGE"]`
`generationConfig.imageConfig.aspectRatio`	string	No	14 ratios, default `1:1`
`generationConfig.imageConfig.imageSize`	string	No	`512` / `1K` / `2K` / `4K`, default `1K`
`generationConfig.thinkingConfig.thinkingLevel`	string	No	`minimal` (fast) / `High` (deep reasoning)
`generationConfig.thinkingConfig.includeThoughts`	boolean	No	Return thinking process text

Nano Banana 2 supports multi-turn conversational editing: feed the previous output image as the next inlineData input along with a new edit instruction to iteratively refine the result.

Authorizations

Authorization

string

header

required

API Key obtained from APIYI Console

Body

application/json

contents

object[]

required

Content array containing edit instructions and the image to edit

Show child attributes

generationConfig

object

required

Show child attributes

Response

Successfully edited image

candidates

object[]

Generation results array

Show child attributes

usageMetadata

object

Show child attributes

Text-to-Image API Reference Nano Banana Pro Image Generation

Documentation Index

​Code Examples

​Python

​Node.js

​cURL

​Multi-Image Editing

​Python (multi-image)

​cURL (multi-image, mirrors Google’s official format)

​Parameter Quick Reference

Authorizations

Body

Response

Code Examples

Python

Node.js

cURL

Multi-Image Editing

Python (multi-image)

cURL (multi-image, mirrors Google’s official format)

Parameter Quick Reference