Skip to main content
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
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt

Use this file to discover all available pages before exploring further.

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

ParameterTypeRequiredDescription
contents[].partsarrayYesComposed of 1 text part + N inlineData parts. Each part contains either text or inlineData — never both
contents[].parts[].textstringYesEdit instruction (place it in the first part only)
contents[].parts[].inlineData.mimeTypestringYesimage/jpeg or image/png
contents[].parts[].inlineData.datastringYesBase64-encoded image (repeat one inlineData part per image for multi-image edits)
generationConfig.responseModalitiesarrayYesUsually ["IMAGE"]
generationConfig.imageConfig.aspectRatiostringNo14 ratios, default 1:1
generationConfig.imageConfig.imageSizestringNo512 / 1K / 2K / 4K, default 1K
generationConfig.thinkingConfig.thinkingLevelstringNominimal (fast) / High (deep reasoning)
generationConfig.thinkingConfig.includeThoughtsbooleanNoReturn 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

​
generationConfig
object
required

Response

Successfully edited image

​
candidates
object[]

Generation results array

​
usageMetadata
object