메인 콘텐츠로 건너뛰기
POST
Image Editing: Edit an existing image with text instructions
오른쪽의 대화형 플레이그라운드에서는 드롭다운으로 매개변수를 선택할 수 있습니다. Authorization 필드에 API Key를 입력하고(형식: 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-nano-banana-2.1 계약과 일치합니다.올바른 예: 텍스트 파트 하나(지침) + inlineData 파트 N개(이미지당 하나):
잘못된 예(각 파트에 text과 inlineData이 모두 포함됨 — 정의되지 않은 동작이 발생함):
🖼️ inlineData.data 필드 정보이 엔드포인트는 JSON 형식(multipart 파일 업로드가 아님)을 사용하므로 플레이그라운드에서 로컬 파일을 직접 선택할 수 없습니다. 먼저 이미지를 Base64 문자열로 변환한 다음 data 입력란에 붙여 넣어야 합니다.한 줄 명령어: 변환 + 클립보드에 복사:
실행한 후 data 필드에 간단히 Cmd+V / Ctrl+V하여 붙여 넣으십시오. 또한 mimeType을 일치하는 image/jpeg 또는 image/png로 설정해야 합니다.권장 사항: 긴 base64 문자열로 인한 브라우저 지연을 방지하려면 테스트에 작은 이미지(< 200KB)를 사용하십시오. 이미지 편집 테스트를 자주 수행한다면 아래의 코드 예제를 사용하여 대신 로컬에서 실행하십시오.

코드 예시

파이썬

Node.js

cURL

여러 이미지 편집

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

Python (여러 이미지)

cURL (여러 이미지, Google의 공식 형식과 동일)

매개변수 빠른 참조

다중 턴 대화형 편집

Nano Banana 2.1 (gemini-nano-banana-2.1)은 진정한 대화형 다중 턴 편집을 지원합니다. 각 턴에서 생성된 이미지를 **role: "model" inlineData**로 contents에 다시 추가한 다음, 다음 사용자 지시를 전송합니다. 모델은 전체 대화 기록을 기반으로 편집하며 변경 사항을 누적합니다(예: 먼저 소파 색상을 변경한 다음 액세서리를 추가하면 이전 변경 사항이 유지됩니다).
이는 역방향 이미지 모델과 다릅니다. 기본 Gemini 형식은 실제로 model-역할 기록 턴에서 이미지를 읽습니다. 턴 간 일관성과 단계별 개선을 위해 아래의 기록 백필 패턴을 사용합니다.
기존 이미지에서 다중 턴 시작: 첫 번째 사용자 메시지에 inlineData (사용자 이미지)와 지시를 함께 넣어 기존 사진을 편집한 다음, 각 턴에서 모델 출력을 contents에 계속 백필합니다.
다중 턴 방식 2가지:
  • 기록 백필(위 방식, 권장): 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