이미지 생성
텍스트 프롬프트와 참조 이미지로 AI 이미지를 동기 또는 비동기 작업으로 생성하고, 크레딧 비용을 미리 예상합니다.
이미지 생성 API는 텍스트 프롬프트(선택적으로 참조 이미지의 안내를 받아)를 한 장 이상의 이미지로 바꿔 줍니다. 호출 방식은 세 가지입니다.
- 동기 —
POST /v1/images/generation은 이미지가 준비될 때까지 블로킹하며, 응답 본문에 모델의 원본 출력(base64 이미지 데이터)을 반환합니다. - 비동기 —
POST /v1/images/generation/async는taskId를 즉시 반환하고, 결과(호스팅된 이미지 URL)는GET /v1/images/generation/tasks/{taskId}를 폴링(polling)해서 가져옵니다. - 먼저 예상 —
POST /v1/images/generation/estimate-credits는 아무것도 소비하지 않고 크레딧 비용과 계정이 생성 가능한 상태인지를 반환합니다.
모든 엔드포인트는 API key(Authorization: Bearer $LISTENHUB_API_KEY)가 필요합니다. key는
listenhub.ai/settings/api-keys 에서 만듭니다.
두 생성 엔드포인트는 데이터를 반환하는 방식이 다릅니다. 동기 엔드포인트는 모델의 원본 JSON을
본문에 그대로 반환합니다(표준 { code, message, data } 엔벨로프로 감싸지 않습니다). 비동기와
예상 엔드포인트는 표준 래핑 엔벨로프를 사용합니다. 응답 형식을 참고하세요.
이미지 생성(동기)
POST /v1/images/generation
텍스트 프롬프트로 이미지를 생성하고 준비될 때까지 블로킹합니다. 스타일이나 내용을 유도하려면 참조 이미지를 선택적으로 제공하세요. 응답 본문은 모델의 원본 출력 — base64 이미지 데이터를 담은 JSON입니다.
기본 생성
curl -X POST "https://api.marswave.ai/openapi/v1/images/generation" \
-H "Authorization: Bearer $LISTENHUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "google",
"model": "gemini-3-pro-image",
"prompt": "A serene mountain landscape at sunset with a reflective lake",
"imageConfig": {
"aspectRatio": "16:9",
"imageSize": "2K"
}
}'const response = await fetch(
'https://api.marswave.ai/openapi/v1/images/generation',
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
provider: 'google',
model: 'gemini-3-pro-image',
prompt: 'A serene mountain landscape at sunset with a reflective lake',
imageConfig: {
aspectRatio: '16:9',
imageSize: '2K',
},
}),
},
)
const data = await response.json()
// data.candidates[0].content.parts[0].inlineData holds the generated imageimport os
import requests
response = requests.post(
'https://api.marswave.ai/openapi/v1/images/generation',
headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
json={
'provider': 'google',
'model': 'gemini-3-pro-image',
'prompt': 'A serene mountain landscape at sunset with a reflective lake',
'imageConfig': {
'aspectRatio': '16:9',
'imageSize': '2K',
},
},
)
data = response.json()
# data['candidates'][0]['content']['parts'][0]['inlineData'] holds the generated imageGPT-Image-2를 쓰려면 provider 를 "openai", model 을 "gpt-image-2" 로 설정하세요. 요청과
응답 형식은 동일하며 provider, model, imageConfig 만 다릅니다.
프로바이더와 모델 매트릭스를 참고하세요.
참조 이미지를 사용한 생성
출력을 유도하려면 참조 이미지를 제공하세요. 참조 이미지는 URL(fileData) 또는 base64로 인코딩된
인라인 데이터(inlineData) 중 하나입니다. 한 요청에서 두 형식을 섞어 쓸 수 있습니다.
이미지 URL 사용
curl -X POST "https://api.marswave.ai/openapi/v1/images/generation" \
-H "Authorization: Bearer $LISTENHUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "google",
"model": "gemini-3-pro-image",
"prompt": "Transform this scene into a watercolor painting style",
"referenceImages": [
{
"fileData": {
"fileUri": "https://example.com/my-photo.jpg",
"mimeType": "image/jpeg"
}
}
],
"imageConfig": {
"aspectRatio": "1:1",
"imageSize": "2K"
}
}'const response = await fetch(
'https://api.marswave.ai/openapi/v1/images/generation',
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
provider: 'google',
model: 'gemini-3-pro-image',
prompt: 'Transform this scene into a watercolor painting style',
referenceImages: [
{
fileData: {
fileUri: 'https://example.com/my-photo.jpg',
mimeType: 'image/jpeg',
},
},
],
imageConfig: {
aspectRatio: '1:1',
imageSize: '2K',
},
}),
},
)
const data = await response.json()import os
import requests
response = requests.post(
'https://api.marswave.ai/openapi/v1/images/generation',
headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
json={
'provider': 'google',
'model': 'gemini-3-pro-image',
'prompt': 'Transform this scene into a watercolor painting style',
'referenceImages': [
{
'fileData': {
'fileUri': 'https://example.com/my-photo.jpg',
'mimeType': 'image/jpeg',
}
}
],
'imageConfig': {
'aspectRatio': '1:1',
'imageSize': '2K',
},
},
)
data = response.json()base64 인라인 데이터 사용
curl -X POST "https://api.marswave.ai/openapi/v1/images/generation" \
-H "Authorization: Bearer $LISTENHUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "google",
"model": "gemini-3-pro-image",
"prompt": "Create a cartoon version of this portrait",
"referenceImages": [
{
"inlineData": {
"data": "<BASE64_ENCODED_IMAGE>",
"mimeType": "image/png"
}
}
]
}'import { readFileSync } from 'fs'
const imageBase64 = readFileSync('reference.png').toString('base64')
const response = await fetch(
'https://api.marswave.ai/openapi/v1/images/generation',
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
provider: 'google',
model: 'gemini-3-pro-image',
prompt: 'Create a cartoon version of this portrait',
referenceImages: [
{
inlineData: {
data: imageBase64,
mimeType: 'image/png',
},
},
],
}),
},
)
const data = await response.json()import os
import base64
import requests
with open('reference.png', 'rb') as f:
image_base64 = base64.b64encode(f.read()).decode('utf-8')
response = requests.post(
'https://api.marswave.ai/openapi/v1/images/generation',
headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
json={
'provider': 'google',
'model': 'gemini-3-pro-image',
'prompt': 'Create a cartoon version of this portrait',
'referenceImages': [
{
'inlineData': {
'data': image_base64,
'mimeType': 'image/png',
}
}
],
},
)
data = response.json()요청 파라미터
아래 파라미터는 POST /v1/images/generation, POST /v1/images/generation/async,
POST /v1/images/generation/estimate-credits 에 적용됩니다 — 이 세 엔드포인트는 하나의 요청
스키마를 공유합니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
provider | string | 예¹ | 모델 프로바이더: google, openai, bytedance |
model | string | 아니요 | 모델 이름. 기본값은 gpt-image-2. 프로바이더와 모델 매트릭스 참고 |
prompt | string | 예² | 생성할 이미지에 대한 텍스트 설명 |
referenceImages | array | 아니요 | 생성을 유도할 참조 이미지. 참조 이미지 상한 참고 |
referenceImages[].fileData | object | 아니요 | URL로 제공하는 참조 이미지 |
referenceImages[].fileData.fileUri | string | 예 | 이미지 URL — scheme은 http, https, gs 중 하나여야 함 |
referenceImages[].fileData.mimeType | string | 예 | MIME 타입: image/png, image/jpeg, image/webp, image/heic, image/heif |
referenceImages[].inlineData | object | 아니요 | base64로 인코딩된 데이터로 제공하는 참조 이미지 |
referenceImages[].inlineData.data | string | 예 | base64로 인코딩된 이미지 데이터 |
referenceImages[].inlineData.mimeType | string | 예 | MIME 타입: image/png, image/jpeg, image/webp, image/heic, image/heif |
imageConfig | object | 아니요 | 이미지 출력 설정. 기본값은 { "imageSize": "2K" } |
imageConfig.imageSize | string | 아니요 | 출력 해상도: 1K, 2K(기본값), 4K |
imageConfig.aspectRatio | string | 아니요 | 화면비. 기본값은 1:1. 화면비 참고 |
imageConfig.quality | string | 아니요 | 렌더링 품질: low, medium, high. GPT-Image-2에 적용되며, 생략하면 모델이 알아서 결정 |
¹ provider 는 두 생성 엔드포인트에서는 필수이고 estimate-credits 에서는 선택입니다.
² prompt 는 두 생성 엔드포인트에서 필수입니다. estimate-credits 에서는 비워 두거나 생략할 수
있습니다(입력 토큰 예상치에만 영향을 줍니다).
referenceImages 의 각 항목은 fileData 또는 inlineData 중 정확히 하나만 포함해야 하며, 둘 다
넣을 수는 없습니다.
프로바이더와 모델 매트릭스
provider 는 벤더를, model 은 구체적인 모델을 선택합니다. 기본 모델은 gpt-image-2 입니다.
provider | model | 비고 |
|---|---|---|
google | gemini-3-pro-image | 더 높은 품질과 더 풍부한 디테일. NanoBanana Pro |
google | gemini-3.1-flash-image | 더 빠른 생성. 1:4 / 4:1 / 1:8 / 8:1 비율을 추가로 지원 |
openai | gpt-image-2 | 프롬프트 준수력이 강함. 참조 이미지 최대 4장. aspectRatio 는 선택 |
bytedance | seedream-5-0-pro | 정밀 편집 지원(좌표 / 색상 코드를 prompt 에 작성). 참조 이미지 최대 10장. 1K / 2K 만 지원 |
구버전 preview 모델 ID gemini-3-pro-image-preview 와 gemini-3.1-flash-image-preview 는 입력으로
여전히 허용되며 위의 GA ID로 정규화됩니다. 새로 연동한다면 GA ID를 보내세요.
화면비
imageConfig.aspectRatio 의 기본값은 1:1 입니다. 스키마가 허용하는 비율은 다음과 같습니다.
| 비율 | 설명 |
|---|---|
1:1 | 정사각형 |
2:3 | 세로형 |
3:2 | 가로형 |
3:4 | 세로형 |
4:3 | 가로형 |
9:16 | 세로 / 모바일 |
16:9 | 와이드스크린 |
21:9 | 울트라와이드 |
1:4 | Flash 전용 |
4:1 | Flash 전용 |
1:8 | Flash 전용 |
8:1 | Flash 전용 |
1:4, 4:1, 1:8, 8:1 은 gemini-3.1-flash-image 와 seedream-5-0-pro 만 허용합니다.
GPT-Image-2는 표준 8종 비율(1:1, 2:3, 3:2, 3:4, 4:3, 9:16, 16:9, 21:9)을 지원하며,
aspectRatio 를 생략하면 자동으로 선택합니다. 선택한 모델이 지원하지 않는 비율은 400 을
반환합니다.
이미지 크기
imageConfig.imageSize 는 1K, 2K(기본값), 4K 를 받습니다. 크기가 클수록 크레딧을 더 소비하며,
GPT-Image-2의 경우 4K(및 high 품질)에는 유효한 유료 구독이 필요합니다. Seedream 5.0 Pro는
1K 와 2K 만 지원하며, 4K 는 400 을 반환합니다. 크레딧 비용을 하드코딩하지 말고 정확한
수치는 크레딧 예상을 호출해 가져오세요.
참조 이미지 상한
| 모델 | 참조 이미지 최대 수 |
|---|---|
gemini-3-pro-image | 14 |
gemini-3.1-flash-image | 14 |
gpt-image-2 | 4 |
seedream-5-0-pro | 10 |
스키마는 referenceImages 를 전체 14개로 제한합니다. GPT-Image-2는 4개라는 더 엄격한 상한을,
Seedream 5.0 Pro는 10개 상한을 적용하며 — 초과하면 400 을 반환합니다. fileData 와 inlineData
모두 허용되는 MIME 타입은 image/png, image/jpeg, image/webp, image/heic, image/heif
입니다.
Seedream 5.0 Pro 정밀 편집
Seedream 5.0 Pro는 정밀 편집을 지원합니다. 이미지 전체를 다시 생성하는 대신 특정 영역만 바꾸는 방식입니다.
별도의 편집 엔드포인트도, mask나 region 파라미터도 없습니다 — 편집은 동일한 생성 엔드포인트를
사용하며, 원본 이미지는 referenceImages 에 넣고 "어디를 어떻게 바꿀지"는 prompt 에 씁니다.
모델은 이미지 왼쪽 위 모서리를 원점으로 하는 절대 픽셀 좌표와 업계 표준 색상 코드를 그대로
읽습니다.
{
"provider": "bytedance",
"model": "seedream-5-0-pro",
"prompt": "Treating the top-left corner as the coordinate origin, change the content inside top-left:(376,363) bottom-right:(701,638) to green, and leave everything else unchanged",
"referenceImages": [
{
"fileData": {
"fileUri": "https://assets.listenhub.ai/your-source-image.png",
"mimeType": "image/png"
}
}
],
"imageConfig": { "imageSize": "2K", "aspectRatio": "1:1" }
}제품에 박스 선택, 올가미, 화살표 같은 시각적 편집 제스처가 있다면, 자체 프런트엔드에서 좌표
문자열로 변환하거나 주석을 참조 이미지에 직접 그려 넣은 뒤 prompt 에 작성하세요. 서버는 프롬프트를
그대로 전달할 뿐 좌표를 파싱하지 않습니다. aspectRatio 는 원본 이미지의 실제 비율과 일치시키세요.
어긋나면 모델이 한 영역만 편집하는 대신 이미지 전체를 재구성할 수 있습니다.
크레딧 예상
POST /v1/images/generation/estimate-credits
크레딧을 쓰거나 모델을 호출하지 않고, 주어진 설정의 크레딧 비용과 계정이 그것을 생성할 수 있는지를
반환합니다. 결제 전에 가격을 보여 주거나 4K / high 요청에 구독이 필요한지 확인할 때 사용하세요.
생성 엔드포인트와 동일한 본문을 받으며, 여기서는 provider 와 prompt 가 선택입니다.
curl -X POST "https://api.marswave.ai/openapi/v1/images/generation/estimate-credits" \
-H "Authorization: Bearer $LISTENHUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"imageConfig": {
"imageSize": "2K",
"aspectRatio": "1:1",
"quality": "medium"
}
}'const response = await fetch(
'https://api.marswave.ai/openapi/v1/images/generation/estimate-credits',
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'gpt-image-2',
imageConfig: { imageSize: '2K', aspectRatio: '1:1', quality: 'medium' },
}),
},
)
const { data } = await response.json()
console.log(data.credits, data.canGenerate)import os
import requests
response = requests.post(
'https://api.marswave.ai/openapi/v1/images/generation/estimate-credits',
headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
json={
'model': 'gpt-image-2',
'imageConfig': {'imageSize': '2K', 'aspectRatio': '1:1', 'quality': 'medium'},
},
)
data = response.json()['data']
print(data['credits'], data['canGenerate'])예상 응답
표준 엔벨로프로 감싸집니다. data 객체는 다음과 같습니다.
| 필드 | 타입 | 설명 |
|---|---|---|
model | string | 예상에 사용된 정규화된 GA 모델 ID |
imageSize | string | 확정된 출력 크기 |
aspectRatio | string | 확정된 화면비(모델이 자동 선택하는 경우 없음) |
quality | string | 확정된 품질(해당 없는 경우 없음) |
pixels | object | 확정된 경우 { "width": number, "height": number, "size": "WxH" } |
credits | number | 이 설정이 소비하게 될 크레딧 |
canGenerate | boolean | 계정에 충분한 유효 크레딧 잔액이 있는지 여부 |
requiresSubscription | boolean | 설정에 유효한 유료 플랜이 필요하면 true(예: 4K, high) |
pricing | object | 가격 메타데이터: pricingVersion, mode(token-estimate/fixed) |
warnings | array | 안내 문자열. 예: reference_image_input_tokens_not_included |
{
"code": 0,
"message": "",
"data": {
"model": "gpt-image-2",
"imageSize": "2K",
"aspectRatio": "1:1",
"quality": "medium",
"pixels": { "width": 2048, "height": 2048, "size": "2048x2048" },
"credits": 6,
"canGenerate": true,
"requiresSubscription": false,
"pricing": { "pricingVersion": "...", "mode": "token-estimate" },
"warnings": []
}
}비동기 생성
오래 걸리거나 고해상도인 작업은 요청을 열어 두는 대신 작업을 제출하고 결과를 폴링하세요.
비동기 작업 생성
POST /v1/images/generation/async
요청 본문은 동기 엔드포인트와 같습니다. taskId 와 함께 202 를 즉시 반환하고, 생성은 백그라운드에서
진행되며 결과 이미지는 호스팅 URL로 저장됩니다.
curl -X POST "https://api.marswave.ai/openapi/v1/images/generation/async" \
-H "Authorization: Bearer $LISTENHUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "google",
"model": "gemini-3-pro-image",
"prompt": "An astronaut riding a horse on Mars, photorealistic",
"imageConfig": { "imageSize": "4K", "aspectRatio": "16:9" }
}'const res = await fetch(
'https://api.marswave.ai/openapi/v1/images/generation/async',
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
provider: 'google',
model: 'gemini-3-pro-image',
prompt: 'An astronaut riding a horse on Mars, photorealistic',
imageConfig: { imageSize: '4K', aspectRatio: '16:9' },
}),
},
)
const { data } = await res.json()
const taskId = data.taskIdimport os
import requests
res = requests.post(
'https://api.marswave.ai/openapi/v1/images/generation/async',
headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
json={
'provider': 'google',
'model': 'gemini-3-pro-image',
'prompt': 'An astronaut riding a horse on Mars, photorealistic',
'imageConfig': {'imageSize': '4K', 'aspectRatio': '16:9'},
},
)
task_id = res.json()['data']['taskId']응답(202):
{
"code": 0,
"message": "",
"data": { "taskId": "65f0...", "status": "pending" }
}작업 조회
GET /v1/images/generation/tasks/{taskId}
단일 작업의 상태와 결과를 폴링합니다. status 는 pending, generating, success, fail 중
하나입니다. 성공하면 images 에 호스팅된 결과 URL이 담깁니다.
curl "https://api.marswave.ai/openapi/v1/images/generation/tasks/65f0abc..." \
-H "Authorization: Bearer $LISTENHUB_API_KEY"{
"code": 0,
"message": "",
"data": {
"taskId": "65f0abc...",
"status": "success",
"images": [
{ "url": "https://.../0.png", "mimeType": "image/png" }
],
"createdAt": 1750000000000,
"completedAt": 1750000020000
}
}| 필드 | 타입 | 설명 |
|---|---|---|
taskId | string | 작업 식별자 |
status | string | pending, generating, success, fail 중 하나 |
images | array | 성공 시 존재하며, 각 항목은 { url, mimeType } |
failMsg | string | status 가 fail 일 때의 실패 메시지 |
createdAt | number | 생성 시각(epoch 밀리초) |
completedAt | number | 완료 시각(epoch 밀리초). 완료된 경우에만 |
작업 목록 조회
GET /v1/images/generation/tasks
내 이미지 작업을 최신순으로 나열합니다.
| 쿼리 파라미터 | 타입 | 기본값 | 설명 |
|---|---|---|---|
page | number | 1 | 페이지 번호, 최소 1 |
pageSize | number | 20 | 페이지당 항목 수, 1–100 |
status | string | — | pending, generating, success, fail 로 필터링 |
curl "https://api.marswave.ai/openapi/v1/images/generation/tasks?page=1&pageSize=20&status=success" \
-H "Authorization: Bearer $LISTENHUB_API_KEY"{
"code": 0,
"message": "",
"data": {
"items": [
{ "taskId": "65f0...", "status": "success", "images": [/* ... */], "createdAt": 1750000000000, "completedAt": 1750000020000 }
],
"page": 1,
"pageSize": 20,
"total": 1
}
}백그라운드 작업이 pending 또는 generating 상태로 30분을 넘기면 타임아웃 failMsg 와 함께
fail 로 정리됩니다. 그보다 오래된 비종료 상태는 실패로 간주하고 재시도하세요.
응답 형식
| 엔드포인트 | 엔벨로프로 감싸는가? | 응답 본문 |
|---|---|---|
POST /v1/images/generation | 아니요 — 모델 원본 JSON | base64 이미지 데이터(아래 참고) |
POST /v1/images/generation/async | 예 | { taskId, status } |
POST /v1/images/generation/estimate-credits | 예 | 예상 객체 |
GET /v1/images/generation/tasks | 예 | 페이지네이션된 { items, page, pageSize, total } |
GET /v1/images/generation/tasks/{taskId} | 예 | 작업 객체 |
동기 엔드포인트는 모델의 원본 출력을 그대로 반환합니다(감싸지 않음). 성공한 응답 본문에는 생성된 이미지가 base64 데이터로 들어 있습니다.
{
"candidates": [
{
"content": {
"parts": [
{
"inlineData": {
"mimeType": "image/png",
"data": "<BASE64_ENCODED_IMAGE>"
}
}
]
}
}
]
}data 필드를 base64에서 디코딩하면 이미지 파일이 됩니다. 비동기 경로는 이미지를 대신 저장해
주고 작업 객체에 호스팅된 url 을 반환하므로 base64 디코딩이 필요 없습니다.
NanoBanana Pro 무료 할당량
API key 호출은 웹과 Labnana 앱과 동일한 계정 단위 무료 할당량(freeUsages) 잔액을 사용합니다.
가입, 초대, 출석 체크로 할당량을 계속 적립하고, API를 통해 소비합니다. 실시간 잔액은
GET /v1/user/subscription 으로 조회한 뒤
freeUsages 맵을 읽으세요.
해당 잔액이 0 보다 크면 1K / 2K 요청은 크레딧 대신 무료 생성 1회를 소비합니다. 잔액이 0 이
되면 같은 요청이 일반 크레딧 과금으로 되돌아갑니다.
무료 할당량은 1K 와 2K 크기에만 적용됩니다. 4K 요청은 절대 freeUsages 를 사용하지
않으며 항상 크레딧으로 과금됩니다.
NanoBanana Pro relax 호출이 어떻게 실행되는지는 계정 유형에 따라 달라집니다.
- 유료 또는 결제 이력이 있는 계정(활성 구독, 충전, 크레딧 팩 구매)은 무료 할당량을 쓰는 중에도 일반 유료 생성 경험을 그대로 받습니다 — 온전한 우선순위, 정상 용량, 정상 폴백. 무료 할당량은 과금만 바꿀 뿐 제한된 통로로 보내지 않습니다.
- 순수 무료 계정(한 번도 결제한 적 없음)은 고정 처리량 상한이 걸린 최저 우선순위 무료 통로에서 NanoBanana Pro relax를 실행합니다. 피크 시간대에는 요청이 대기열에 들어가거나 재시도 가능한 busy/timeout 응답과 함께 거부될 수 있습니다. 그럴 때는 크레딧도 소비되지 않고 무료 할당량도 소모되지 않으므로 나중에 다시 시도하세요(늦은 밤이 더 빠릅니다).
순수 무료 relax 실패는 현지화된 텍스트를 파싱하지 않고도 감지할 수 있도록 기계 판독 가능한 메타데이터를 반환합니다.
failReason은free_relax_busy또는free_relax_timeout입니다.retryable은true입니다.- 무료 할당량이 환불되면
freeUsageRolledBack이true가 됩니다. userMessage에는 친절하고 현지화 가능한 문구가 담깁니다.
동기 요청에서는 오류 응답 본문에, 비동기 요청에서는 실패한 작업 상세(및 작업 목록)에 나타납니다. 두 사유 모두 "나중에 재시도, 아무것도 과금되지 않음"으로 처리하세요.
레이트 리밋과 참조 이미지 모드
표준 텍스트-투-이미지 요청에는 사용자별 및 전역 레이트 리밋이 적용됩니다.
참조 이미지 모드(inlineData 를 사용하는 referenceImages)에는 추가 서버 측 리소스 제약이
적용됩니다. 피크 시간대에는 base64 요청이 더 공격적으로 제한될 수 있습니다. 429 를 받으면
Retry-After 헤더를 읽고 백오프한 뒤 재시도하세요. 클라이언트에 지수 백오프를 구현하세요.
오류 코드
오류는 표준 엔벨로프(code 가 0이 아님)로 반환되며, 동기 엔드포인트의 경우
NanoBanana Pro 무료 할당량에 기록된 원본 오류 본문으로 반환됩니다.
| HTTP 상태 | 의미 |
|---|---|
400 | 잘못된 요청 파라미터(예: 선택한 모델이 지원하지 않는 화면비) |
402 | 크레딧 부족 |
429 | 레이트 리밋 또는 서비스 혼잡 — Retry-After 를 읽고 재시도 |
500 | 이미지 생성 실패 — 요청을 재시도 |