curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "gemini-nano-banana-2.1",
"prompt": "나무 테이블에 앉은 주황색 고양이, 옆에 커피 한 잔, 부드러운 아침 햇살, 사실적인 사진",
"size": "16:9",
"resolution": "2K",
"n": 1
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/images/generations",
headers={"Authorization": "Bearer <token>"},
json={
"model": "gemini-nano-banana-2.1",
"prompt": "나무 테이블에 앉은 주황색 고양이, 옆에 커피 한 잔, 부드러운 아침 햇살, 사실적인 사진",
"size": "16:9",
"resolution": "2K",
"n": 1
}
)
print(response.json())
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "gemini-nano-banana-2.1",
prompt: "나무 테이블에 앉은 주황색 고양이, 옆에 커피 한 잔, 부드러운 아침 햇살, 사실적인 사진",
size: "16:9",
resolution: "2K",
n: 1
})
});
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K..."
}
]
}
Nano banana 2.1
Nano banana 2.1 이미지 생성
텍스트 기반 이미지 생성과 참조 이미지 편집, 1K / 2K / 4K 출력 및 10가지 화면비를 지원하며 공식 버전과 Ext 버전을 제공합니다.
POST
/
v1
/
images
/
generations
curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "gemini-nano-banana-2.1",
"prompt": "나무 테이블에 앉은 주황색 고양이, 옆에 커피 한 잔, 부드러운 아침 햇살, 사실적인 사진",
"size": "16:9",
"resolution": "2K",
"n": 1
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/images/generations",
headers={"Authorization": "Bearer <token>"},
json={
"model": "gemini-nano-banana-2.1",
"prompt": "나무 테이블에 앉은 주황색 고양이, 옆에 커피 한 잔, 부드러운 아침 햇살, 사실적인 사진",
"size": "16:9",
"resolution": "2K",
"n": 1
}
)
print(response.json())
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "gemini-nano-banana-2.1",
prompt: "나무 테이블에 앉은 주황색 고양이, 옆에 커피 한 잔, 부드러운 아침 햇살, 사실적인 사진",
size: "16:9",
resolution: "2K",
n: 1
})
});
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K..."
}
]
}
모델 선택
| 모델 ID | 과금 방식 | 요청당 이미지 수 | 참조 이미지 크기 |
|---|---|---|---|
gemini-nano-banana-2.1 | 실제 토큰 사용량 기준 | 1–4장 | 이미지당 최대 20MB |
gemini-nano-banana-2.1-ext | 해상도 등급별 이미지당 과금 | 1장만 | 이미지당 최대 20MB, 총 50MB |
이 API는 비동기 방식입니다. 제출에 성공하면
task_id를 반환합니다. 작업 조회로 상태와 이미지를 가져오세요. 3–5초 간격으로 폴링하고 전체 대기 제한 시간을 최소 3분으로 설정하는 것을 권장합니다.curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "gemini-nano-banana-2.1",
"prompt": "나무 테이블에 앉은 주황색 고양이, 옆에 커피 한 잔, 부드러운 아침 햇살, 사실적인 사진",
"size": "16:9",
"resolution": "2K",
"n": 1
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/images/generations",
headers={"Authorization": "Bearer <token>"},
json={
"model": "gemini-nano-banana-2.1",
"prompt": "나무 테이블에 앉은 주황색 고양이, 옆에 커피 한 잔, 부드러운 아침 햇살, 사실적인 사진",
"size": "16:9",
"resolution": "2K",
"n": 1
}
)
print(response.json())
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "gemini-nano-banana-2.1",
prompt: "나무 테이블에 앉은 주황색 고양이, 옆에 커피 한 잔, 부드러운 아침 햇살, 사실적인 사진",
size: "16:9",
resolution: "2K",
n: 1
})
});
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K..."
}
]
}
요청 헤더
string
필수
Bearer <token> 형식의 Bearer 인증입니다. <token>은 APIMart API Key입니다.요청 매개변수
string
필수
모델 ID:
gemini-nano-banana-2.1 또는 gemini-nano-banana-2.1-ext.string
필수
이미지 생성 또는 편집을 위한 텍스트 설명입니다. 중국어와 영어를 지원합니다.
string
기본값:"auto"
출력 화면비입니다.
1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9를 지원하며 16x9 형식도 허용됩니다.생략하거나 auto로 설정하면 모델이 결정합니다. 이미지 기반 생성에서는 참조 이미지의 비율을 따릅니다.1:4, 4:1, 1:8, 8:1 등 다른 비율은 지원하지 않습니다. 지원하지 않는 비율을 사용하면 작업이 실패하고 환불됩니다.string
기본값:"1K"
출력 해상도 등급:
1K, 2K 또는 4K. 소문자도 허용되며 과금에도 영향을 줍니다.0.5K와 512는 지원하지 않으며 제출 시 HTTP 400을 반환합니다. 3K 등 인식할 수 없는 다른 값은 1K로 생성 및 과금됩니다. 위의 지원 값만 사용하세요.integer
기본값:"1"
생성할 이미지 수입니다. 공식 버전은 1–4장, Ext 버전은 1장만 지원합니다.4를 초과하면 제출 즉시 HTTP 400을 반환합니다. Ext 버전에 2–4를 지정하면 실행 단계에서 실패하고 전액 환불됩니다. 여러 장이 필요하면 Ext 작업을 각각 제출하거나 공식 버전을 사용하세요.
string[]
참조 이미지 목록입니다. 생략하면 텍스트 기반 생성, 지정하면 이미지 기반 생성 또는 편집을 수행합니다. 각 항목은 다음을 지원합니다.
- 공개적으로 접근 가능한 HTTP(S) 이미지 URL.
data:image/png;base64,...형식의 Base64 Data URL.
boolean
기본값:"false"
gemini-nano-banana-2.1-ext에만 적용됩니다. 활성화하면 Ext 버전 실패 시 공식 버전으로 작업 완료를 시도합니다.실제로 공식 버전을 사용하면 Ext 버전의 이미지당 요금이 아닌 공식 버전의 실제 토큰 사용량으로 과금됩니다.출력 크기 참고
| 화면비 | 1K | 2K | 4K |
|---|---|---|---|
| 1:1 | 1024×1024 | 2048×2048 | 4096×4096 |
| 2:3 | 848×1264 | 1696×2528 | 3392×5056 |
| 3:2 | 1264×848 | 2528×1696 | 5056×3392 |
| 3:4 | 896×1200 | 1792×2400 | 3584×4800 |
| 4:3 | 1200×896 | 2400×1792 | 4800×3584 |
| 4:5 | 928×1152 | 1856×2304 | 3712×4608 |
| 5:4 | 1152×928 | 2304×1856 | 4608×3712 |
| 9:16 | 768×1376 | 1536×2752 | 3072×5504 |
| 16:9 | 1376×768 | 2752×1536 | 5504×3072 |
| 21:9 | 1584×672 | 3168×1344 | 6336×2688 |
참조 이미지 편집
{
"model": "gemini-nano-banana-2.1-ext",
"prompt": "이미지 속 고양이에게 빨간 니트 모자를 씌우고 나머지는 그대로 유지해 주세요",
"image_urls": ["https://example.com/cat.jpg"],
"resolution": "1K"
}
size를 생략하면 참조 이미지의 비율을 따릅니다.
일괄 생성(공식 버전만)
{
"model": "gemini-nano-banana-2.1",
"prompt": "사이버펑크 스타일의 도시 야경, 네온 조명, 비가 그친 거리",
"size": "16:9",
"resolution": "2K",
"n": 4
}
제출 응답
integer
응답 상태 코드입니다. 성공 시
200입니다.array
작업 제출 결과입니다.
status는 submitted입니다. task_id는 작업 상태와 결과 조회에 사용하는 ID이며 최종 이미지 URL이 아닙니다.작업 결과 조회
curl --request GET \
--url https://api.apimart.ai/v1/tasks/task_01K... \
--header 'Authorization: Bearer <token>'
{
"code": 200,
"data": {
"id": "task_01K...",
"status": "completed",
"progress": 100,
"result": {
"images": [
{
"url": ["https://example.com/generated-image.png"],
"expires_at": 1791417625
}
]
}
}
}
| 작업 상태 | 의미 |
|---|---|
pending | 대기 중 |
processing | 생성 중 |
completed | 성공. data.result.images[0].url에서 이미지 URL 배열 확인 |
failed | 실패. data.error.message에서 원인 확인. 전액 환불되며 data.cost는 0 |
data.result.images[0].url 배열에 포함됩니다. 4장을 생성하면 이 배열에 링크 4개가 들어갑니다. 완성된 이미지만 반환하며 n=1은 완성 이미지 1장을 의미합니다.
링크는 작업 완료 후 24시간 동안 유효하며 expires_at을 기준으로 합니다. 만료 전에 다운로드하여 저장하세요. 출력은 PNG 또는 JPEG이며 실제 파일 내용을 기준으로 합니다. 조회 결과의 data.cost는 최종 청구 금액(USD)입니다.
과금 안내
- 공식 버전: 실제 입력 및 출력 토큰 사용량으로 과금됩니다. 프롬프트와 참조 이미지는 입력 사용량에 포함됩니다. 제출 시 해상도 등급과
n을 기준으로 선차감하고 완료 후 실제 사용량에 따라 환불 또는 추가 청구합니다. - Ext 버전: 해상도 등급별 단가 × 실제 생성 이미지 수로 과금됩니다. 화면비는 등급에 영향을 주지 않습니다.
official_fallback을 활성화하고 실제로 공식 버전을 사용하면 공식 버전의 토큰 과금이 적용됩니다. - 단가는 모델 가격을 확인하세요. 제출 단계에서 거부된 요청은 작업을 생성하지 않으며 과금되지 않습니다. 실패한 작업은 전액 환불됩니다.
일반적인 오류
| 상황 | 해결 방법 |
|---|---|
| HTTP 400 | 0.5K / 512, 4를 초과하는 n, 참조 이미지당 크기 제한 초과 여부 확인 |
| HTTP 401 | API Key 확인 |
| HTTP 402 | 잔액이 선차감 금액을 충당하는지 확인 |
| HTTP 429 | 요청 제한 발생. 대기 간격을 늘려 재시도 |
| 작업 실패: 지원하지 않는 화면비 | 지원하는 10가지 size 비율 또는 auto 사용 |
| 작업 실패: Ext에서 여러 장 요청 | n을 1로 설정하거나 공식 버전 사용 |
| 작업 실패: 콘텐츠 안전 검사 차단 | 프롬프트 또는 참조 이미지를 수정하고 재시도 |
| 작업 실패: 참조 이미지 다운로드 실패 | 이미지 URL에 공개적으로 접근할 수 있는지 확인 |
Nano banana 2.1과 Gemini 3.1 Flash Image는 서로 다른 모델이며 모델명을 별칭처럼 바꿔 사용할 수 없습니다. 후자에서 이전할 때는
0.5K 해상도와 1:4, 4:1, 1:8, 8:1의 네 가지 극단적 비율을 변경하세요.