Google Nano Banana 2.1(2026년 10월에 공개된 Nano Banana 2의 업그레이드) 기반의 이미지 생성 API(비동기 작업)입니다. 텍스트 기반 생성은 prompt만 있으면 되고, 편집은 참고 이미지를 image 또는 images(URL, data:, base64)에 넣거나 /v1/images/edits를 호출합니다. 제출하면 바로 작업 id(HTTP 202)가 반환되며 GET /v1/images/jobs/{id}를 폴링해 이미지를 받습니다. 1:1, 3:4, 2:3, 9:16, 4:3, 3:2, 16:9 등의 비율과 1K / 2K / 4K를 지원하며, 4:1, 1:4, 8:1, 1:8 같은 가로·세로로 긴 화면도 바로 생성됩니다. 장당 과금이며 실패한 요청은 과금하지 않습니다.
플레이그라운드에서 사용해 보기 →빠른 시작
세 단계면 됩니다: 작업 제출 → 결과 조회 → 이미지 링크 받기. YOUR_API_KEY를 내 키로 바꾸면 아래 명령을 그대로 실행할 수 있습니다.
curl https://nezhagate.com/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "nano-banana-2.1", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "16:9", "resolution": "2K"}'{
"id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
"object": "image.generation.job",
"status": "queued",
"created": 1791281500,
"model": "nano-banana-2.1"
}curl https://nezhagate.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \ -H "Authorization: Bearer YOUR_API_KEY"
{
"id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
"object": "image.generation.job",
"status": "succeeded",
"created": 1791281500,
"model": "nano-banana-2.1",
"data": [
{"url": "https://img.nezhagate.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
],
"usage": {"images": 1, "resolution": "2K", "model": "nano-banana-2.1"}
}3단계 · data[0].url이 이미지(PNG)입니다. 60일 동안 보관되므로 오래 쓰려면 내 저장소에 내려받아 두세요.
import time
import requests
BASE = "https://nezhagate.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
# 1. 제출
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
"model": "nano-banana-2.1",
"prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field",
"size": "16:9",
"resolution": "2K",
}).json()
if "error" in job:
raise SystemExit(job["error"]["message"])
# 2. 끝날 때까지 3초마다 조회
while job["status"] not in ("succeeded", "failed"):
time.sleep(3)
job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()
# 3. 이미지 내려받기
if job["status"] == "succeeded":
url = job["data"][0]["url"]
with open("nano-banana-2.1.png", "wb") as f:
f.write(requests.get(url).content)
print("saved", url)
else:
print("failed:", job["error"]["message"])인증
Authorization: Bearer YOUR_API_KEY Content-Type: application/json
콘솔에서 API 키를 만들면 시작할 수 있습니다.
요청 본문
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| model | string | 예 | 모델 ID. 여기서는 nano-banana-2.1입니다. |
| prompt | string | 예 | 만들 이미지를 설명하는 텍스트 프롬프트. |
| size | string | 아니오 | 출력 화면 비율. 비율을 넘기는 방식을 권장합니다 — 1:1, 3:4, 2:3, 9:16, 4:3, 3:2, 16:9 — 이렇게 하면 모델이 그 비율로 네이티브 렌더링해 피사체가 잘리지 않습니다. 픽셀 크기(예: 1024x1024, 1024x1536, 1536x1024)도 받습니다. 기본값은 1:1(정사각형)입니다. |
| resolution | string | 아니오 | 해상도 등급: 1K(기본값) / 2K / 4K이며 등급별로 과금합니다. size의 비율과 함께 씁니다(예: {"size": "16:9", "resolution": "2K"}). 등급별 실제 픽셀 크기는 아래 「비율, 해상도와 출력 크기」에 있습니다. size에 픽셀 크기(예: 2048x1152)를 쓰면 긴 변으로 등급이 정해집니다. |
| n | integer | 아니오 | 항상 1: 작업 하나에 1장을 만듭니다. 더 큰 값을 보내도 1장만 나오고 1장 값만 과금됩니다. 여러 장이 필요하면 작업을 여러 개 동시에 제출하세요. |
| image | string | 아니오 | 이미지-투-이미지: 참조 이미지를 공개 URL, data: URI, 또는 원시 base64로 넣습니다. 값이 있으면 선택한 크기 / 비율에서 원본의 정체성을 유지하는 진짜 이미지-투-이미지가 실행되며, /v1/images/edits 호출과 동일합니다. |
| images | array | 아니오 | 참조 이미지 여러 장, 최대 8장(더 보내면 앞의 8장만 사용): 문자열 배열 또는 {"image_url": "..."} 객체 배열이며, 각각 공개 이미지 URL, data: URI, base64 중 하나로 장당 16MB까지입니다. 보내면 이미지-투-이미지로 실행되며 /v1/images/edits와 같습니다. 1장이면 위의 image 필드도 쓸 수 있습니다. |
요청 예시
# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "nano-banana-2.1", "prompt": "a serene ink-wash poster, lots of negative space", "size": "16:9", "resolution": "2K"}'
# 2) poll until status=succeeded
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'응답
{
"id": "img_3f9a...c2",
"object": "image.generation.job",
"status": "queued",
"model": "nano-banana-2.1"
}가격
이미지 1장 단위로 과금하며, 가격은 해상도 등급으로만 정해지고 비율이나 텍스트-투-이미지 / 이미지-투-이미지 여부와는 무관합니다. 제출할 때 등급 가격을 예치하고, 작업이 실패하면 전액 환불합니다. 1크레딧 = $0.005.
| 등급 | 장당 크레딧 | 장당 가격(USD) |
|---|---|---|
| 1K | 3 | $0.015 |
| 2K | 5 | $0.025 |
| 4K | 8 | $0.04 |
작업 하나는 항상 1장을 만듭니다. n을 얼마로 보내도 1장이 나오고 1장 값만 과금됩니다. 여러 장이 필요하면 작업을 여러 개 동시에 제출하세요(계정당 동시에 50장까지 생성).
비율, 해상도와 출력 크기
size에 비율을, resolution에 등급(기본 1K, 2K, 4K)을 넣습니다. 모델은 선택한 비율로 바로 그리며, 정사각형을 그린 뒤 잘라내지 않습니다. 전달되는 이미지는 긴 변이 1024 / 2048 / 4096픽셀이고 다른 변은 비율에 따라 정해집니다. 자주 쓰는 비율:
| 비율 | 1K | 2K | 4K |
|---|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 | 4096x4096 |
| 3:4 | 768x1024 | 1536x2048 | 3072x4096 |
| 2:3 | 683x1024 | 1365x2048 | 2731x4096 |
| 9:16 | 576x1024 | 1152x2048 | 2304x4096 |
| 4:3 | 1024x768 | 2048x1536 | 4096x3072 |
| 3:2 | 1024x683 | 2048x1365 | 4096x2731 |
| 16:9 | 1024x576 | 2048x1152 | 4096x2304 |
이 7가지 외에 4:5, 5:4, 21:9, 1:4, 4:1, 1:8, 8:1도 네이티브로 그립니다(긴 변 규칙은 같음). 그 밖의 비율은 가장 가까운 가로형 · 세로형 · 정사각형으로 그린 뒤 원하는 비율로 잘라내므로 화면 일부가 잘릴 수 있습니다.
size에 픽셀 크기(예: 1536x1024)를 쓸 수도 있으며, 이 경우 적은 크기 그대로 전달하고 등급은 긴 변으로 정합니다(1536 이하 1K, 2048 이하 2K, 그보다 크면 4K). resolution은 1K / 2K / 4K(대소문자 무관)만 받으며, 다른 값은 무시되고 등급은 size로 정해집니다(기본 1K). size를 생략하면 1:1 정사각형이 나옵니다.
이미지-투-이미지와 참조 이미지
- image(1장) 또는 images(여러 장, 최대 8장. 더 보내면 앞의 8장만 사용)를 보내면 이미지-투-이미지로 실행됩니다. 무엇을 어떻게 바꿀지는 프롬프트에 적으세요. POST /v1/images/edits도 같은 매개변수로 쓸 수 있습니다.
- 참조 이미지는 공개 이미지 URL(http / https), data: URI 또는 일반 base64로 보낼 수 있으며, 장당 16MB까지, JPEG · PNG · WebP 등 일반적인 형식을 지원합니다.
- URL은 이미지 파일 자체를 내려받을 수 있어야 합니다(웹 페이지, 로그인이 필요한 주소, 핫링크가 막힌 주소는 안 됨). 읽을 수 없는 참조 이미지는 제출할 때 400과 이유를 돌려주며, 작업은 만들어지지 않고 과금도 없습니다.
- 출력 비율은 참조 이미지가 아니라 size로 정해집니다. 원본 비율을 유지하려면 size를 원본과 같은 비율로 지정하세요.
- 참조 이미지는 당사가 대신 호스팅하며 7일 동안 보관합니다.
curl https://nezhagate.com/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "nano-banana-2.1", "prompt": "Keep the people, change the background to a beach at night with warm string lights", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'작업 상태와 응답 필드
GET /v1/images/jobs/{id}는 항상 id, object(image.generation.job), status, created(Unix 초), model을 반환하며, 나머지 필드는 상태에 따라 붙습니다.
| status | 의미 | 추가되는 필드 |
|---|---|---|
| queued | 대기 중 | queue_position(앞에 있는 작업 수), eta_seconds(예상 대기 시간, 초, 참고용) |
| processing | 생성 중 | — |
| succeeded | 완료 | data[].url(이미지 링크, 당사 이미지 호스트에 60일 보관), usage.images(전달 장수), usage.resolution(과금 등급) |
| failed | 실패(제출 시 예치한 금액은 전액 환불됨) | error.message, error.type, error.code |
2~3초마다 조회하는 것을 권장합니다. 한 계정은 동시에 최대 50장까지 생성하며, 그 이상의 작업은 제출 순서대로 대기합니다. 15분이 지나도 시작되지 않은 작업은 자동으로 실패 처리되고 전액 환불됩니다. 작업 기록은 3일 동안 보관되며, 그 뒤에는 작업 ID로 조회하면 404가 돌아오지만 이미지 링크는 60일 동안 유효합니다. 작업은 제출한 계정만 조회할 수 있습니다.
생성 시간
제출부터 결과까지 걸리는 일반적인 시간입니다(참고용). 이미지-투-이미지는 몇 초에서 십여 초 더 걸리며, 다른 회선에서 다시 실행된 작업은 1~2분이 걸릴 수 있습니다.
| 등급 | 일반적인 소요 시간 |
|---|---|
| 1K | 25–40초 |
| 2K | 25–50초 |
| 4K | 35–80초 |
오류와 환불
모든 오류는 {"error": {"message", "type", "code", "param"}}의 같은 구조입니다. code로 분기하세요.
제출할 때 돌아오는 오류(작업이 만들어지지 않고 과금도 없음)
| HTTP | code | 원인 | 조치 |
|---|---|---|---|
| 400 | missing_prompt | prompt가 비어 있음 | prompt를 넣으세요 |
| 400 | model_not_found | model ID가 틀렸거나 지금은 사용할 수 없음 | ID를 확인하세요(사용 가능한 모델은 /v1/models) |
| 400 | invalid_request | 참조 이미지를 읽을 수 없음(끊긴 링크, 이미지가 아님, 16MB 초과 등). 어느 이미지인지와 이유는 message에 표시 | 이미지 직접 링크를 쓰거나 base64로 보내세요 |
| 401 | invalid_api_key | 키가 틀렸거나 삭제 또는 비활성화됨 | 콘솔에서 키를 확인하세요 |
| 402 | insufficient_quota | 잔액이 이 작업의 예치 금액보다 적음 | 충전 후 다시 시도하세요 |
| 429 | rate_limit_exceeded | 이 키에 설정한 분당 요청 한도를 넘음 | 빈도를 낮추거나 콘솔에서 키 한도를 올리세요 |
| 503 | model_maintenance | 모델 점검 중 | 잠시 후 다시 시도하세요(상태 페이지 참고) |
| 503 | service_unavailable | 당사 측의 일시적인 오류(참조 이미지 저장 실패 등) | 잠시 후 다시 시도하세요 |
실패한 작업(접수 후 status가 failed로 끝남, 예치 금액은 전액 환불)
| 상황 | 보이는 내용 | 조치 |
|---|---|---|
| 프롬프트나 참조 이미지가 Google 안전 심사를 통과하지 못함 | error.message에 Content blocked 등의 심사 메시지 | 프롬프트를 고치거나 참조 이미지를 바꾸세요. 그대로 다시 제출하면 대개 다시 거절됩니다 |
| 생성 회선의 일시적인 장애나 시간 초과(먼저 다른 회선에서 자동으로 다시 시도하고, 모두 실패할 때만 실패를 돌려줌) | error.code가 upstream_error, upstream_timeout 등이며 이유는 message에 표시 | 다시 제출하세요 |
| 15분 동안 시작되지 못함 | error.message에 그 내용 | 잠시 후 다시 제출하세요 |
폴링 대신 웹훅 사용
운영 환경에서는 제출할 때 callback_url을 넣는 것을 권장합니다. 작업이 끝나면(성공이든 실패든) 조회 API와 같은 JSON을 그 URL로 image.completed 또는 image.failed 이벤트로 POST하며, 출처를 검증할 수 있는 서명 헤더도 함께 보냅니다. 「설정 → Webhook」에서 계정 전체에 쓸 URL을 지정할 수도 있습니다. 웹훅 문서
curl https://nezhagate.com/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "nano-banana-2.1", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'