Image Editing: Edit an existing image with text instructions
curl --request POST \
--url https://api.apiyi.com/v1beta/models/gemini-3-pro-image: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"
}
}
}
'import requests
url = "https://api.apiyi.com/v1beta/models/gemini-3-pro-image:generateContent"
payload = {
"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"
}
}
}
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: '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'}
}
})
};
fetch('https://api.apiyi.com/v1beta/models/gemini-3-pro-image: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-pro-image: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' => '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'
]
]
]),
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-pro-image:generateContent"
payload := strings.NewReader("{\n \"contents\": [\n {\n \"parts\": [\n {\n \"text\": \"Combine the people from these two images into one office scene, making funny faces\"\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-pro-image:generateContent")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"contents\": [\n {\n \"parts\": [\n {\n \"text\": \"Combine the people from these two images into one office scene, making funny faces\"\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-pro-image: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\": \"Combine the people from these two images into one office scene, making funny faces\"\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{
"candidates": [
{
"content": {
"parts": [
{
"inlineData": {
"mimeType": "image/png",
"data": "<string>"
}
}
]
},
"finishReason": "STOP"
}
],
"usageMetadata": {
"promptTokenCount": 10,
"candidatesTokenCount": 258
}
}Nano Banana Pro 이미지 생성
이미지 편집 API 참조
Nano Banana Pro 이미지 편집 API 참조 및 대화형 플레이그라운드 — 이미지와 지침을 제공하여 편집된 결과를 생성합니다.
POST
/
v1beta
/
models
/
gemini-3-pro-image:generateContent
Image Editing: Edit an existing image with text instructions
curl --request POST \
--url https://api.apiyi.com/v1beta/models/gemini-3-pro-image: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"
}
}
}
'import requests
url = "https://api.apiyi.com/v1beta/models/gemini-3-pro-image:generateContent"
payload = {
"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"
}
}
}
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: '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'}
}
})
};
fetch('https://api.apiyi.com/v1beta/models/gemini-3-pro-image: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-pro-image: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' => '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'
]
]
]),
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-pro-image:generateContent"
payload := strings.NewReader("{\n \"contents\": [\n {\n \"parts\": [\n {\n \"text\": \"Combine the people from these two images into one office scene, making funny faces\"\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-pro-image:generateContent")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"contents\": [\n {\n \"parts\": [\n {\n \"text\": \"Combine the people from these two images into one office scene, making funny faces\"\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-pro-image: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\": \"Combine the people from these two images into one office scene, making funny faces\"\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{
"candidates": [
{
"content": {
"parts": [
{
"inlineData": {
"mimeType": "image/png",
"data": "<string>"
}
}
]
},
"finishReason": "STOP"
}
],
"usageMetadata": {
"promptTokenCount": 10,
"candidatesTokenCount": 258
}
}오른쪽의 대화형 플레이그라운드에서는 드롭다운으로 매개변수를 선택할 수 있습니다. Authorization 필드에 API 키(형식:
Bearer sk-xxx)를 입력하면 클릭 한 번으로 테스트 요청을 보낼 수 있습니다.범위: 이 페이지는 이미지 편집을 위한 페이지입니다. 편집 지침과 함께 입력 이미지(base64 인코딩)를 제공해야 합니다. 텍스트만으로 새 이미지를 생성하려면 텍스트-이미지 엔드포인트를 사용하세요.
🖥️ 브라우저 플레이그라운드 제한 사항(중요)이 엔드포인트는 응답으로 base64 인코딩된 이미지(
inlineData.data, 일반적으로 수 MB)를 반환합니다. 브라우저 렌더링 제한으로 인해 응답이 도착한 후 오른쪽의 플레이그라운드에 请求时发生错误: unable to complete request가 표시될 수 있습니다. — 요청은 실제로 성공한 것입니다. 브라우저에서 이렇게 긴 base64 문자열을 렌더링할 수 없을 뿐입니다.권장 워크플로(초보자에게 적합):- 아래 Python / Node.js / cURL 샘플을 복사해 로컬에서 실행하세요. 코드는 응답을 자동으로
base64.b64decode처리하고 이미지를 파일로 저장합니다. - 브라우저 내 플레이그라운드를 반드시 사용해야 한다면 작은 참조 이미지(< 50KB)를 사용하고
imageSize을 가장 낮은 티어(예:1K)로 설정하세요.
⚠️ 잘못된 예(각 파트에
parts 배열 구조(중요 — 여러 이미지 편집 시 필독)각 part는 text 또는 inlineData 중 하나여야 하며, 둘 다여서는 안 됩니다. 이는 Google의 공식 gemini-3-pro-image 계약과 일치합니다.올바른 예: 텍스트 파트 하나(지침) + N개의 inlineData 파트(이미지당 하나):"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>"}}
]
}]
text와 inlineData가 모두 포함됨 — 정의되지 않은 동작을 일으킴):"contents": [{
"parts": [
{"inlineData": {...}, "text": "is this the prompt 1"},
{"inlineData": {...}, "text": "is this the prompt 2"}
]
}]
inlineData.data 필드 안내이 엔드포인트는 JSON 형식(multipart 파일 업로드가 아님)을 사용하므로 플레이그라운드에서 로컬 파일을 직접 선택할 수 없습니다. 먼저 이미지를 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
Cmd+V / Ctrl+V를 눌러 플레이그라운드의 data 필드에 붙여넣기만 하면 됩니다. 또한 mimeType를 해당 image/jpeg 또는 image/png로 설정해야 합니다.권장 사항: 긴 base64 문자열로 인해 브라우저가 느려지는 것을 방지하려면 테스트에 200KB 미만의 작은 이미지를 사용하세요. 이미지 편집 테스트를 자주 수행하는 경우 아래 코드 예제를 사용해 로컬에서 실행하세요.코드 예제
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-pro-image: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-pro-image: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-pro-image: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"}
}
}'
여러 이미지 편집
여러 입력 이미지를 병합하거나 비교할 때는 단일text 부분(지침) 다음에 여러 inlineData 부분(이미지당 하나)을 사용합니다.
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()
# 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-pro-image: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 (여러 이미지, Google의 공식 형식과 동일)
curl -X POST "https://api.apiyi.com/v1beta/models/gemini-3-pro-image: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 | Yes | 1개의 text part + N개의 inlineData part로 구성됩니다. 각 part에는 text 또는 inlineData 중 하나만 포함되며, 둘 다 포함되지는 않습니다 |
contents[].parts[].text | string | Yes | 편집 지시문입니다(첫 번째 part에만 넣습니다) |
contents[].parts[].inlineData.mimeType | string | Yes | image/jpeg 또는 image/png |
contents[].parts[].inlineData.data | string | Yes | Base64로 인코딩된 이미지입니다(다중 이미지 편집의 경우 이미지마다 inlineData part를 하나씩 반복합니다) |
generationConfig.responseModalities | array | Yes | 일반적으로 ["IMAGE"]입니다 |
generationConfig.imageConfig.aspectRatio | string | No | 10개의 비율이며, 기본값은 1:1입니다 |
generationConfig.imageConfig.imageSize | string | No | 1K / 2K / 4K이며, 기본값은 1K입니다 |
Nano Banana Pro는 멀티 이미지 편집을 지원합니다. 멀티 이미지 합성 및 스타일 전이와 같은 고급 기능을 위해 여러 이미지를 편집 지시문과 함께 입력할 수 있습니다.
인증
API Key from APIYI Console
본문
application/json
이 페이지가 도움이 되었나요?