이미지 생성
텍스트 프롬프트에서 이미지를 생성하는 API입니다.
Google, OpenAI, BFL, ByteDance, Ideogram, Recraft, Runway, Stability AI, xAI 등 다양한 제공업체의 이미지 모델을 지원하며, 제공업체에 따라 동기(즉시 반환) 또는 비동기(폴링) 방식으로 결과를 받을 수 있습니다.
동기 이미지 생성은 모델에 따라 응답 시간이 다릅니다. Google Gemini 모델은 약 510초, OpenAI 모델은 약 1530초가 소요됩니다. HTTP 클라이언트의 타임아웃을 최소 60초 이상으로 설정해주세요 (httpx 기본값은 5초입니다).
이미지 생성
POST
/v1/gateway/images/generate/텍스트 프롬프트에서 하나 이상의 이미지를 생성합니다.
상태 폴링 (비동기 전용)
GET
/v1/gateway/images/generate/{operation_id}/비동기 이미지 생성 상태 폴링 (Fal/Replicate 전용).
파라미터
model
이미지 모델 이름.string
required
prompt
생성할 이미지에 대한 텍스트 설명.string
required
number_of_images
생성할 이미지 수 (기본값: integer
1).aspect_ratio
예: string
"1:1", "16:9", "9:16", "4:3".quality
string
"standard" 또는 "hd" (제공업체별 상이).image_size
예: string
"1024x1024" (제공업체별 상이).input_images
편집·합성·인페인팅에 사용할 입력 이미지 목록. 값을 넣으면 같은 엔드포인트가 편집 모드로 동작합니다.list[string]
이미지 편집 · 합성
편집 전용 엔드포인트는 따로 없습니다. 생성과 같은
POST /v1/gateway/images/generate/에 input_images를 넣으면 편집 모드로 전환됩니다.- 배열의 각 항목은
http(s)URL 또는data:image/...;base64,...형태의 데이터 URL입니다. 이미지 호스팅이 없는 로컬 애플리케이션이라면 데이터 URL이 가장 간단한 방법입니다. 접두사 없는 raw base64 문자열은400으로 거절됩니다. - 이미지를 여러 장 넣으면 합성됩니다. 티셔츠 사진과 패턴 원단 사진을 함께 넣고 "Apply the pattern from the second image onto the garment in the first image"라고 지시하면 첫 번째 이미지의 옷에 두 번째 이미지의 패턴이 입혀집니다. 프롬프트에서는 넣은 순서대로 "첫 번째 이미지", "두 번째 이미지"처럼 지칭하세요.
- 모델별 최대 입력 이미지 수를 넘기면 한도를 알려주는
400이 반환됩니다.
모델별 최대 입력 이미지 수
| 모델 | 최대 입력 이미지 |
|---|---|
Nano Banana 2 (gemini-3.1-flash-image-preview) | 14 |
Nano Banana 2 Lite (gemini-3.1-flash-lite-image) | 14 |
| Nano Banana Pro, Nano Banana, GPT Image 2 / 1.5 / 1 / 1 Mini, Seedream 5.0 Pro / 5.0 Lite / 4.5 / 4.0 | 10 |
FLUX 2 [pro] (black-forest-labs/flux-2-pro) | 8 |
Gen-4 Image (runwayml/gen4-image) | 3 |
| SDXL, Grok Imagine, FLUX 1.1 [pro], Ideogram V3 | 1 |
Recraft V4 (fal-ai/recraft/v4/text-to-image) | 0 (생성 전용 — input_images 미지원) |
이미지 모델은
/chat/completions로 호출할 수 없습니다. 시도하면 404 invalid_request_error - Model '<name>' not found가 반환됩니다. 이미지는 반드시 /v1/gateway/images/generate/를 사용하세요.curl
Python
응답 — 동기 제공업체 (Google)
Fal/Replicate 등 비동기 제공업체는 결과가 바로 반환되지 않습니다.
operation_id를 사용하여 상태를 폴링해야 합니다. 아래 비동기 응답 섹션을 참고해주세요.응답 — 비동기 제공업체 (Fal, Replicate)
GET /v1/gateway/images/generate/{operation_id}/?model=<model_name>으로 status가 "completed"가 될 때까지 폴링하세요.예제
curl
Python
Python — 비동기 제공업체 (Fal/Replicate)
JavaScript
제공업체 참고
| 제공업체 | 동기/비동기 | URL 유형 | 비고 |
|---|---|---|---|
| Google (Gemini) | 동기 | Base64 인라인 | 기본 제공업체. 모델: gemini-2.5-flash-image |
| OpenAI (GPT Image) | 동기 | HTTPS URL 또는 base64 | 임시 URL, 즉시 다운로드 권장 |
| Fal | 비동기 | HTTPS CDN URL | 폴링 필요 |
| Replicate | 비동기 | HTTPS URL | 폴링 필요 |
사용 가능한 모델
조직에서 사용 가능한 모델의 라이브 목록을 확인하려면 잘못된
model 값으로 POST /v1/gateway/images/generate/를 호출하세요 — 404 응답의 detail 필드에 Available models: [...] 가 포함되어 반환됩니다.OpenAI (동기)
| 모델 | 크레딧/이미지 | 주요 파라미터 |
|---|---|---|
gpt-image-2 | 53 | size, quality (low/medium/high), background (auto/opaque) |
gpt-image-1.5 | 39 | size, quality (low/medium/high), background (auto/transparent/opaque) |
gpt-image-1 | 42 | size, quality (low/medium/high), background |
gpt-image-1-mini | 8 | size, quality (low/medium/high), background |
Google (동기)
| 모델 | 크레딧/이미지 | 주요 파라미터 |
|---|---|---|
gemini-3.1-flash-image-preview (Nano Banana 2) | 69 | aspect_ratio, image_size (1K/2K/4K), number_of_images (최대 4) |
gemini-3-pro-image-preview (Nano Banana Pro) | 140 | aspect_ratio, image_size (1K/2K/4K), number_of_images (최대 4) |
gemini-3.1-flash-lite-image (Nano Banana 2 Lite) | 34 | aspect_ratio, image_size, input_images (최대 14) |
gemini-2.5-flash-image (Nano Banana) | 39 | aspect_ratio, number_of_images (최대 4) |
Replicate (비동기 — 폴링 필요)
| 모델 | 크레딧/이미지 | 주요 파라미터 |
|---|---|---|
black-forest-labs/flux-2-pro | 30 | aspect_ratio, resolution (1MP/2MP/4MP) |
black-forest-labs/flux-1.1-pro | 40 | aspect_ratio |
bytedance/seedream-4 | 30 | aspect_ratio, size (1K/2K/4K) |
bytedance/seedream-5-pro (Seedream 5.0 Pro) | 90 | image_size, aspect_ratio, input_images (최대 10) |
runwayml/gen4-image | 80 | aspect_ratio, resolution (720p/1080p) |
stability-ai/sdxl | 5 | — |
Fal (비동기 — 폴링 필요)
| 모델 | 크레딧/이미지 | 주요 파라미터 |
|---|---|---|
fal-ai/bytedance/seedream/v5/lite (Seedream 5.0 Lite) | 35 | image_size, aspect_ratio |
fal-ai/bytedance/seedream/v4.5 (Seedream 4.5) | 40 | image_size (square/landscape/portrait/2K/4K) |
fal-ai/ideogram/v3 (Ideogram V3) | 60 | aspect_ratio |
fal-ai/recraft/v4/text-to-image (Recraft V4) | 40 | aspect_ratio (생성 전용, 편집 미지원) |
xai/grok-imagine-image (Grok Imagine) | 20 | aspect_ratio |
조직에 따라 일부 모델이 활성화되지 않을 수 있습니다. 활성화되지 않은 모델을 사용하면
403 에러가 반환됩니다 — 관리자에게 문의하세요.마지막 수정 날짜: Aug 25, 2026