> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# 이미지 생성
> 프롬프트를 기반으로 이미지를 생성합니다
## 개요
에이전트는 먼저 `GET /v1/models?recommended_for=image` 로 현재 추천 이미지 모델 후보를 확인한 뒤, 선택한 `model` 을 이 엔드포인트에 명시적으로 전달하세요.
`gpt-image-2` 는 token 단위로 과금되는 GPT Image 모델입니다. TokenLab 는 OpenAI 공식 usage 세부 내역에 따라 텍스트 입력, 이미지 입력, 보고된 캐시 입력, 이미지 출력 token 을 정산하며, 고정 이미지 단가 모델로 처리하지 않습니다.
`gpt-image-2` 이미지 생성에서 지원되는 공개 파라미터는 `prompt`, `n`, `size`, `quality`, `response_format`, `async`, `background`, `output_format`, `output_compression` 또는 `compression`, `moderation`, `user`입니다. `size` 또는 `quality`를 생략하면 TokenLab가 `auto`를 사용합니다. 사용자 지정 `size` 값은 아래의 유연한 `WIDTHxHEIGHT` 계약을 따라야 합니다.
`input_fidelity`는 현재 TokenLab의 `gpt-image-2` 공개 계약에 포함되지 않습니다. 생략하세요. 보내면 `400 unsupported_parameter`가 반환됩니다.
### 모델 동작 참고
Google Gemini image-family 모델은 같은 선택자 계약을 공유하지 않습니다.
* `gemini-3.1-flash-image`, `gemini-3-pro-image`, `nano-banana-pro` 는 공개 text-to-image 및 image-edit/image-to-image 작업에서 `aspect_ratio` 와 `resolution` (`1k`, `2k`, `4k`) 을 지원합니다.
* `nano-banana-2` 는 현재 TokenLab 계약에서 text-to-image에만 `aspect_ratio` 와 `resolution` (`1k`, `2k`, `4k`) 을 지원합니다.
* `gemini-2.5-flash-image`, `nano-banana`, `nano-banana-edit` 는 `aspect_ratio` 를 지원하지만 공개 `resolution` 선택은 노출하지 않습니다.
* Nano Banana 참조 이미지 요청은 이 엔드포인트(`/v1/images/generations`)에서 `nano-banana-edit` 또는 `nano-banana-pro` 를 사용하고 `operation: "image-to-image"` 와 `image_urls` 를 보내세요. Nano Banana 참조 이미지 요청을 `/v1/images/edits` 로 보내지 마세요.
* Nano Banana image-to-image 요청에서 `nano-banana-pro` 는 `resolution` (`1k`, `2k`, `4k`) 을 포함할 수 있습니다. `nano-banana-edit` 에서는 생략해야 합니다. `nano-banana` 와 `nano-banana-2` 는 현재 모델 세부정보에서 text-to-image 모델입니다.
* 이 엔드포인트의 참조 이미지는 JSON `image_url` / `image_urls` 또는 multipart `image` 파일로 보낼 수 있습니다. `/v1/images/generations` 는 `images[]` 와 `file_id` 를 받지 않습니다. `/v1/files` 참조는 `images[].file_id` 를 명시적으로 지원하는 `/v1/images/edits` 모델에서만 사용하세요.
Google 이미지 패밀리에는 `aspect_ratio` 를 우선 사용하고, 모델이 명시적으로 지원할 때만 `resolution` 을 보내세요.
xAI Grok Imagine 이미지 모델(`grok-imagine-image`, `grok-imagine-image-quality`, legacy `grok-imagine-image-pro`)은 `aspect_ratio` 와 `resolution` (`1k`, `2k`) 을 지원합니다. `grok-imagine-image-pro` 는 `grok-imagine-image-quality` 의 호환 ID로 유지됩니다.
## 요청 본문
**동기 요청 타임아웃:** 일부 이미지 요청은 생성이 완료될 때까지 기다린 뒤 최종 이미지를 inline 으로 반환합니다. 고해상도 또는 고품질 요청은 1분 안팎이거나 그 이상 걸릴 수 있으므로 HTTP 클라이언트 타임아웃을 최소 `120s` 로 설정하세요. 생성 응답에 `status: "pending"`, `task_id`, 또는 `poll_url` 이 포함되어 있으면 반환된 `poll_url` 을 따라 폴링하세요.
사용할 모델(예: `gpt-image-2`, `flux-pro`, `qwen-image-plus`, `nano-banana-pro`). 현재 추천 목록은 `GET /v1/models?recommended_for=image` 로 확인하세요.
원하는 이미지에 대한 텍스트 설명입니다.
image-to-image 생성에 사용할 공개 HTTPS 참조 이미지 URL입니다. Nano Banana 참조 이미지 요청은 `operation` 을 `image-to-image` 로 설정하세요. `nano-banana-pro` 는 `resolution` 을 포함할 수 있고, `nano-banana-edit` 는 생략해야 합니다.
공개 HTTPS 참조 이미지 URL 배열입니다. JSON 요청에서 하나 이상의 참조 이미지를 보낼 때 사용합니다. 이 엔드포인트는 `file_id` 와 `images[]` 를 지원하지 않습니다.
기본 입력 이미지와 참조 이미지를 구분하는 공급자를 위한 추가 모델별 참조 이미지 URL입니다.
image-to-image 생성을 위한 multipart 참조 이미지 파일입니다. 원본 이미지가 비공개이거나 헤더 인증이 필요할 때 직접 업로드를 사용하세요. /v1/files 의 `file_id` 와는 다르며, 이 엔드포인트는 `file_id` 를 받지 않습니다.
생성할 이미지 수입니다 (1-10, 모델에 따라 다름).
이미지 크기입니다. OpenAI 스타일 이미지 계열 및 정확한 픽셀 크기를 받는 다른 모델에 사용합니다.
`gpt-image-2` 의 `size` 는 `auto` 또는 `WIDTHxHEIGHT` 를 허용합니다. 사용자 지정 크기는 두 변이 모두 16의 배수여야 하고, 가장 긴 변은 `3840px` 이하여야 하며, 긴 변/짧은 변 비율은 `3:1` 이하여야 하고, 총 픽셀 수는 `655,360` 이상 `8,294,400` 이하이어야 합니다. `aspect_ratio` 와 `resolution` 은 현재 TokenLab 의 `gpt-image-2` 모델 세부정보에 포함되지 않습니다..
Google Gemini 이미지 계열에서는 `size` 가 호환 alias 로 처리되어 모델의 공개 `aspect_ratio` 계약과, 지원되는 경우 `resolution` 계약으로 매핑됩니다. 이 모델들에는 `aspect_ratio` 를 직접 보내는 것을 권장합니다.
모델별 종횡비 선택값입니다.
Google 이미지 패밀리에서 자주 쓰는 값은 `1:1`, `16:9`, `9:16`, `3:2`, `2:3` 입니다.
모델별 출력 해상도 선택값입니다.
`gemini-3.1-flash-image` 와 `gemini-3-pro-image` 는 text-to-image 및 image-edit에서, `nano-banana-pro` 는 text-to-image 및 image-to-image에서, `nano-banana-2` 는 text-to-image에서만 지원합니다. 일반적인 값은 `1k`, `2k`, `4k` 입니다. 모델이 명시적으로 문서화하지 않았다면 비율만 지원하는 Gemini 이미지 계열에는 보내지 마세요. xAI Grok Imagine 이미지 모델에는 `1k` 또는 `2k` 를 사용하세요.
이미지 품질입니다. `gpt-image-2` 같은 GPT Image 모델은 `auto`, `low`, `medium`, `high` 를 사용합니다. 다른 이미지 계열은 제공자별 값을 사용할 수 있으므로 기본값이 아닌 값을 보내기 전에 선택한 모델 메타데이터를 확인하세요.
응답 형식입니다: `url` 또는 `b64_json`. 기본값은 `url`입니다.
Azure Official 또는 Azure-compatible `gpt-image-2` 요청에서는 TokenLab가 이미지 결과를 `b64_json`으로 받습니다. `url` 요청에서는 각 이미지를 CDN에 업로드한 뒤 `data[].url`을 반환합니다. CDN 스토리지를 사용할 수 없거나 업로드가 실패하면 Base64 응답으로 바꾸지 않고 요청을 실패시킵니다. `b64_json` 요청에서는 원본 Base64를 반환합니다.
`gpt-image-2` 또는 공식 FLUX/BFL 이미지 모델에서 `true`로 설정하면 먼저 작업을 생성합니다. 완료된 비동기 이미지 작업은 요청한 `response_format`과 관계없이 URL을 반환합니다. `b64_json`이 필요하면 동기 요청을 사용하세요.
선택적 스타일 지정자입니다. 선택한 모델이 명시적으로 문서화한 경우에만 보내세요. 모델 메타데이터에 달리 표시되어 있지 않다면 `gpt-image-2` 에는 생략하세요.
최종 사용자를 식별하는 고유 ID입니다.
## 응답
### 동기 응답
생성 시점의 Unix timestamp입니다.
생성된 이미지 배열입니다.
각 객체는 다음을 포함합니다:
* `url` (string): 생성된 이미지의 URL
* `b64_json` (string): Base64로 인코딩된 이미지 (요청한 경우)
* `revised_prompt` (string): 선택한 모델이 반환한 선택적 프롬프트 수정본
### 비동기 작업 응답
`gpt-image-2` 또는 공식 FLUX/BFL 이미지 모델에서 `async: true`를 설정하면 생성 요청에서 최종 이미지를 기다리지 않고 작업을 생성합니다. 응답에는 `status: "pending"`, `task_id`, `poll_url`이 포함됩니다. 작업이 `completed` 또는 `failed`가 될 때까지 `/v1/tasks/{task_id}`를 폴링하세요.
비동기 이미지 작업은 최종 이미지 URL만 반환합니다. 원본 `b64_json` 이미지 데이터가 필요하면 동기 요청을 사용하세요.
작업 생성 시 예상 금액이 예약될 수 있습니다. 완료된 작업은 실제 사용량으로 정산되며, 실패하거나 시간 초과된 작업은 예약 금액이 해제되거나 환불됩니다.
생성 시각의 Unix 타임스탬프입니다.
폴링용 고유 작업 식별자.
초기 상태: `pending`.
결과를 폴링하기 위한 상대 URL이며, 예를 들어 `/v1/tasks/{id}`입니다.
작업이 pending인 동안에는 비어 있습니다. 완료된 이미지 작업은 생성된 이미지 URL을 `data[].url`에 반환합니다.
작업 결과를 받으면 `status: "pending"`일 때 `poll_url` 또는 `GET /v1/tasks/{task_id}`를 사용해 결과를 가져오세요.
```bash cURL theme={null}
curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-pro-image",
"prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill",
"aspect_ratio": "16:9",
"resolution": "2k",
"n": 1
}'
```
```python Python theme={null}
from openai import OpenAI
client = OpenAI(
api_key="sk-your-api-key",
base_url="https://api.tokenlab.sh/v1"
)
response = client.images.generate(
model="gemini-3-pro-image",
prompt="A cinematic portrait of a white cat sitting on a rainy windowsill",
aspect_ratio="16:9",
resolution="2k",
n=1
)
print(response.data[0].url)
```
```javascript JavaScript theme={null}
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: 'sk-your-api-key',
baseURL: 'https://api.tokenlab.sh/v1'
});
const response = await client.images.generate({
model: 'gemini-3-pro-image',
prompt: 'A cinematic portrait of a white cat sitting on a rainy windowsill',
aspect_ratio: '16:9',
resolution: '2k',
n: 1
});
console.log(response.data[0].url);
```
```php PHP theme={null}
true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Authorization: Bearer sk-your-api-key'
],
CURLOPT_POSTFIELDS => json_encode([
'model' => 'gemini-3-pro-image',
'prompt' => 'A cinematic portrait of a white cat sitting on a rainy windowsill',
'aspect_ratio' => '16:9',
'resolution' => '2k',
'n' => 1
])
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
echo $data['data'][0]['url'];
```
비율만 지원하는 이미지 계열 예시: `gemini-2.5-flash-image`, `nano-banana` 또는 `nano-banana-edit` 에는 `aspect_ratio` 만 보내고 `resolution` 은 생략하세요.
```json theme={null}
{
"model": "gemini-2.5-flash-image",
"prompt": "A clean editorial product shot of a citrus soda can",
"aspect_ratio": "16:9"
}
```
Nano Banana Pro 참조 이미지 예시: 요청은 `/v1/images/generations` 로 보내고 `/v1/images/edits` 로 보내지 않습니다. `resolution` 은 선택 사항이며 `1k`, `2k`, `4k` 로 설정할 수 있습니다.
```json theme={null}
{
"model": "nano-banana-pro",
"prompt": "Create a clean cinematic character image based on the reference images",
"operation": "image-to-image",
"image_urls": ["https://example.com/reference-1.png"],
"aspect_ratio": "1:1",
"resolution": "2k"
}
```
비공개 또는 로컬 원본 이미지는 multipart 로 직접 업로드할 수 있습니다. `/v1/images/generations` 에 `file_id` 를 보내지 마세요:
```bash theme={null}
curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-F "model=nano-banana-pro" \
-F "prompt=Create a clean cinematic character image based on this reference" \
-F "operation=image-to-image" \
-F "image=@reference.png" \
-F "aspect_ratio=1:1" \
-F "resolution=2k"
```
```json 동기 응답 theme={null}
{
"created": 1706000000,
"data": [
{
"url": "https://...",
"revised_prompt": "A fluffy white cat with bright eyes sitting peacefully on a wooden windowsill, watching raindrops stream down the glass window..."
}
]
}
```
```json 비동기 작업 응답 theme={null}
{
"created": 1706000000,
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"data": []
}
```
## 사용 가능한 모델
아래는 현재 예시 모델이며 고정 카탈로그가 아닙니다. 최신 제공 여부와 가격은 `GET /v1/models?recommended_for=image` 또는 Models 페이지에서 확인하세요.
| 모델 | 유형 | 기능 |
| -------------------- | ------------- | ----------------------------- |
| `gpt-image-2` | 인라인 또는 작업 기반 | 토큰 단위 과금 GPT Image 모델, 유연한 크기 |
| `flux-pro` | 작업 기반인 경우가 많음 | 사실적인 이미지, 고품질 |
| `qwen-image-plus` | 작업 기반인 경우가 많음 | 강한 텍스트 렌더링과 프롬프트 준수 |
| `nano-banana-pro` | 작업 기반인 경우가 많음 | 참조 이미지 워크플로와 고해상도 출력 |
| `grok-imagine-image` | 작업 기반인 경우가 많음 | xAI 이미지 생성, 종횡비와 해상도 선택 지원 |
| `ideogram-v3` | 작업 기반인 경우가 많음 | 강한 텍스트 렌더링 |
모델이 항상 동기 또는 항상 비동기라고 하드코딩하지 마세요. 생성 응답이 `status: "pending"` 를 반환하면 `poll_url` 을 따라 완료될 때까지 조회하세요.
## 비동기 응답 처리
이미지 모델의 경우 응답에 `status: "pending"` 이 포함되어 있는지 항상 확인하세요: