> ## 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.

# 이미지 생성

> 올바른 TokenLab 이미지 엔드포인트를 선택하고, 모델 인식 요청을 전송하며, 동기 또는 비동기 이미지 결과를 안전하게 처리합니다.

TokenLab은 공용 이미지 엔드포인트를 통해 텍스트-투-이미지, 이미지-투-이미지 및 이미지 편집을 지원합니다. 이미지 모델은 하나의 보편적인 매개변수 집합을 공유하지 않으므로, 프로덕션 클라이언트는 먼저 엔드포인트를 선택한 다음 모델을 선택하고, 해당 모델에서 지원하는 필드만 전송해야 합니다.

## 각 엔드포인트 사용 시기

| 사용자 워크플로우 | 엔드포인트                         | 사용 시                                                                                                          | 피해야 할 시                         |
| --------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| 텍스트-투-이미지 | `POST /v1/images/generations` | 사용자가 프롬프트만으로 시작할 때                                                                                            | 공식 GPT 이미지 편집 흐름이 필요할 때         |
| 이미지-투-이미지 | `POST /v1/images/generations` | 모델 문서가 `operation: "image-to-image"`와 `image_url`, `image_urls`, 또는 `reference_image_urls`를 통해 참조 이미지를 문서화할 때 | 모델이 멀티파트 편집 입력을 기대할 때           |
| 이미지 편집    | `POST /v1/images/edits`       | GPT 이미지 패밀리 모델과 같은 지원되는 편집 모델로 기존 이미지를 편집할 때                                                                  | 나노 바나나 스타일의 이미지-투-이미지 생성을 사용할 때 |
| 변형        | `POST /v1/images/variations`  | 레거시 변형 호환 통합을 유지할 때                                                                                           | 새로운 참조 이미지 워크플로우를 구축할 때         |
| 상태        | `GET /v1/tasks/{id}`          | 생성 응답이 `task_id`, `status: "pending"`, 또는 `poll_url`을 반환할 때                                                   | 생성 응답이 이미 최종 `data[]`를 포함할 때    |

항상 `model`을 전송하십시오. 이미지 엔드포인트는 의도적으로 프로덕션 트래픽에 대한 역사적 암묵적 기본 모델에 의존하지 않습니다.

## 모델 선택

모델 발견으로 시작한 다음 선택한 모델의 TokenLab 계약을 검사하십시오:

```bash theme={null}
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"
```

비채팅 모델의 경우, 목록 응답에는 `tokenlab.public_contract_summary`가 포함될 수 있습니다. 모델 세부 페이지는 더 완전한 `tokenlab.public_contract`를 노출할 수 있습니다. 이러한 필드를 사용하여 확인하십시오:

* 지원되는 작업, 예를 들어 `text-to-image`, `image-to-image`, 또는 `image-edit`.
* 모델이 예상하는 요청 엔드포인트.
* 참조에 사용할 모양, 예를 들어 `image_url`, `image_urls`, `reference_image_urls`, 멀티파트 `image`, 또는 JSON `images[]`.
* 모델이 `size`, `aspect_ratio`, `resolution`, `quality`, `background`, `output_format`, 또는 `response_format`을 수용하는지 여부.

## 요청 형식 규칙

* `gpt-image-2` 스타일 요청은 OpenAI와 유사한 `size`, `quality`, 및 편집 필드를 사용합니다. 모델이나 TokenLab이 자동 기본값을 사용하도록 하려면 선택적 필드를 생략하십시오.
* 제미니 및 나노 바나나 이미지 패밀리는 일반적으로 `aspect_ratio`를 사용합니다; 모델 계약이 이를 노출할 때만 `resolution`을 전송하십시오.
* 나노 바나나 이미지-투-이미지는 `/v1/images/generations`에서 `operation: "image-to-image"` 및 참조 이미지 URL과 함께 사용해야 합니다.
* `/v1/images/generations`는 최상위 `images[]` 또는 `file_id`를 수용하지 않습니다; 이는 편집 흐름 형식입니다.
* 원격 이미지 참조는 공개 `http` 또는 `https` URL이어야 합니다. 개인 네트워크 URL, 내장된 자격 증명, URL 조각, 또는 처리 시작 전에 만료될 수 있는 서명된 URL을 전송하지 마십시오.

## 텍스트-투-이미지 예제

```bash theme={null}
curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "호두 나무 책상 위에 있는 세라믹 커피 컵의 깔끔한 제품 사진",
    "size": "1024x1024",
    "response_format": "url"
  }'
```

## 참조 이미지 예제

```bash theme={null}
curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana",
    "operation": "image-to-image",
    "prompt": "제품 모양을 유지하고 배경을 밝은 스튜디오 설정으로 변경",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'
```

## 결과 처리

이미지 응답은 동기 또는 비동기일 수 있습니다:

* 동기 응답은 최종 `data[]`를 `url` 또는 `b64_json`과 함께 반환합니다.
* 비동기 응답은 `id`, `task_id`, `status`, 및 일반적으로 `poll_url`을 반환합니다.
* `poll_url`이 있을 때 이를 선호하십시오. 고정 경로가 필요하면 `GET /v1/tasks/{id}`를 폴링하십시오.
* `b64_json`이 필요할 때는 동기 요청을 사용하십시오; 비동기 이미지 결과는 URL 지향적입니다.

```bash theme={null}
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"
```

반환된 이미지 URL, 작업 ID, 모델 및 귀하의 사용자/작업 ID를 유지하십시오. 최종 상태 이후에는 계속 폴링하지 마십시오.

## 프로덕션 체크리스트

* TokenLab을 호출하기 전에 사용자 입력을 검증하십시오: 프롬프트 길이, 이미지 수, URL 도달 가능성, 및 파일 유형.
* 동기 고해상도 요청을 위해 HTTP 타임아웃을 충분히 높게 설정하십시오. 긴 작업을 위해 사용 가능한 경우 비동기 모드를 사용하십시오.
* 지원을 위해 `request_id`, `task_id`, `poll_url`, 모델, 엔드포인트, 및 정제된 요청 형식을 저장하십시오.
* 클라이언트 타임아웃 시, 생성 요청을 재시도하기 전에 작업이 생성되었는지 확인하십시오.
* 제공자 작업 ID가 아닌 사용 기록 및 `billing_transaction_id`와 비용을 조정하십시오.

## 일반적인 오류

| 증상                       | 가능한 원인                     | 수정 방법                                                    |
| ------------------------ | -------------------------- | -------------------------------------------------------- |
| `400` 및 `param: "model"` | 명시적 모델 누락                  | `/v1/models?recommended_for=image`를 쿼리하고 `model`을 전송하십시오 |
| 지원되지 않는 필드               | 해당 모델의 공개 계약에 필드가 없음       | 필드를 제거하거나 이를 문서화한 모델/엔드포인트를 선택하십시오                       |
| 비동기 결과에서 `b64_json` 없음   | 비동기 이미지 작업은 URL 지향적 결과를 반환 | base64 출력을 위해 동기 모드를 사용하십시오                              |
| 참조 이미지 거부                | 잘못된 엔드포인트 또는 개인/만료된 URL    | 모델의 문서화된 참조 형식과 일치시키고 도달 가능한 URL을 사용하십시오                 |

## API 참조

| 주제          | 참조                                                       |
| ----------- | -------------------------------------------------------- |
| 이미지 생성      | [이미지 생성](/ko/api-reference/images/create-image)          |
| 이미지 편집      | [이미지 편집](/ko/api-reference/images/edit-image)            |
| 이미지 변형 생성   | [이미지 변형 생성](/ko/api-reference/images/create-variation)   |
| 이미지 상태 가져오기 | [이미지 상태 가져오기](/ko/api-reference/images/get-image-status) |
| 작업 상태 가져오기  | [작업 상태 가져오기](/ko/api-reference/tasks/get-task-status)    |