Google Nano Banana 2 Lite(Gemini 3.1 Flash Lite Image) 기반의 이미지 생성 API(비동기 작업)입니다. Nano Banana 제품군에서 가장 빠르고 저렴한 모델입니다. 텍스트 기반 생성은 prompt만 있으면 되고, 편집은 참고 이미지를 image 또는 images(URL, data:, base64)에 넣거나 /v1/images/edits를 호출합니다. 제출하면 바로 작업 id(HTTP 202)가 반환되며 GET /v1/images/jobs/{id}를 폴링해 이미지를 받습니다. 1K로만 출력하며 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 21:9, 4:1, 1:4, 8:1, 1:8 14가지 비율을 지원합니다. 2K / 4K를 요청하면 제출 시 거절되고 과금되지 않습니다. 장당 과금이며 실패한 요청은 과금하지 않습니다.
플레이그라운드에서 사용해 보기 →빠른 시작
세 단계면 됩니다: 작업 제출 → 결과 조회 → 이미지 링크 받기. YOUR_API_KEY를 내 키로 바꾸면 아래 명령을 그대로 실행할 수 있습니다.
curl https://kovapi.com/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "nano-banana-2-lite", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "16:9", "resolution": "1K"}'{
"id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
"object": "image.generation.job",
"status": "queued",
"created": 1791281500,
"model": "nano-banana-2-lite"
}curl https://kovapi.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-lite",
"data": [
{"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.jpg"}
],
"usage": {"images": 1, "resolution": "1K", "model": "nano-banana-2-lite"}
}3단계 · data[0].url이 이미지(업스트림 원본, JPEG 형식)입니다. 7일 동안 보관되므로 오래 쓰려면 내 저장소에 내려받아 두세요.
import time
import requests
BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
# 1. 제출
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
"model": "nano-banana-2-lite",
"prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field",
"size": "16:9",
"resolution": "1K",
}).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-lite.jpg", "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-lite입니다. |
| 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만 지원합니다(기본값이라 생략 가능). resolution에 2K / 4K를 지정하면 제출 시 400 unsupported_resolution을 반환하며 과금되지 않습니다. size에 픽셀 크기를 쓸 때, Lite의 14가지 1K 기본 크기(예: 2928x352, 1584x672)는 모두 1K로 계산합니다. |
| thinking_level | string | 아니오 | 생각 수준. nano-banana-2-lite만 지원: minimal(기본값, 생략 가능) 또는 high. high는 그리기 전에 먼저 생각해서 3~6초 더 걸리고 가격은 같습니다. 복잡한 구도, 정확한 개수, 글자 배치에 시도해 볼 만합니다. 자체 테스트에서는 결과 차이가 뚜렷하지 않았습니다. 다른 모델에 high를 보내면 제출 시 400을 반환하며 과금하지 않습니다. |
| 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://kovapi.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "nano-banana-2-lite", "prompt": "a serene ink-wash poster, lots of negative space", "size": "16:9", "resolution": "1K"}'
# 2) poll until status=succeeded
curl https://kovapi.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-lite"
}가격
이미지 1장 단위로 과금하며, 가격은 해상도 등급으로만 정해지고 비율이나 텍스트-투-이미지 / 이미지-투-이미지 여부와는 무관합니다. 제출할 때 등급 가격을 예치하고, 작업이 실패하면 전액 환불합니다. 1크레딧 = $0.005.
| 등급 | 장당 크레딧 | 장당 가격(USD) |
|---|---|---|
| 1K | 2 | $0.01 |
작업 하나는 항상 1장을 만듭니다. n을 얼마로 보내도 1장이 나오고 1장 값만 과금됩니다. 여러 장이 필요하면 작업을 여러 개 동시에 제출하세요(계정당 동시에 50장까지 생성).
비율, 해상도와 출력 크기
size에 비율을 넣고, resolution은 생략해도 됩니다(등급은 1K뿐). 모델이 선택한 비율로 바로 그리며, 상위 원본 이미지를 자르거나 크기를 바꾸지 않고 그대로 전달합니다. 비율별 픽셀 크기는 고정이며 아래 표와 같습니다:
| 비율 | 1K |
|---|---|
| 1:1 | 1024x1024 |
| 16:9 | 1376x768 |
| 9:16 | 768x1376 |
| 4:3 | 1200x896 |
| 3:4 | 896x1200 |
| 3:2 | 1264x848 |
| 2:3 | 848x1264 |
| 4:5 | 928x1152 |
| 5:4 | 1152x928 |
| 21:9 | 1584x672 |
| 1:4 | 512x2064 |
| 4:1 | 2064x512 |
| 1:8 | 352x2928 |
| 8:1 | 2928x352 |
표에 있는 비율만 지원합니다(size에 픽셀 크기를 쓰면 1.5% 이내로 가장 가까운 비율로 처리합니다). 그 밖의 비율은 바로 실패하며 과금되지 않습니다. 그린 뒤 잘라내는 일은 없습니다.
size에 픽셀 크기를 쓸 수도 있습니다. 표에 있는 크기(예: 2928x352, 1584x672)는 1K로 그리고, 그 밖의 픽셀 크기는 가장 가까운 비율(차이 1.5% 이내)의 1K 기본 크기로 그립니다. 긴 변이 1536을 넘으면 2K / 4K로 보고 제출 시 거절합니다. resolution은 1K만 가능하며, 2K / 4K를 지정하면 제출 시 400 unsupported_resolution을 반환하고 작업을 만들지 않으며 과금도 없습니다. 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://kovapi.com/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "nano-banana-2-lite", "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": "1K"}'작업 상태와 응답 필드
GET /v1/images/jobs/{id}는 항상 id, object(image.generation.job), status, created(Unix 초), model을 반환하며, 나머지 필드는 상태에 따라 붙습니다.
| status | 의미 | 추가되는 필드 |
|---|---|---|
| queued | 대기 중 | queue_position(앞에 있는 작업 수), eta_seconds(예상 대기 시간, 초, 참고용) |
| processing | 생성 중 | — |
| succeeded | 완료 | data[].url(이미지 링크, 당사 이미지 호스트에 7일 보관), usage.images(전달 장수), usage.resolution(과금 등급) |
| failed | 실패(제출 시 예치한 금액은 전액 환불됨) | error.message, error.type, error.code |
2~3초마다 조회하는 것을 권장합니다. 한 계정은 동시에 최대 50장까지 생성하며, 그 이상의 작업은 제출 순서대로 대기합니다. 15분이 지나도 시작되지 않은 작업은 자동으로 실패 처리되고 전액 환불됩니다. 작업 기록은 3일 동안 보관되며, 그 뒤에는 작업 ID로 조회하면 404가 돌아오지만 이미지 링크는 7일 동안 유효합니다. 작업은 제출한 계정만 조회할 수 있습니다.
생성 시간
제출부터 결과까지 걸리는 일반적인 시간입니다(참고용). 이미지-투-이미지는 몇 초에서 십여 초 더 걸리며, 자동으로 다시 시도된 작업은 1~2분이 걸릴 수 있습니다.
| 등급 | 일반적인 소요 시간 |
|---|---|
| 1K | 5–15초 |
오류와 환불
모든 오류는 {"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://kovapi.com/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "nano-banana-2-lite", "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"}'