Skip to main content
POST
Image Editing: Edit an existing image with text instructions
오른쪽의 대화형 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를 가장 작은 티어(1K)로 설정하십시오.
⚠️ parts 배열 구조(중요 — 다중 이미지 편집 시 필독)각 part은 text 또는 inlineData 중 하나여야 하며, 둘 다 포함해서는 안 됩니다. 이는 Google의 공식 gemini-nano-banana-2.1 규격과 일치합니다.올바른 형식: 하나의 텍스트 파트(지시 사항) + N개의 inlineData 파트(이미지당 하나):
잘못된 형식(각 파트에 text와 inlineData가 모두 포함됨 — 정의되지 않은 동작 발생):
🖼️ inlineData.data 필드 안내이 엔드포인트는 JSON 형식을 사용하므로(multipart 파일 업로드가 아님), Playground에서 로컬 파일을 직접 선택할 수 없습니다. 먼저 이미지를 Base64 문자열로 변환한 다음, data 입력란에 붙여넣어야 합니다.한 줄 명령어: 변환 + 클립보드에 복사:
실행 후 Playground의 data 필드에 Cmd+V / Ctrl+V로 붙여넣기만 하면 됩니다. 또한 mimeType를 일치하는 image/jpeg 또는 image/png로 설정해야 합니다.권장 사항: 긴 base64 문자열로 인한 브라우저 랙을 방지하려면 테스트 시 작은 이미지(< 200KB)를 사용하십시오. 이미지 편집 테스트를 자주 진행하는 경우, 아래의 코드 예제를 활용하여 로컬에서 실행하십시오.

코드 예제

Python

Node.js

cURL

다중 이미지 편집

여러 입력 이미지를 병합하거나 비교할 때는 단일 text 파트(지시 사항) 뒤에 여러 개의 inlineData 파트(이미지당 1개)를 사용합니다.

Python (다중 이미지)

cURL (다중 이미지, Google 공식 형식 반영)

파라미터 빠른 참조

멀티턴 대화형 편집

Nano Banana 2.1(gemini-nano-banana-2.1)은 진정한 대화형 멀티턴 편집을 지원합니다. 각 턴에서 생성된 이미지를 role: "model" inlineData 형태로 contents에 다시 추가한 후, 다음 사용자 지시를 전송하십시오. 모델은 전체 대화 기록을 기반으로 편집하며 변경 사항을 누적합니다(예: 먼저 소파 색상을 변경한 다음 액세서리를 추가하면 이전 변경 사항이 유지됩니다).
이는 역방향 이미지 모델과 다릅니다. 네이티브 Gemini 형식은 model 역할의 대화 기록 턴에서 이미지를 실제로 읽어들입니다. 턴 간 일관성과 단계별 정교화를 위해 아래의 히스토리 백필(history-backfill) 패턴을 사용하십시오.
기존 이미지에서 멀티턴 시작: 첫 번째 사용자 메시지에 inlineData(보유한 이미지)와 지시사항을 함께 넣어 기존 사진을 편집한 다음, 매 턴마다 모델 출력을 contents에 계속 백필하십시오.
두 가지 멀티턴 방식:
  • 히스토리 백필(위 방식, 권장): contents에서 사용자/모델 대화 기록을 번갈아 유지합니다. 더 우수한 일관성으로 여러 턴에 걸쳐 변경 사항을 누적합니다.
  • 재전송(더 단순함): 이전 컨텍스트를 유지하지 않고 단일 단계 편집을 위해 매 턴마다 단일 사용자 메시지(text + 이전 이미지의 inlineData)를 전송합니다.

인증

Authorization
string
header
필수

API Key obtained from APIYI Console

본문

application/json
contents
object[]
필수

Content array containing edit instructions and the image to edit

generationConfig
object
필수

응답

Successfully edited image

candidates
object[]

Generation results array

usageMetadata
object