> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Flux Kontext 이미지 생성

>  - 비동기 처리 모드로, 후속 조회에 사용할 작업 ID를 반환합니다
- Pro와 Max 모두 텍스트 기반 이미지 생성 및 참조 이미지 편집을 지원합니다
- 생성 결과의 expires_at은 이미지 링크의 만료 시각을 나타냅니다 

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/v1/images/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "flux-kontext-pro",
      "prompt": "머리 색깔을 파란색으로 변경",
      "image_urls": ["https://upload.apimart.ai/f/models/9998230420418352-159728fe-5ae8-4330-857a-a84c034d8d21-flux-kontext-pro.webp"],
      "size": "16:9"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.apimart.ai/v1/images/generations"

  payload = {
      "model": "flux-kontext-pro",
      "prompt": "머리 색깔을 파란색으로 변경",
      "image_urls": ["https://upload.apimart.ai/f/models/9998230420418352-159728fe-5ae8-4330-857a-a84c034d8d21-flux-kontext-pro.webp"],
      "size": "16:9"
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://api.apimart.ai/v1/images/generations";

  const payload = {
    model: "flux-kontext-pro",
    prompt: "머리 색깔을 파란색으로 변경",
    image_urls: ["https://upload.apimart.ai/f/models/9998230420418352-159728fe-5ae8-4330-857a-a84c034d8d21-flux-kontext-pro.webp"],
    size: "16:9"
  };

  const headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  };

  fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload)
  })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2"
      }
    ]
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "인증에 실패했습니다. API 키를 확인하세요",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "계정 잔액이 부족합니다. 충전 후 다시 시도하세요",
      "type": "payment_required"
    }
  }
  ```
</ResponseExample>

## 지원 모델

| 모델명                | 설명                                  |
| ------------------ | ----------------------------------- |
| `flux-kontext-pro` | Flux Kontext Pro 이미지 생성 및 편집 모델     |
| `flux-kontext-max` | Flux Kontext Max 고품질 이미지 생성 및 편집 모델 |

## 인증

<ParamField header="Authorization" type="string" required>
  모든 엔드포인트에는 Bearer Token 인증이 필요합니다

  API Key 받기:

  [API Key 관리 페이지](https://apimart.ai/keys)에서 API Key를 받으세요

  요청 헤더에 다음 값을 추가합니다:

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" required>
  모델 이름

  * `flux-kontext-pro` - Kontext Pro 이미지 생성 및 편집 모델
  * `flux-kontext-max` - Kontext Max 고품질 이미지 생성 및 편집 모델
</ParamField>

<ParamField body="prompt" type="string" required>
  이미지 생성 또는 편집 내용을 설명하는 텍스트입니다.
</ParamField>

<ParamField body="image_urls" type="array">
  참조 이미지 목록입니다. 생략하면 텍스트로 이미지를 생성하고, 지정하면 이미지를 편집합니다.

  **제한:**

  * 최대 4장의 이미지 지원
  * 공개적으로 접근 가능한 URL 또는 Base64로 인코딩된 입력 이미지 지원
  * 출력 이미지와 모든 참조 이미지의 총 픽셀 수는 9MP를 초과할 수 없음
</ParamField>

<ParamField body="size" type="string" default="1:1">
  이미지 가로세로 비율

  지원되는 가로세로 비율:

  * `1:1` - 정사각형(기본값)
  * `4:3` - 가로 4:3
  * `3:4` - 세로 3:4
  * `16:9` - 가로 와이드스크린
  * `9:16` - 세로
  * `3:2` - 가로 3:2
  * `2:3` - 세로 2:3
  * `21:9` - 울트라 와이드
  * `9:21` - 울트라 톨

  `1024x1536` 같은 픽셀 문자열은 가장 가까운 지원 비율로 매핑되며 정확한 픽셀 크기로 출력되지 않습니다. Kontext는 `width`와 `height`를 지원하지 않으며 전달하면 작업이 실패합니다. `resolution`은 Kontext에서 효과가 없고 출력은 약 1MP입니다.
</ParamField>

<ParamField body="output_format" type="string" default="png">
  출력 이미지 인코딩 형식

  * `png` - PNG 형식(기본값)
  * `jpeg` - JPEG 형식
  * `webp` - WebP 형식
</ParamField>

<ParamField body="response_format" type="string">
  응답 형식 호환 매개변수입니다. 허용 값은 `url`과 `b64_json`입니다. 이미지 인코딩 형식은 변경하지 않으며 이미지 형식에는 `output_format`이 우선 적용됩니다.
</ParamField>

<ParamField body="n" type="integer" default="1">
  생성할 이미지 수입니다. 값은 반드시 `1`이어야 합니다. 여러 장이 필요하면 작업을 여러 번 제출하세요.
</ParamField>

<ParamField body="seed" type="integer">
  무작위 시드입니다. 동일한 시드와 다른 매개변수를 유지하면 동일한 결과를 재현할 수 있습니다. 생략하면 무작위로 생성됩니다.
</ParamField>

<ParamField body="prompt_upsampling" type="boolean" default="false">
  프롬프트 강화를 활성화할지 여부

  * `true` - 활성화
  * `false` - 비활성화(기본값)

  > `false`를 명시적으로 설정하면 프롬프트 재작성을 비활성화할 수 있습니다.
</ParamField>

<ParamField body="safety_tolerance" type="integer" default="2">
  안전 허용 수준

  범위: 0\~6. 값이 높을수록 허용 수준이 높아집니다
</ParamField>

### 실제 출력 크기

| 비율     | 실제 출력 크기  |
| ------ | --------- |
| `1:1`  | 1024×1024 |
| `4:3`  | 1184×880  |
| `3:4`  | 880×1184  |
| `16:9` | 1392×752  |
| `9:16` | 752×1392  |
| `3:2`  | 1248×832  |
| `2:3`  | 832×1248  |
| `21:9` | 1568×672  |
| `9:21` | 672×1568  |

## 사용 사례 예시

**이미지 편집(입력 이미지 포함)**

```json theme={null}
{
    "model": "flux-kontext-pro",
    "prompt": "배경을 해변으로 변경",
    "image_urls": ["https://example.com/photo.jpg"],
    "size": "16:9",
    "output_format": "png"
}
```

**텍스트로 이미지 생성(입력 이미지 없음)**

```json theme={null}
{
    "model": "flux-kontext-max",
    "prompt": "파란 고양이",
    "size": "1:1",
    "seed": 12345
}
```

**다중 참조 이미지 편집**

```json theme={null}
{
    "model": "flux-kontext-max",
    "prompt": "이미지 1의 인물을 이미지 2의 장면에 배치하고 조명을 통일",
    "image_urls": [
        "https://example.com/person.jpg",
        "https://example.com/scene.jpg"
    ],
    "size": "4:3"
}
```

## Response

<ResponseField name="code" type="integer">
  응답 상태 코드
</ResponseField>

<ResponseField name="data" type="array">
  응답 데이터 배열

  <Expandable title="속성">
    <ResponseField name="status" type="string">
      작업 상태

      * `submitted` - 제출됨
    </ResponseField>

    <ResponseField name="task_id" type="string">
      후속 작업 결과 조회에 사용하는 작업 고유 식별자
    </ResponseField>
  </Expandable>
</ResponseField>

## 작업 결과 조회

제출에 성공하면 `GET /v1/tasks/{task_id}`로 작업 상태를 폴링합니다. 자세한 내용은 [작업 조회 API](/ko/api-reference/tasks/status)를 참고하세요.

### 성공 응답 예시

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2",
    "status": "completed",
    "progress": 100,
    "created": 1785133674,
    "completed": 1785133683,
    "actual_time": 9,
    "estimated_time": 15,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/xxxxxxxx-flux-kontext.png"
          ],
          "expires_at": 1785220083
        }
      ]
    }
  }
}
```

이미지 조회 경로는 `data.result.images[0].url[0]`입니다. `expires_at`은 해당 링크의 만료 시각을 나타내는 Unix 타임스탬프입니다. 만료되기 전에 이미지를 저장하세요.

### 작업 상태

| 상태                      | 의미                                 |
| ----------------------- | ---------------------------------- |
| `submitted` / `pending` | 접수 완료 또는 처리 대기 상태입니다. 폴링을 계속합니다    |
| `processing`            | 생성 중. 폴링을 계속합니다                    |
| `completed`             | 생성 성공. 결과는 `result.images`에 있습니다   |
| `failed`                | 생성 실패. `data.error.message`를 확인하세요 |

### 잘못된 모델 매개변수와 작업 실패

잘못된 모델 매개변수는 비동기로 반환됩니다. 제출 시에는 HTTP 200과 `task_id`가 반환되고, 작업을 조회하면 최종 상태가 `failed`로 바뀌며 구체적인 원인이 `data.error.message`에 표시됩니다. 따라서 작업이 최종 상태가 될 때까지 폴링해야 합니다.

```json theme={null}
{
  "code": 200,
  "data": {
    "status": "failed",
    "error": {
      "type": "task_failed",
      "code": "task_failed",
      "message": "width/height are not supported by flux-kontext-pro"
    }
  }
}
```

이 유형의 오류에서 `data.error.code`는 항상 `task_failed`이며 구체적인 원인은 `message`에 표시됩니다. 실패한 작업은 전액 환불됩니다.

## 주의사항

1. **비동기 처리**: 제출 후 `task_id`가 반환됩니다. 결과를 가져오려면 `/v1/tasks/{task_id}`를 폴링해야 합니다.
2. **참조 이미지 요구사항**: 참조 이미지는 최대 4개까지 지원하며 공개적으로 접근 가능한 이미지 URL 또는 Base64로 인코딩된 입력 이미지를 사용할 수 있습니다. 출력 이미지와 합쳐 9MP를 초과할 수 없습니다.
3. **크기 규칙**: 기본 비율은 `1:1`입니다. 픽셀 문자열은 가장 가까운 지원 비율로 매핑되고 `width`/`height`는 거부되며 `resolution`은 효과가 없습니다. Kontext 출력은 약 1MP입니다.
4. **생성 수**: `n`은 반드시 `1`이어야 하며 요청당 이미지 1장만 생성합니다.
5. **프롬프트 재작성**: `prompt_upsampling: false`를 명시적으로 설정하면 프롬프트 재작성을 비활성화할 수 있습니다.
6. **결과 링크**: 이미지 URL의 유효 기간은 해당 `expires_at` Unix 타임스탬프를 따릅니다. 만료되기 전에 저장하세요.
7. **접근할 수 없는 참조 URL**: `temporarily unavailable dependency` 메시지는 참조 이미지에 접근할 수 없다는 의미일 수 있습니다. 이 경우 URL이 공개되어 있고 접근 제한이나 만료된 서명이 없는지 먼저 확인하세요.