Nano Banana API 가이드: TokenLab에서의 이미지 생성 및 편집

Nano Banana API는 TokenLab에서 세 가지 유료 모델 ID를 제공하며, 가장 저렴한 모델은 중간 모델보다 이미지당 비용이 약 절반 수준입니다. 비용과 관련된 실수는 모델 선택보다는 잘못된 엔드포인트로 편집 요청을 보내거나, 이미 작업이 생성된 create 호출을 재시도하는 경우에 주로 발생합니다. 이 가이드에서는 정확한 ID, 정상 작동하는 텍스트-이미지 변환 호출, 참조 이미지 호출, 비동기 폴링, 예상 오류 및 요금 책정 방식을 다룹니다. 가격 및 필드 목록은 2026년 10월 3일 기준으로 작성되었으므로, 배포 전 다시 한번 확인하시기 바랍니다.

핵심 요약

• 정확한 ID를 전송하세요: nano-banana-2, nano-banana-2-lite 또는 nano-banana-pro. 표시 이름(Display name)은 요청 별칭이 아닙니다.
• Nano Banana의 참조 이미지 작업은 operation: "image-to-image" 및 image_urls를 포함하여 POST /v1/images/generations로 보내야 합니다. /v1/images/edits나 /v1/chat/completions로 보내지 마세요.
• 2026년 10월 3일 기준 기본 가격은 lite, standard, pro ID별로 이미지당 각각 $0.0168, $0.0335, $0.067입니다. 각 모델마다 가격 범위가 있으므로 Usage에서 정확한 티어를 확인하세요.
• task_id, status: "pending" 또는 poll_url이 포함된 응답을 받았다면, completed 또는 failed 상태가 될 때까지 GET /v1/tasks/{id}를 폴링해야 합니다.
• 상태 조회는 작업이 실패했더라도 HTTP 200을 반환합니다. HTTP 코드가 아닌 작업의 status 필드를 기준으로 분기 처리하세요.
• 최종 요금은 복사된 가격표가 아닌, Usage 및 billing_transaction_id에서 확인할 수 있습니다.

Nano Banana API 모델, 가격 단위 및 용도

이 가이드의 초기 초안을 현재 문서와 비교했을 때 세 가지 문제를 발견했습니다. 가격 정보가 없는 모델이 나열되어 있었고, Nano Banana 편집 요청을 chat completions를 통해 보냈으며, 이미지 가이드에서 사용하지 않는 필터로 카탈로그를 조회했습니다. 아래 표는 첫 번째 문제를 수정하며, 이후 섹션에서 나머지 두 문제를 해결합니다.

모델 ID	최적 용도	가격 단위	TokenLab 가격 (USD)	출처, 관찰 시점
nano-banana-2	aspect_ratio 및 resolution(1k, 2k, 4k)을 사용하는 텍스트-이미지 및 이미지-이미지 변환. 2026-02-26 출시.	per_image	요청당 $0.0335. 범위 $0.0225 ~ $0.0755.	라이브 모델 API, 2026-10-03
nano-banana-2-lite	가장 저렴한 텍스트-이미지 및 이미지-이미지 변환. 확인된 가격 항목은 1k 티어 기준.	per_image	요청당 $0.0168. 최소 및 최대 모두 $0.0168.	라이브 모델 API, 2026-10-03
nano-banana-pro	aspect_ratio 및 resolution을 사용하는 텍스트-이미지, 이미지-이미지 변환 및 이미지 편집.	per_image	요청당 $0.067. 범위 $0.067 ~ $0.12.	라이브 모델 API, 2026-10-03
nano-banana	aspect_ratio만 사용하는 텍스트-이미지 변환. 공개된 resolution 선택 옵션 없음.	확인되지 않음	모델 페이지 또는 가격 책정 엔드포인트 확인	카탈로그, 2026-10-02; 이미지 생성 문서, 2026-10-03

위의 모든 가격은 is_lock_price: true가 적용되어 있으며 2026-10-02T16:53:30.068Z에 업데이트되었습니다. 모델 선택 전 다음 세 가지 세부 사항을 고려하세요:

• 해상도 티어에 따라 가격이 변동됩니다. 라이브 API는 nano-banana-2와 nano-banana-pro에 대한 가격 범위를 보여주지만, 각 티어가 어떤 해상도에 매핑되는지는 명시되어 있지 않습니다. 1k가 기본 가격이라고 가정하지 마세요. 해당 모델의 가격 항목을 읽어보시기 바랍니다.
• 텍스트 출력에는 별도의 토큰 가격이 있습니다. nano-banana-2와 nano-banana-pro 모두 native-gemini-text-output 항목을 포함합니다. 이는 outputModality가 text일 때 적용됩니다. nano-banana-2는 입력 0.25, 출력 1.5이며, nano-banana-pro는 입력 1, 출력 6입니다. 단위는 per_token입니다. 예산을 책정하기 전에 GET /v1/models/:model/pricing에서 규모를 확인하세요.
• Lite는 허용된 요청 형식을 나열하지 않습니다. nano-banana-2-lite의 라이브 기록에는 "나열되지 않음"으로 표시되어 있습니다. 이를 기반으로 빌드하기 전에 세부 정보를 확인하세요.

대략적인 예산을 위해 기본 가격에 볼륨을 곱합니다. 이는 기본 가격 기준 추정치이며 견적은 아닙니다:

• nano-banana-2-lite로 100개 이미지 생성: 100 × $0.0168 = $1.68.
• nano-banana-2로 100개 이미지 생성: 100 × $0.0335 = $3.35.
• nano-banana-pro로 100개 이미지 생성: 100 × $0.067 = $6.70.

더 높은 해상도 티어는 이 수치를 상승시킵니다.

현재 이미지 모델을 직접 나열하려면 이미지 생성 가이드에서 사용하는 엔드포인트를 호출하세요. 이전 초안에서는 category=image를 사용했으나, 가이드에는 해당 내용이 문서화되어 있지 않습니다.

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

특정 모델의 작업, 가격 및 수명 주기에 대해서는 Get a Model을 사용하세요. TokenLab 모델 디렉토리를 탐색할 수도 있습니다.

Nano Banana API로 텍스트-이미지 요청 보내기

TokenLab 대시보드에서 API 키를 생성하고 내보냅니다:

export TOKENLAB_API_KEY="your-tokenlab-api-key"

항상 model을 전송하세요. 이미지 생성 참조에 따르면 이미지 API는 기본값을 선택하지 않습니다. 모델이 누락되면 param: "model"과 함께 400 오류가 반환됩니다.

이 요청은 Google 이미지 제품군에 대해 문서화된 필드만 사용합니다. nano-banana-2가 1k, 2k, 4k를 문서화하고 있으므로 resolution을 1k로 유지했습니다.

curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  --max-time 120 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A minimalist ceramic vase on a natural wooden table, studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "response_format": "url"
  }'

--max-time 120 플래그는 문서와 일치합니다. 고해상도 요청은 1분 이상 걸릴 수 있으므로 클라이언트 타임아웃을 최소 120초로 설정하세요. 문서는 size가 Google 이미지 제품군에 대한 호환성 별칭이라고 설명하지만, aspect_ratio를 직접 사용할 것을 권장합니다.

동기식 성공 시 완성된 이미지가 인라인으로 반환됩니다. 아래 자리 표시자 값은 문서화된 형태만 보여줍니다:

{
  "created": 1700000000,
  "data": [
    { "url": "https://example.com/generated-image.png" }
  ]
}

다음 순서로 읽으세요:

1. 본문에 task_id, status: "pending" 또는 poll_url이 있다면 이미지가 아닌 작업(task)입니다. 폴링 섹션으로 이동하세요.
2. 그렇지 않으면 data[0].url을 읽으세요. response_format: "b64_json"인 경우 data[0].b64_json을 읽으세요.
3. created는 Unix 타임스탬프입니다. revised_prompt는 모델이 반환할 때만 나타나므로 필수로 요구하지 마세요.
4. 이미지 URL, 자체 작업 ID, 모델 및 응답 헤더의 request_id를 저장하세요.

생성된 이미지 URL은 미디어 사본으로 30일 동안 보관될 수 있습니다. 각 항목의 상태와 expires_at은 media_retention.items를 확인하세요. 보류 중이거나 실패한 사본은 보장이 되지 않으므로 더 오래 필요하다면 파일을 자체 스토리지로 복사하세요. 데이터 보존 가이드에 자세한 내용이 있습니다.

참조 URL을 사용한 이미지 편집

깔끔한 스튜디오 배경에서 동일한 제품 사진을 원하는 카탈로그 팀을 가정해 봅시다. /v1/images/edits를 사용하고 싶겠지만, 문서는 이를 배제합니다. Nano Banana 참조 이미지 요청은 operation: "image-to-image"를 사용하여 /v1/images/generations에서 노출됩니다. /v1/images/edits는 올바른 경로가 아닙니다.

이 요청은 이미지 생성 가이드에서 가져온 것이며, 모델로 nano-banana-2를 사용합니다:

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "operation": "image-to-image",
    "prompt": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

이 형태에서 따르는 규칙:

• 문서화된 참조 필드를 정확히 전송하세요. JSON에서 image_url, image_urls 또는 reference_image_urls를 사용하세요. 최상위 images[]나 file_id를 보내지 마세요. 이는 편집 흐름에 속하며 이 엔드포인트에서는 거부됩니다.
• 공개 URL을 사용하세요. 포함된 자격 증명, 프래그먼트, 사설 네트워크 호스트가 없는 http 또는 https여야 합니다. 처리가 시작되기 전에 만료될 수 있는 서명된 URL은 피하세요.
• 개인 소스에는 멀티파트(multipart)를 사용하세요. 문서는 개인적이거나 헤더 보호가 필요한 소스를 위해 멀티파트 image 파일을 제공합니다.
• resolution을 모델에 맞추세요. 문서는 nano-banana-pro가 이를 포함할 수 있고 nano-banana-edit는 생략해야 한다고 말합니다. 또한 nano-banana-edit를 참조 이미지 모델로 명시하지만, 해당 ID는 2026-10-02에 가져온 카탈로그에는 없습니다. 사용하기 전에 /v1/models를 통해 ID를 확인하세요.

원본 문서의 chat-completions 편집 예제는 삭제되었습니다. 라이브 기록에는 nano-banana-2 및 nano-banana-pro에 대해 허용된 형식으로 gemini_generate_content가 나열되어 있습니다. 증거 자료에는 chat-completions 이미지 편집 경로가 문서화되어 있지 않습니다.

마스크 기반 인페인팅 및 strength와 같은 매개변수는 증거 자료에서 Nano Banana에 대해 문서화되어 있지 않습니다. 전송하기 전에 GET /v1/models/{model}을 검사하세요.

이미지 요청이 작업이 되는 경우 및 폴링 방법

이미지 생성 호출은 동기식 또는 비동기식이며, 응답을 통해 확인할 수 있습니다. 비동기 작업 가이드는 트리거 필드인 task_id, status: "pending" 또는 poll_url을 나열합니다. 이 중 하나라도 나타나면 data[] 배열은 비어 있고 작업이 진행 중인 것입니다.

증거 자료는 async: true 요청 플래그를 gpt-image-2 및 공식 FLUX/BFL 이미지 모델에 대해서만 문서화합니다. Nano Banana ID에 대해서는 문서화되어 있지 않으므로 Nano Banana 요청에 추가하지 마세요. 작업 응답이 돌아오면 처리하고, 비동기 동작이 필요한 경우 모델 세부 정보를 확인하세요.

느린 응답 후 생성 호출을 다시 보내는 브라우저 새로고침을 가정해 봅시다. 이제 두 번의 생성 비용을 지불하게 됩니다. 문서는 대부분의 중복 생성이 이러한 재시도에서 발생한다고 말합니다. 다음 순서를 따르세요:

1. ID를 즉시 저장하세요. id 또는 task_id, poll_url, 모델, 엔드포인트 및 자체 작업 ID를 저장하세요. id와 task_id는 같은 값입니다.
2. URL을 폴링하세요. poll_url이 있으면 사용하세요. 그렇지 않으면 고정 경로를 호출하세요:

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

1. 5~10초마다 폴링하세요. 가이드는 긴 미디어 작업에 충분한 시간이라고 말합니다.
2. 상태를 파악하세요. pending, processing, completed, failed가 있습니다. 취소된 작업은 cancelled: true와 함께 failed로 표시됩니다.
3. 종료 상태에서 중지하세요. completed 상태에서 data[].url을 읽으세요. 비동기 이미지 결과는 URL뿐이며 b64_json은 없습니다. failed 상태에서는 error와 error_details를 읽으세요.
4. 타임아웃을 안전하게 처리하세요. 생성 호출이 응답을 보기 전에 타임아웃되면 request_id를 확인하고 재시도 전에 작업을 찾으세요. 작업 ID를 저장했다면 폴링을 재개하세요. 상태 폴링이 실패하면 백오프(backoff)를 사용하여 해당 폴링을 재시도하고 다시 생성하지 마세요.

상태 조회는 실패한 작업에 대해서도 HTTP 200을 반환합니다. 실패한 작업에는 status, type, code, message, param, retryable이 포함된 error_details가 포함될 수 있습니다. 예를 들어 param: "size"와 함께 error_details.status: 400이 나오면 요청 수정이 필요하다는 의미입니다. 폴링 자체가 실패했다는 의미는 아닙니다. 실패한 생성을 재시도하면 새 작업이 생성되고 새 비용이 발생할 수 있습니다.

예상되는 오류 및 대처 방법

오류는 HTTP 상태와 code로 처리하고, message로 처리하지 마세요. 오류 처리 가이드에 따르면 메시지는 예고 없이 변경될 수 있습니다. Chat Completions와 Responses는 OpenAI 스타일의 error 객체를 사용하지만, Gemini와 Anthropic 형식은 자체 형태를 유지합니다. 모든 TokenLab API에 하나의 파서를 공유하지 마세요.

상태 / 코드	가능한 원인	대처 방법
400, param: "model"	명시적 모델 없음	model을 전송하세요. /v1/models?recommended_for=image로 ID를 나열하세요.
400 지원되지 않는 필드, 또는 unsupported_parameter	모델이 문서화하지 않은 필드(예: 지원하지 않는 모델의 resolution)	필드를 제거하거나 모델을 변경하세요. 변경 없이 반복하지 마세요.
400 참조 이미지	잘못된 엔드포인트, 또는 비공개/만료된 URL	image_urls와 함께 /v1/images/generations를 사용하세요. 공개되고 안정적인 URL을 사용하세요.
401 invalid_api_key 또는 expired_api_key	키 누락, 취소 또는 만료	키를 교체하세요.
402 insufficient_balance 또는 quota_exceeded	잔액 부족 또는 키 한도 초과	자금을 추가하거나 키 한도를 높이거나 저렴한 모델을 선택하세요.
403 model_not_allowed	키가 해당 모델을 사용할 수 없음	키의 모델 목록을 업데이트하세요.
404 model_not_found	알 수 없거나 사용할 수 없는 ID	/v1/models를 읽고 현재 ID를 사용하세요.
413 payload_too_large	요청 또는 파일이 너무 큼	입력 크기를 줄이세요.
429 rate_limit_exceeded	윈도우 내 요청 과다	Retry-After를 기다린 후 재시도하세요.
500–504, all_channels_failed	서비스 또는 공급 문제	retryable이 true일 때만 재시도하세요. retry_after를 준수하고 시도 횟수를 제한하세요.

503 all_channels_failed가 항상 서비스 중단을 의미하지는 않습니다. retryable이 false이고 retry_after가 누락된 경우, 선택한 Delivery 티어에 공급이 없는 것입니다. 요청을 반복해도 도움이 되지 않으므로 먼저 GET /v1/models를 확인하세요.

작업 폴링 자체의 실패:

• 404 async_task_not_found: 작업이 만료되었거나 사라짐. 저장된 task_id와 poll_url을 확인하세요.
• 403 task_not_owned: 작업이 다른 워크스페이스에 속함. API 키가 어느 워크스페이스에 속하는지 확인하세요.
• 미디어 URL이 없는 완료된 작업: 실패로 간주하세요. ID를 보관하고 지원팀에 문의하세요.

지원팀에 문의할 때는 request_id, task_id, billing_transaction_id(있는 경우), 엔드포인트, 모델, 시간, 필드 이름을 보내세요. 키, 개인 미디어 또는 서명된 URL은 절대 보내지 마세요.

이미지 요청 요금 책정 방식

세 가지 유료 Nano Banana ID 모두 per_image 단위를 사용하므로, 주요 요금은 모델의 per_request 가격입니다. 결제 가이드는 이에 관한 규칙을 추가합니다:

• 하나의 결과, 하나의 요금. 완료된 각 요청은 해당 결과를 생성한 전달 옵션에 대해 한 번 청구됩니다. TokenLab Verified는 TokenLab 공개 가격을 사용합니다. Official은 공식 가격 계층을 사용합니다. Auto는 Verified를 먼저 시도한 후 Official을 시도합니다.
• 티어가 최종 금액을 결정합니다. 라이브 가격 범위(nano-banana-2의 경우 $0.0225~$0.0755, nano-banana-pro의 경우 $0.067~$0.12)는 단일 고정 가격이 모든 요청을 커버하지 않음을 보여줍니다. 해상도 티어가 주요 요인일 가능성이 높지만, 모델의 가격 항목에서 확인하세요.
• 작업이 먼저 예약합니다. 비동기 작업은 수락될 때 예상 비용을 예약할 수 있습니다. 완료된 작업은 한 번 청구되며, 실패한 작업은 보류 중인 금액을 해제하거나 환불합니다. 결제 가이드는 실패한 작업은 청구되지 않는다고 명시합니다.
• 대시(-)는 무료가 아닙니다. 모델 페이지에서 TokenLab 가격 열의 대시는 현재 Verified 제안을 사용할 수 없음을 의미합니다.

요금을 확인하려면 다음 위치를 사용하세요:

1. 현재 가격은 GET /v1/models/:model/pricing 또는 Pricing API를 사용하세요.
2. 콘솔은 유료 생성을 확인하기 전 최대 추정치를 보여줍니다.
3. 모델별 최종 요금은 Usage를 확인하세요.
4. 응답 또는 작업의 billing_transaction_id와 X-Billing-Transaction-ID 헤더를 확인하세요. 스트리밍 및 일부 네이티브 형식은 헤더에서만 노출될 수 있습니다.

작업 완료 후 Usage에 최종 요금이나 해제된 금액이 표시되지 않으면 Request ID와 작업 ID를 support@tokenlab.sh로 보내세요. 이 기사의 가격을 코드에 복사하지 마세요. 결제 가이드는 애플리케이션이 비용을 표시하거나 비교해야 할 때 현재 가격을 읽으라고 명시합니다.

FAQ

이미지-이미지 요청에는 어떤 Nano Banana 모델 ID를 보내야 하나요?

라이브 기록에는 nano-banana-2, nano-banana-2-lite, nano-banana-pro에 대해 image-to-image가 나열되어 있습니다. 문서는 nano-banana-edit도 언급하지만, 2026-10-02에 가져온 카탈로그에는 없습니다. operation: "image-to-image" 및 image_urls와 함께 ID를 /v1/images/generations로 보내세요. 증거 자료에 품질 비교가 없으므로 자신의 이미지로 작은 테스트를 실행해 보세요.

이미지 요청이 이미지 대신 task_id를 반환한 이유는 무엇인가요?

생성 호출이 비동기 작업으로 실행되었습니다. 응답에서 task_id, status: "pending" 또는 poll_url을 찾으세요. 해당 필드를 저장한 후 상태가 completed 또는 failed가 될 때까지 5~10초마다 poll_url 또는 GET /v1/tasks/{id}를 폴링하세요. 기다리는 동안 두 번째 생성 요청을 보내지 마세요.

Nano Banana 모델에서 base64 출력을 얻을 수 있나요?

response_format 필드는 url 또는 b64_json을 허용하며, 동기식 요청은 data[].b64_json을 반환할 수 있습니다. 비동기 이미지 결과는 요청한 형식과 관계없이 URL만 제공됩니다. 필드는 모델마다 다르므로 선택한 모델의 세부 정보를 확인하여 b64_json을 허용하는지 확인하세요.

실패한 이미지 작업도 청구되나요?

결제 가이드에 따르면 실패한 작업은 청구되지 않으며, 보류 중인 예약은 해제되거나 환불됩니다. 실패한 생성을 재시도하면 새 작업이 생성되고 새 비용이 발생할 수 있습니다. billing_transaction_id와 task_id를 사용하여 Usage에서 결과를 확인하세요.

TokenLab 대시보드에서 키를 생성하고, 위 텍스트-이미지 요청을 nano-banana-2-lite로 보낸 후 Usage에서 요금을 확인하세요.