플래그십 Nano Banana Pro(Gemini 3 Pro Image) 기반의 이미지 생성(비동기 작업 방식)입니다. 텍스트-투-이미지는 프롬프트만 있으면 되고, 이미지-투-이미지는 참조 이미지를 `image`(URL, data: URI, base64)에 넣으면 피사체를 유지한 채 다시 그립니다. 디테일과 구도, 이미지 안 글자 배치가 더 강해 상업용 표지와 고품질 일러스트에 적합합니다. 즉시 작업 ID가 돌아오고(HTTP 202) GET /v1/images/jobs/{id}를 폴링하면 됩니다. 화면 비율 7종과 1K / 2K / 4K를 지원하고 실패한 요청에는 과금하지 않습니다.
플레이그라운드에서 사용해 보기 →인증
Authorization: Bearer YOUR_API_KEY Content-Type: application/json
콘솔에서 API 키를 만들면 시작할 수 있습니다.
요청 본문
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| model | string | 예 | 모델 ID. 여기서는 nano-banana-pro입니다. |
| prompt | string | 예 | 만들 이미지를 설명하는 텍스트 프롬프트. |
| size | string | 아니오 | 출력 화면 비율. 비율을 넘기는 방식을 권장합니다 — 1:1, 3:4, 2:3, 9:16, 4:3, 3:2, 16:9 — 이렇게 하면 모델이 그 비율로 네이티브 렌더링해 피사체가 잘리지 않습니다. 픽셀 크기(예: 1024x1024, 1024x1536, 1536x1024)도 받습니다. 기본값은 1:1(정사각형)입니다. |
| n | integer | 아니오 | 이미지 장수. 기본값 1. |
| image | string | 아니오 | 이미지-투-이미지: 참조 이미지를 공개 URL, data: URI, 또는 원시 base64로 넣습니다. 값이 있으면 선택한 크기 / 비율에서 원본의 정체성을 유지하는 진짜 이미지-투-이미지가 실행되며, /v1/images/edits 호출과 동일합니다. |
| images | array | 아니오 | 다중 이미지 참조(최대 8장. 피사체 일관성을 위해서는 4장 이하 권장): 문자열 배열이나 [{"image_url": "..."}] 객체 배열로 넘기세요. 각 항목은 공개 URL, data: URI, base64 모두 가능합니다. 여러 참조의 피사체와 화풍을 융합하는 다중 참조 이미지-투-이미지가 실행되며, /v1/images/edits의 다중 이미지 입력과 동일합니다. 참조가 한 장이라면 위의 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-pro", "prompt": "a serene ink-wash poster, lots of negative space", "size": "1024x1536"}'
# 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-pro"
}이미지-투-이미지
이미지-투-이미지: 참조 이미지를 `image`에 넣으면(공개 URL, data: URI, 원시 base64 모두 가능) 원본의 정체성을 유지한 채 i2i가 실행됩니다 — 모델이 지정한 크기/비율로 다시 생성합니다. /v1/images/edits 호출과 동일합니다.
curl https://nezhagate.com/v1/images/generations -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model": "nano-banana-pro", "prompt": "배경을 별이 가득한 밤하늘로 바꿔 줘", "image": "https://example.com/ref.png", "size": "3:4"}'이미지 작업 (제출 → 결과 폴링)
이미지 생성은 보통 1~3분이 걸리므로 이미지 엔드포인트는 작업(job) 방식만 사용합니다. 요청을 제출하면 즉시 작업 ID가 반환되고(HTTP 202), 그 ID로 결과를 폴링합니다 — 서버는 재시작 중에도 렌더링을 이어가므로 이미지가 사라지지 않습니다. 텍스트-투-이미지와 이미지-투-이미지 모두 같습니다. (기존의 "async": true 필드는 더 이상 필요하지 않으며, 받아들이되 무시합니다.)
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "nano-banana-pro", "prompt": "여백이 넉넉한 수묵화 포스터", "size": "3:4"}'{ "id": "img_3f9a...c2", "object": "image.generation.job", "status": "queued", "model": "nano-banana-pro" }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": "succeeded",
"model": "nano-banana-pro",
"data": [{ "url": "https://img.nezhagate.com/i/9f86d081a8....png" }]
}status는 queued / processing / succeeded / failed 중 하나입니다. 성공하면 응답에 data[].url이 담깁니다. 작업은 이를 생성한 계정만 조회할 수 있습니다. 이미지 엔드포인트는 항상 비동기이며 — 제출 시 작업 ID를 반환합니다. "async": true는 하위 호환을 위해 받아들이지만 무시됩니다.
오류 코드
| Code | 설명 |
|---|---|
| 401 | API 키가 없거나 유효하지 않음 |
| 402 | 잔액 부족 또는 키 한도 초과 |
| 400 | 지원하지 않는 모델 또는 파라미터 |
| 429 | 업스트림 요청 한도 초과 |
| 502 | 모든 업스트림 경로가 실패 |
