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

# Qwen Image 3.0 이미지 생성

>  - 비동기 처리 모드, 후속 조회를 위한 작업 ID 반환
- 텍스트-이미지, 이미지-이미지(1-3장 참조 이미지 편집) 지원
- 1K / 2K 해상도 지원, 요청당 최대 6장
- 표준 및 Pro 변형(Pro는 밀집 레이아웃과 텍스트에 더 강함) 

<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": "qwen-image-3.0",
      "prompt": "A cafe poster with the title Autumn Limited, warm tones, refined layout",
      "size": "16:9",
      "resolution": "1K"
    }'
  ```

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

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

  payload = {
      "model": "qwen-image-3.0",
      "prompt": "A cafe poster with the title Autumn Limited, warm tones, refined layout",
      "size": "16:9",
      "resolution": "1K",
  }

  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: "qwen-image-3.0",
    prompt: "A cafe poster with the title Autumn Limited, warm tones, refined layout",
    size: "16:9",
    resolution: "1K",
  };

  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_01JGXYZ1234567890ABCDEF"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": 400,
      "message": "잘못된 요청 매개변수입니다",
      "type": "invalid_request_error"
    }
  }
  ```

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

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "잔액이 부족합니다. 충전 후 다시 시도해주세요",
      "type": "payment_required"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": 429,
      "message": "요청이 너무 많습니다. 잠시 후 다시 시도해주세요",
      "type": "rate_limit_error"
    }
  }
  ```
</ResponseExample>

## 지원 모델

| 모델                   | 설명                                        | 최대 장수 | 해상도     |
| -------------------- | ----------------------------------------- | ----- | ------- |
| `qwen-image-3.0`     | 지시 이해가 명확하고 텍스트 렌더링이 안정적, 일반 용도에 가성비 좋음   | 6     | 1K / 2K |
| `qwen-image-3.0-pro` | 콘텐츠가 더 풍부함, 신문·스토리보드·메뉴·시험지 등 밀집 레이아웃에 최적 | 6     | 1K / 2K |

<Tip>
  밀집 텍스트/레이아웃에는 `-pro`를 권장합니다. 일반 이미지는 `qwen-image-3.0`을 사용하세요. 프롬프트 최대 약 **4.5k 토큰**. 모델명은 2.0 시리즈와 호환되지 않습니다.
</Tip>

## Authorizations

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

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

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

## Body

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

  * `qwen-image-3.0` - 표준
  * `qwen-image-3.0-pro` - Pro (밀집 텍스트 / 레이아웃)
</ParamField>

<ParamField body="prompt" type="string" required>
  이미지 생성용 텍스트 설명, 최대 약 **4.5k 토큰**
</ParamField>

<ParamField body="image_urls" type="string[]">
  참조 이미지 URL 배열 (이미지-이미지 / 편집), **1-3장**

  * 공개 `http(s)://` URL 또는 `data:image/png;base64,...` (base64는 먼저 재업로드됨)
  * 형식: JPG / JPEG / PNG / BMP / TIFF / WEBP / GIF
  * 파일당 ≤ 10MB, 너비/높이는 384-2048 px 권장
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  해상도 등급 (과금 등급에 영향)

  * `1K` (기본값, 소문자 허용)
  * `2K`

  등급을 생략하고 `size`에 픽셀을 직접 전달할 수 있습니다 (예: `1600x900`). 원시 픽셀 사용 시 면적 **> 2.25M 픽셀**이면 2K로 과금됩니다.
</ParamField>

<ParamField body="size" type="string" default="1:1">
  종횡비 또는 명시적 픽셀 크기

  지원 비율:

  * `1:1` (기본값)
  * `4:3` / `3:4`
  * `16:9` / `9:16`
  * `3:2` / `2:3`

  `16x9` 형식 또는 `1024x1024` 같은 픽셀도 허용. 커스텀 픽셀일 때 **각 변**(너비·높이)은 **512 \~ 2048**, 종횡비 1:8 \~ 8:1.

  `size`와 `resolution`을 모두 설정하지 않으면 출력은 **1024×1024**로 고정됩니다.
</ParamField>

<ParamField body="n" type="integer" default="1">
  이미지 수, **1-6**. 6을 초과하면 6으로 클램프됩니다.
</ParamField>

<ParamField body="negative_prompt" type="string">
  네거티브 프롬프트: 피하고 싶은 내용
</ParamField>

<ParamField body="prompt_extend" type="boolean" default="false">
  지능형 프롬프트 재작성

  기본값은 **꺼짐** (결과 예측 가능성 유지). 지능형 재작성을 쓰려면 `true`로 설정하세요.
</ParamField>

<ParamField body="prompt_extend_mode" type="string">
  재작성 모드 (3.0 시리즈만, `prompt_extend: true` 필요)

  * `direct` - 텍스트-이미지 및 이미지-이미지 모두 가능
  * `agent` - **텍스트-이미지만**, 더 적극적인 재작성

  잘못된 값은 무시됩니다.
</ParamField>

## 크기 참조표

`resolution`(등급) + `size`(비율) 조합:

| 해상도    | 1:1       | 4:3       | 3:4       | 16:9      | 9:16      | 3:2       | 2:3       |
| ------ | --------- | --------- | --------- | --------- | --------- | --------- | --------- |
| **1K** | 1024×1024 | 1152×864  | 864×1152  | 1280×720  | 720×1280  | 1248×832  | 832×1248  |
| **2K** | 2048×2048 | 2048×1536 | 1536×2048 | 2048×1152 | 1152×2048 | 2048×1360 | 1360×2048 |

## 사용 사례

### 텍스트-이미지 (여러 장)

```json theme={null}
{
  "model": "qwen-image-3.0",
  "prompt": "Flat illustration of a city skyline at dusk, warm orange tones",
  "size": "16:9",
  "resolution": "1K",
  "n": 4
}
```

### 밀집 레이아웃 + 재작성

```json theme={null}
{
  "model": "qwen-image-3.0-pro",
  "prompt": "A Western restaurant menu with appetizers, mains, and desserts columns, five dishes each with prices, serif font, cream background",
  "size": "3:4",
  "resolution": "2K",
  "prompt_extend": true,
  "prompt_extend_mode": "agent"
}
```

### 이미지-이미지 (편집)

```json theme={null}
{
  "model": "qwen-image-3.0-pro",
  "prompt": "Change the sign text to Open, keep everything else the same",
  "image_urls": ["https://example.com/shop.jpg"],
  "size": "1:1"
}
```

### 네거티브 프롬프트

```json theme={null}
{
  "model": "qwen-image-3.0",
  "prompt": "Photorealistic mountain cabin in morning mist",
  "negative_prompt": "text, watermark, people, low resolution",
  "size": "3:2"
}
```

## 제한

| 항목     | 제한                                         |
| ------ | ------------------------------------------ |
| 프롬프트   | ≤ 4.5k 토큰                                  |
| 출력 크기  | 커스텀 픽셀 시 각 변 512 \~ 2048; 종횡비 1:8 \~ 8:1   |
| 이미지 수  | 1-6 (초과분 클램프)                              |
| 참조 이미지 | 1-3                                        |
| 참조 형식  | JPG / JPEG / PNG / BMP / TIFF / WEBP / GIF |
| 참조 크기  | ≤ 10MB, 너비/높이 384-2048 px 권장               |

## Response

<ResponseField name="code" type="integer">
  상태 코드, 성공 시 200
</ResponseField>

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

  <Expandable title="속성">
    <ResponseField name="status" type="string">
      작업 상태, 생성 시 `submitted`
    </ResponseField>

    <ResponseField name="task_id" type="string">
      결과 폴링용 작업 ID
    </ResponseField>
  </Expandable>
</ResponseField>

## 2.0과의 차이

|                      | 2.0 시리즈 | 3.0 시리즈                    |
| -------------------- | ------- | -------------------------- |
| 프롬프트 길이              | 더 짧음    | 약 4.5k 토큰                  |
| `prompt_extend_mode` | 미지원     | `direct` / `agent`         |
| 해상도                  | 1K / 2K | 1K / 2K (Pro 2K는 요금이 더 높음) |
| 참조 이미지               | 지원      | 1-3장                       |

## 참고 사항

1. **비동기**: 제출 후 `task_id`가 반환됩니다. [작업 상태 조회](/ko/api-reference/tasks/status)를 **3\~5초**마다 폴링하세요. 클라이언트 타임아웃 약 **3분** (2K + 다중 이미지는 더 느림).
2. **저장**: 이미지는 플랫폼 CDN에 미러되어 장기 접근 가능합니다.
3. **과금**: 납품 이미지 수 × 해상도 등급. **실제 픽셀 면적** 기준 (> 2.25M 픽셀 = 2K). `qwen-image-3.0`은 1K/2K 동일 요금, `-pro` 2K는 1K의 2배. 실패 시 전액 환불, 참조 이미지는 무료.
4. **오류**: 잘못된 size/비율, 이미지-이미지에서 `agent`, 접근 불가/과대 참조 이미지 → 400, 속도 제한 → 429.

<Note>
  **결과 조회**

  진행 상황과 `result.images`는 [작업 상태 조회](/ko/api-reference/tasks/status)를 사용하세요.
</Note>