Gemini 3.1 Flash Image Preview

• 모델: gemini-3.1-flash-image-preview (고정)
• 기능: 텍스트-이미지, 이미지-이미지 (최대 14개 참조), 최대 4K, 극단적 종횡비, 선택적 Google 검색 근거

이 모델을 /v1/chat/completions으로 호출하지 마세요 — Images API를 사용하라는 힌트와 함께 400 오류가 발생합니다.

엔드포인트

모드	엔드포인트	사용 시기
동기 (권장)	POST https://apimaster.ai/v1/images/generations	단일 HTTP 왕복; 플랫폼이 업스트림을 폴링하여 { "data": [{ "url" }] } 반환
비동기	POST https://apimaster.ai/v1/images/generations/async → GET https://apimaster.ai/v1/tasks/{task_id}?model=gemini-3.1-flash-image-preview	긴 작업, 사용자 정의 대기열

빠른 시작 (동기)

curl -s "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "Cyberpunk city at night, neon lights",
    "size": "16:9",
    "resolution": "2K",
    "n": 1
  }'

성공

{
  "created": 1782633696,
  "data": [{ "url": "https://apimaster.ai/imgs/1782633695067198543.jpg" }]
}

2K/4K의 경우 HTTP 읽기 제한 시간을 ≥ 180초로 설정하세요. URL을 즉시 다운로드하거나 미러링하세요 — 만료됩니다.

비동기 흐름

제출

curl -s "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "a corgi astronaut on the moon",
    "size": "1:1",
    "resolution": "1K",
    "n": 1
  }'

제출 응답

{
  "code": 200,
  "data": [{ "status": "submitted", "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K" }]
}

폴링

curl -s "https://apimaster.ai/v1/tasks/TASK_ID?model=gemini-3.1-flash-image-preview" \
  -H "Authorization: Bearer YOUR_API_KEY"

성공 시 data.result.images[0].url을 읽습니다. 일반적인 폴링 상태: in_progress → succeeded / completed.

첫 번째 폴링 전에 10–20초 기다린 후, 3–5초마다 폴링하세요.

인증

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

본문 매개변수

필드	타입	필수	참고
model	string	예	gemini-3.1-flash-image-preview
prompt	string	예	장면 설명
size	string	아니요	종횡비; 아래 참조
resolution	string	아니요	0.5K / 1K / 2K / 4K, 기본값 1K; 대소문자 구분 안 함
n	integer	아니요	1만 지원 (숫자, 문자열 아님)
image_urls	array	아니요	참조 이미지 (URL 또는 데이터 URI)
google_search	boolean	아니요	Google 텍스트 검색 근거(grounding)
google_image_search	boolean	아니요	google_search: true 필요

해상도 및 요금 등급

값	~픽셀	1K 기본 대비 가격
0.5K	~512	1K와 동일
1K	~1024	기본
2K	~2048	× 4/3
4K	~4096	× 2

실제 요금 = 채널 가격 × 해상도 배율 × 그룹 비율. 마켓플레이스 또는 콘솔 로그를 참조하세요.

오류

HTTP	의미
400	잘못된 매개변수, 또는 잘못된 엔드포인트 (채팅)
401	유효하지 않은 API 키
402	잔액 부족
408	동기 폴링 시간 초과 — 비동기 재시도 또는 해상도 낮춤
500 / 502	업스트림 또는 플랫폼 오류

잘못된 종횡비는 하나의 채널만 구성된 경우 500으로 표시될 수 있습니다.

참고사항

• 사용 로그에는 이미지 미리보기용 result_url과 request_data.effective_resolution이 포함됩니다.
• 가격은 채널과 해상도에 따라 다릅니다 — 마켓플레이스를 참조하세요.