이미지 생성
Nano Banana, GPT-Image, Seedream, Wan 2.7 모델 시리즈에서 텍스트 프롬프트와 참조 이미지로 이미지를 동기 또는 비동기 작업으로 생성합니다.
이미지 생성은 텍스트 프롬프트를 — 선택적으로 참조 이미지의 안내를 받아 — 한 장 이상의 이미지로
바꿔 줍니다. 네 시리즈에 걸친 아홉 개 모델이 하나의 요청 스키마와 하나의 엔드포인트 집합을
공유하며, model 필드로 모델을 선택합니다.
호출 방식은 세 가지입니다.
- 동기 —
POST /v1/images/generation은 이미지가 준비될 때까지 블로킹하며, 응답 본문에 모델의 원본 출력(base64 이미지 데이터)을 반환합니다. - 비동기 —
POST /v1/images/generation/async는taskId를 즉시 반환합니다. 호스팅된 이미지 URL은GET /v1/images/generation/tasks/{taskId}를 폴링해서 가져오세요. - 먼저 예상 —
POST /v1/images/generation/estimate-credits는 아무것도 소비하지 않고 크레딧 비용과 계정이 생성 가능한 상태인지를 반환합니다.
이 페이지의 모든 엔드포인트는 OpenAPI Base URL https://api.marswave.ai/openapi 를 사용하며,
Authorization: Bearer $LISTENHUB_API_KEY 헤더로 API 키를 인증합니다. 키는
listenhub.ai/settings/api-keys 에서 만드세요.
모델 선택
아래 표에서 모델을 고른 다음, 해당 시리즈 페이지에서 정확한 제한과 특이 사항, 예제를 확인하세요.
| 모델 | 시리즈 | 적합한 용도 | 크기 | 화면 비율 | 참조 이미지 최대 개수 |
|---|---|---|---|---|---|
gpt-image-2 (기본값) | GPT-Image | 크기별 고정 가격으로 프롬프트를 충실히 따름 | 1K, 2K, 4K | 표준 10종 비율 | 4 |
gpt-image-2.5-flare | GPT-Image | 가격과 제한이 같은 두 번째 GPT-Image 스타일 | 1K, 2K, 4K | 표준 10종 비율 | 4 |
gpt-image-2.5-sunburst | GPT-Image | 가격과 제한이 같은 세 번째 GPT-Image 스타일 | 1K, 2K, 4K | 표준 10종 비율 | 4 |
gpt-image-2-official | GPT-Image | quality 를 반영하는 유일한 모델, token 단위 과금 | 1K, 2K, 4K | 표준 10종 비율 | 4 |
gemini-3-pro-image | Nano Banana | 가장 세밀한 출력, Nano Banana Pro | 1K, 2K, 4K | 표준 10종 비율 | 14 |
gemini-3.1-flash-image | Nano Banana | 더 빠르고 저렴한 생성, 1:4 / 4:1 / 1:8 / 8:1 을 받는 유일한 Nano Banana 등급 | 1K, 2K, 4K | 14종 전부 | 14 |
seedream-5-0-pro | Seedream | 좌표와 색상 코드로 하는 정밀 영역 편집 | 1K, 2K | 14종 전부 | 10 |
wan2.7-image | Wan 2.7 | 자주 쓰는 다섯 가지 비율에서 비용 효율적인 생성 | 1K, 2K | 5종 비율 | 9 |
wan2.7-image-pro | Wan 2.7 | 같은 다섯 비율에 4K 출력 지원 | 1K, 2K, 4K | 5종 비율 | 9 |
model 을 생략하면 gpt-image-2 가 기본값입니다. 표준 10종 비율은 1:1, 2:3, 3:2,
3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 — 네 가지 극단 비율을 제외한 전부입니다. 전체
규칙은 화면 비율을 참고하세요.
Nano Banana
gemini-3-pro-image와 gemini-3.1-flash-image: 디테일 우선과 속도 우선인 Google 모델 둘, 그리고 네 가지 극단 비율.
GPT-Image
gpt-image-2, 2.5 Flare와 Sunburst 변형, 그리고 GPT-Image-2 Pro — quality를 반영하는 유일한 모델.
Seedream
seedream-5-0-pro: prompt에 좌표를 적어 기존 이미지의 지정한 영역을 편집합니다.
Wan 2.7
wan2.7-image와 wan2.7-image-pro: 엄격하게 검증되는 다섯 가지 비율, Pro 등급에서는 4K까지.
호출 흐름
비용 예상
생성에 쓸 것과 동일한 요청 본문으로 POST /v1/images/generation/estimate-credits 를 호출하세요.
아무것도 소비하지 않고 credits 와 canGenerate 를 반환합니다. 크레딧 비용은 모델과 크기에 따라
달라집니다 — 하드코딩하지 말고 이 엔드포인트에서 읽어 오세요.
생성
이미지가 준비될 때까지 블로킹하려면 POST /v1/images/generation 을, taskId 를 즉시 받으려면
POST /v1/images/generation/async 를 호출하세요.
결과 받기
동기 엔드포인트는 응답 본문에 base64 이미지 데이터를 반환합니다. 비동기 엔드포인트는 이미지를 대신
저장해 줍니다 — status 가 success 가 될 때까지 GET /v1/images/generation/tasks/{taskId} 를
폴링한 뒤 호스팅된 images[].url 을 읽으세요.
요청 파라미터
아래 파라미터는 POST /v1/images/generation, POST /v1/images/generation/async,
POST /v1/images/generation/estimate-credits 에 적용됩니다 — 세 엔드포인트가 하나의 요청 스키마를
공유합니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
provider | string | 예¹ | 모델 프로바이더: google, openai, bytedance, alibaba, quotaflow |
model | string | 아니요 | 모델 이름. 기본값은 gpt-image-2. 레거시 preview ID는 대응하는 GA ID로 정규화됩니다. 모델 선택 참고 |
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 타입: fileData.mimeType 과 동일한 다섯 가지 값 |
imageConfig | object | 아니요 | 이미지 출력 설정. 기본값은 { "imageSize": "2K" } |
imageConfig.imageSize | string | 아니요 | 출력 해상도: 1K, 2K(기본값), 4K. 모델별 제한을 따릅니다 |
imageConfig.aspectRatio | string | 아니요 | 화면 비율. 시리즈별 기본값 규칙은 화면 비율 참고 |
imageConfig.quality | string | 아니요 | low, medium, high. gpt-image-2-official 만 반영하며, 다른 모든 모델은 무시합니다 |
¹ provider 는 두 생성 엔드포인트에서 필수이고 estimate-credits 에서는 선택입니다.
² prompt 는 두 생성 엔드포인트에서 필수입니다. estimate-credits 에서는 비어 있거나 생략해도
됩니다(입력 token 예상치에만 영향을 줍니다).
referenceImages 의 각 항목은 fileData 또는 inlineData 중 적어도 하나를 담아야 합니다.
정확히 하나만 보내세요 — 검증은 둘 다 담긴 항목도 받아들이지만, 그때의 동작은 정의되어
있지 않습니다.
provider 는 검증은 되지만 라우팅에는 쓰이지 않습니다 — 상위 모델은 전적으로 model 로
결정됩니다. 요청을 읽기 쉽게 유지하려면 이 페이지들의 모든 예제처럼 모델에 맞는 벤더를
보내세요. 다만 값이 어긋나더라도 실제로 실행되는 모델은 바뀌지 않습니다.
gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst 에 quality 를 전달해도 오류가
나지는 않습니다 — 값이 버려지고 estimate-credits 가 경고
quality_ignored_for_gpt_image_2_lite 를 반환합니다. 요청한 품질로 렌더링하는 모델은
gpt-image-2-official 뿐입니다.
GPT-Image를 참고하세요.
화면 비율
전체 모델 목록에 걸쳐 14종의 비율이 있습니다. 그중 10종은 표준 비율로 대부분의 모델이
받아들이고, 4종은 극단 비율로 gemini-3.1-flash-image 와 seedream-5-0-pro 만 받아들입니다.
| 비율 | 설명 | 분류 |
|---|---|---|
1:1 | 정사각형 | 표준 |
2:3 | 세로 | 표준 |
3:2 | 가로 | 표준 |
3:4 | 세로 | 표준 |
4:3 | 가로 | 표준 |
4:5 | 세로 | 표준 |
5:4 | 가로 | 표준 |
9:16 | 세로 / 모바일 | 표준 |
16:9 | 와이드스크린 | 표준 |
21:9 | 울트라와이드 | 표준 |
1:4 | 좁은 세로 | 극단 |
4:1 | 넓은 가로 | 극단 |
1:8 | 극단적 세로 | 극단 |
8:1 | 파노라마 | 극단 |
imageConfig.aspectRatio 에는 스키마 수준 기본값 1:1 이 걸려 있습니다. aspectRatio 없이
imageConfig 객체를 보내면 모든 모델에서 정사각형 이미지가 나옵니다 — 아래의 시리즈별
동작은 imageConfig 를 통째로 생략했을 때만 적용됩니다. imageConfig 자체의 객체 기본값은
{ "imageSize": "2K" } 라서 비율을 설정하지 않은 채로 두기 때문입니다.
위의 스키마 기본값이 값을 이미 채워 넣지 않았을 때, aspectRatio 는 다음과 같이 결정됩니다.
| 시리즈 | 여전히 설정되지 않았을 때 | 지원하지 않을 때 |
|---|---|---|
| Nano Banana | 1:1 로 결정 | 400, code: 29003 |
| GPT-Image | 설정하지 않음 — 모델이 프롬프트에 맞는 비율을 고릅니다 | 400, code: 26019, 지원 목록을 메시지에 담음 |
| Seedream | 설정하지 않음 | 허용 — Seedream은 비율이 아니라 크기로 검증합니다 |
| Wan 2.7 | 설정하지 않음 | 400, code: 26019, 지원 목록을 메시지에 담음 |
이미지 크기
imageConfig.imageSize 는 1K, 2K(기본값), 4K 를 받습니다. 크기가 클수록 크레딧을 더 많이
소비합니다.
| 모델 | 1K | 2K | 4K |
|---|---|---|---|
| 모든 GPT-Image 모델 | 예 | 예 | 예 |
| Nano Banana 모델 둘 다 | 예 | 예 | 예 |
seedream-5-0-pro | 예 | 예 | 400 |
wan2.7-image | 예 | 예 | 400 |
wan2.7-image-pro | 예 | 예 | 텍스트에서 이미지 생성만 가능 — 참조 이미지와 함께 쓰면 400 |
크레딧 비용을 하드코딩하지 마세요 — 사용할 모델과 크기, 비율의 정확한 값은 estimate-credits를 호출해 확인하세요.
참조 이미지
참조 이미지는 생성을 유도합니다. 각 이미지는 URL(fileData) 또는 base64(inlineData) 중 하나로만
제공하고 둘 다 넣지 마세요. 배열은 모델의 상한 안으로 유지하세요.
| 시리즈 | 참조 이미지 최대 개수 |
|---|---|
| Nano Banana | 14(스키마 상한) |
| GPT-Image | 4 |
| Seedream | 10 |
| Wan 2.7 | 9 |
스키마는 모든 모델에 대해 referenceImages 를 최대 14개로 제한합니다. 상한이 더 엄격한 시리즈는
초과분을 400 과 해당 상한을 밝히는 메시지로 거부합니다. fileData 와 inlineData 모두
받아들이는 MIME 타입은 image/png, image/jpeg, image/webp, image/heic, image/heif 입니다.
세 이미지 엔드포인트는 최대 25MB 의 JSON 본문을 받습니다 — base64 inlineData 가 그 안에
들어가야 하므로 플랫폼 기본값의 네 배입니다. base64는 파일 크기를 대략 3분의 1 정도 부풀리므로,
인라인으로 넣는 이미지는 원본 바이트 기준 합계 약 18MB 아래로 유지하거나, fileData 로 URL을
전달하세요.
이미지 생성(동기)
POST /v1/images/generation
이미지를 생성하고 준비될 때까지 블로킹합니다. 응답 본문은 모델의 원본 출력 — base64 이미지 데이터를
담은 JSON이며, 표준 { code, message, data } 엔벨로프가 아닙니다.
응답 형식을 참고하세요.
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": "An astronaut riding a horse on Mars, photorealistic",
"imageConfig": {
"imageSize": "2K",
"aspectRatio": "16:9"
}
}'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: 'An astronaut riding a horse on Mars, photorealistic',
imageConfig: { imageSize: '2K', aspectRatio: '16:9' },
}),
},
)
const result = await response.json()
const image = result.candidates[0].content.parts[0].inlineDataimport 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': 'An astronaut riding a horse on Mars, photorealistic',
'imageConfig': {'imageSize': '2K', 'aspectRatio': '16:9'},
},
)
result = response.json()
image = result['candidates'][0]['content']['parts'][0]['inlineData']참조 이미지 사용
참조 이미지는 모든 엔드포인트에서 동일하게 동작합니다. 이미지가 이미 호스팅되어 있으면
fileData 를, 바이트를 메모리에 갖고 있으면 inlineData 를 사용하세요.
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": "Redraw this character in a watercolor style",
"referenceImages": [
{
"fileData": {
"fileUri": "https://example.com/character.png",
"mimeType": "image/png"
}
}
],
"imageConfig": { "imageSize": "2K", "aspectRatio": "3:4" }
}'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": "Redraw this character in a watercolor style",
"referenceImages": [
{
"inlineData": {
"data": "'"$(base64 -w0 character.png)"'",
"mimeType": "image/png"
}
}
],
"imageConfig": { "imageSize": "2K", "aspectRatio": "3:4" }
}'base64 참조 이미지를 담은 요청은 별도의 더 엄격한 레이트 리밋에 걸립니다. 429 를 받으면
Retry-After 헤더를 읽고 백오프한 뒤 재시도하세요.
비동기 생성
오래 걸리거나 고해상도인 작업이라면 요청을 열어 둔 채 기다리지 말고, 작업을 제출한 뒤 결과를 폴링하세요.
비동기 작업 생성
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" }
}'응답(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/estimate-credits
주어진 설정의 크레딧 비용과 계정 잔액이 충분한지를, 크레딧을 소비하지도 모델을 호출하지도 않고
반환합니다. 생성 엔드포인트와 동일한 요청 본문을 받으며, 여기서는 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"
}
}'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' },
}),
},
)
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'},
},
)
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 | gpt-image-2-official 이 4K 또는 quality: high 일 때만 true |
pricing | object | 가격 메타데이터: pricingVersion, mode(token-estimate 또는 fixed), 요율 입력값 |
warnings | array | 안내 문자열, 예: quality_ignored_for_gpt_image_2_lite |
{
"code": 0,
"message": "",
"data": {
"model": "gpt-image-2",
"imageSize": "2K",
"aspectRatio": "1:1",
"credits": 6,
"canGenerate": true,
"requiresSubscription": false,
"pricing": { "pricingVersion": "gpt-image-2-lite-fixed-2026-06-15", "mode": "fixed" },
"warnings": []
}
}대부분의 모델은 크기별 고정 크레딧 비용으로 과금됩니다(mode: "fixed").
gpt-image-2-official 은 예상 token 수를 기준으로 과금되므로(mode: "token-estimate"), 비용이
프롬프트 길이, 출력 크기, 요청한 품질, 참조 이미지 개수(API에서는 각각 고정 요율로 계산)에
따라 달라집니다.
credits 는 언제나 해당 설정의 크레딧 가격입니다. 무료 할당량을 빼지 않습니다 — 할당량이
남아 있는 계정의 1K 또는 2K 요청도 전체 가격으로 예상되고, 실제로는 아무 비용도 들지
않습니다. 계정이 실제로 지불할 가격을 보여줘야 한다면
freeUsages 를 직접 읽으세요.
무료 생성
API key 호출은 ListenHub 및 Labnana 앱과 동일한 계정 단위 무료 할당량(freeUsages) 잔액을
사용합니다. 가입, 초대, 출석 체크로 할당량을 적립하고 API를 통해 소비합니다. 실시간 잔액은
GET /v1/user/subscription 으로 조회한 뒤
freeUsages 맵을 읽으세요.
해당 잔액이 0 보다 크면 1K 또는 2K 요청은 크레딧 대신 무료 생성 1회를 소비합니다. 잔액이
0 이 되면 같은 요청은 일반 크레딧 과금으로 되돌아갑니다.
| 무료 할당량 리소스 | 적용되는 모델 |
|---|---|
gemini-3-pro-image-relax-1k-2k | gemini-3-pro-image |
gemini-3.1-flash-image | gemini-3.1-flash-image |
gpt-image-2 | gpt-image-2 |
gpt-image-2.5 | gpt-image-2.5-flare, gpt-image-2.5-sunburst |
seedream-5-0-pro | seedream-5-0-pro |
wan2.7-image | wan2.7-image |
무료 할당량은 1K 와 2K 크기에만 적용됩니다 — 4K 요청은 절대 freeUsages 를 사용하지
않으며 항상 크레딧으로 과금됩니다. gpt-image-2-official 과 wan2.7-image-pro 는 어떤
크기에서도 무료 할당량이 없습니다.
gemini-3-pro-image 는 무료 할당량이 별도 실행 통로에서 도는 유일한 모델이며, 분기 처리에 쓸 자체
실패 메타데이터가 있습니다 —
Nano Banana → relax 통로를 참고하세요.
응답 형식
| 엔드포인트 | 엔벨로프로 감싸는가? | 응답 본문 |
|---|---|---|
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 디코딩이 필요 없습니다.
에러 코드
오류는 0이 아닌 code 를 담은 표준 엔벨로프로 반환되며, 동기 엔드포인트의 경우
무료 생성에서 설명한 원본 오류 본문으로 반환됩니다.
이 경로들은 모든 비즈니스 오류를 HTTP 400 으로 정규화합니다. 크레딧 부족은 402 가 아니라
code: 26004 를 담은 400 입니다 — HTTP 상태 코드가 아니라 엔벨로프의 code 로 분기하세요.
429 는 자체 의미를 갖는 유일한 상태 코드입니다. 예외는 동기 요청의 free-relax 실패 본문으로,
엔벨로프로 감싸지 않은 원본이며 code 대신 errno 를 담습니다.
| HTTP 상태 코드 | code | 의미 |
|---|---|---|
400 | 29003 | 잘못된 파라미터 — 모델이 거부하는 크기 또는 참조 이미지 개수, 또는 Nano Banana 시리즈가 거부하는 비율 |
400 | 26019 | GPT-Image 또는 Wan 2.7에서 지원하지 않는 화면 비율 |
400 | 26004 | 크레딧 부족 |
400 | 23016 | 구독 필요 — 활성 플랜이 없는 계정에서 gpt-image-2-official 을 4K 또는 quality: high 로 사용한 경우. 먼저 예상 응답의 requiresSubscription 을 확인하세요 |
429 | — | 레이트 리밋 또는 서비스 혼잡 — Retry-After 를 읽고 백오프 |
비율 거부가 모두 하나의 코드로 오지는 않습니다. Nano Banana는 29003 을, GPT-Image와 Wan 2.7은
26019 를 냅니다. “이 모델에 맞지 않는 비율”을 감지하려면 두 코드 모두로 분기하세요.
두 생성 엔드포인트 모두 사용자별 및 전역 레이트 리밋이 적용됩니다. base64 참조
이미지(inlineData)를 담은 요청에는 별도의 더 엄격한 제한이 적용되며, 피크 시간대에는 가장 먼저
제한될 수 있습니다. estimate-credits 에는 레이트 리밋이 없습니다.