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

# Qwen Image 3.0 이미지 생성

> qwen-image-3.0 또는 qwen-image-3.0-pro로 이미지를 생성합니다

* `qwen-image-3.0`, `qwen-image-3.0-pro` 지원
* 텍스트-이미지, 이미지-이미지, 여러 참조 이미지 생성 지원
* 참조 이미지는 최대 3장
* 1K / 2K 해상도와 7가지 화면 비율 지원
* 요청당 이미지 1장만 생성하며 `n`은 `1`로 고정
* 비동기 작업으로 실행되고 작업 ID로 결과 조회

<Warning>
  `image_urls`에는 공개적으로 접근 가능한 이미지 URL만 사용할 수 있습니다. base64 Data URI는 지원하지 않습니다. 로컬 파일은 먼저 [이미지 업로드 API](../../uploads/images)로 업로드하세요.
</Warning>

## 지원 모델

| 모델                   | 텍스트-이미지 | 이미지-이미지 | 참조 이미지 | 출력    |
| -------------------- | ------- | ------- | ------ | ----- |
| `qwen-image-3.0`     | 지원      | 지원      | 최대 3장  | 1장 고정 |
| `qwen-image-3.0-pro` | 지원      | 지원      | 최대 3장  | 1장 고정 |

## Authorizations

<ParamField header="Authorization" type="string" required>
  모든 API는 Bearer Token 인증이 필요합니다.

  [API Key 관리 페이지](https://toapis.com/console/token)에서 키를 발급받고 다음 헤더로 전송하세요.

  ```text theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

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

  * `qwen-image-3.0`
  * `qwen-image-3.0-pro`
</ParamField>

<ParamField body="prompt" type="string" required>
  이미지 설명 또는 편집 지시문입니다. 빈 문자열은 사용할 수 없습니다.
</ParamField>

<ParamField body="size" type="string">
  출력 이미지의 화면 비율:

  `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`

  `WIDTH*HEIGHT` 또는 `WIDTHxHEIGHT` 픽셀 형식도 지원합니다. 전체 픽셀 면적은 `512*512`에서 `2048*2048` 사이이고 화면 비율은 `1:8`에서 `8:1` 사이여야 합니다. 생략하면 모델이 크기를 선택합니다.
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  `size`에 화면 비율을 지정했을 때의 해상도:

  * `1K` - 기본값
  * `2K`

  `metadata.resolution`도 사용할 수 있지만 최상위 필드를 권장합니다.
</ParamField>

<ParamField body="n" type="integer" default={1}>
  생성할 이미지 수입니다. `1`로 고정됩니다. `2` 이상이면 `400 invalid_request`가 반환됩니다.
</ParamField>

<ParamField body="image_urls" type="string[]">
  이미지 편집, 이미지-이미지 또는 여러 참조 이미지에 사용할 URL 배열입니다.

  * 최대 3장
  * URL만 지원하며 base64는 지원하지 않음
  * 로컬 파일은 [이미지 업로드 API](../../uploads/images) 사용
</ParamField>

<ParamField body="client_business_id" type="string">
  주문 번호나 내부 업무 ID입니다. 지정하면 같은 상태 조회 API에서 이 ID로 조회할 수 있습니다.
</ParamField>

<ParamField body="metadata" type="object">
  Qwen Image 고급 파라미터입니다.

  <Expandable title="metadata 속성">
    <ParamField body="metadata.prompt_extend" type="boolean" default={true}>
      프롬프트를 자동으로 최적화하고 확장할지 여부입니다.
    </ParamField>

    <ParamField body="metadata.prompt_extend_mode" type="string">
      확장 모드: `direct`, 또는 텍스트-이미지 전용 `agent`. `image_urls`가 있으면 `agent`는 자동으로 `direct`가 됩니다.
    </ParamField>

    <ParamField body="metadata.negative_prompt" type="string">
      생성하지 않을 내용을 지정하는 네거티브 프롬프트입니다.
    </ParamField>

    <ParamField body="metadata.seed" type="integer">
      랜덤 시드입니다. 유사한 결과에 도움을 주지만 완전히 동일한 결과를 보장하지는 않습니다.
    </ParamField>

    <ParamField body="metadata.watermark" type="boolean" default={false}>
      워터마크 추가 여부입니다.
    </ParamField>
  </Expandable>
</ParamField>

## 해상도와 픽셀 매핑

화면 비율을 지정하면 두 모델 모두 다음 픽셀 크기로 변환됩니다.

| 화면 비율  | 1K        | 2K        |
| ------ | --------- | --------- |
| `1:1`  | 1024×1024 | 2048×2048 |
| `4:3`  | 1152×864  | 1600×1200 |
| `3:4`  | 864×1152  | 1200×1600 |
| `16:9` | 1280×720  | 1920×1080 |
| `9:16` | 720×1280  | 1080×1920 |
| `3:2`  | 1152×768  | 1728×1152 |
| `2:3`  | 768×1152  | 1152×1728 |

## Response

<ResponseField name="id" type="string">상태 조회에 사용하는 작업 ID입니다.</ResponseField>
<ResponseField name="object" type="string">항상 `generation.task`입니다.</ResponseField>
<ResponseField name="model" type="string">사용한 모델입니다.</ResponseField>
<ResponseField name="status" type="string">`queued`, `in_progress`, `completed`, `failed` 중 하나입니다.</ResponseField>
<ResponseField name="progress" type="integer">0-100 진행률입니다.</ResponseField>
<ResponseField name="created_at" type="integer">Unix 타임스탬프 형식의 생성 시간입니다.</ResponseField>

## 요청 예시

<RequestExample>
  ```bash cURL (텍스트-이미지) theme={null}
  curl --request POST \
    --url https://toapis.com/v1/images/generations \
    --header 'Authorization: Bearer <YOUR_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "qwen-image-3.0",
      "prompt": "구름 위 고대 도시, 황금빛 아침, 영화 포스터 구도, 선명한 한국어 제목",
      "size": "16:9",
      "resolution": "2K",
      "n": 1,
      "metadata": {
        "prompt_extend": true,
        "negative_prompt": "흐림, 낮은 품질, 잘못된 문자",
        "watermark": false
      }
    }'
  ```

  ```bash cURL (여러 참조 이미지) theme={null}
  curl --request POST \
    --url https://toapis.com/v1/images/generations \
    --header 'Authorization: Bearer <YOUR_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "qwen-image-3.0-pro",
      "prompt": "첫 번째 이미지의 인물과 두 번째 이미지의 의상을 유지하고 현대적인 잡지 표지를 만드세요",
      "image_urls": [
        "https://example.com/person.png",
        "https://example.com/outfit.png"
      ],
      "size": "3:4",
      "resolution": "2K",
      "n": 1
    }'
  ```
</RequestExample>

## 제출 성공 응답

```json theme={null}
{
  "id": "task_img_abc123def456",
  "object": "generation.task",
  "model": "qwen-image-3.0-pro",
  "status": "queued",
  "progress": 0,
  "created_at": 1787270400
}
```

## 작업 조회

```bash theme={null}
curl --request GET \
  --url https://toapis.com/v1/images/generations/task_img_abc123def456 \
  --header 'Authorization: Bearer <YOUR_API_KEY>'
```

자세한 응답 필드와 폴링 방법은 [이미지 작업 상태 조회](../../tasks/image-status)를 참고하세요.

```json theme={null}
{
  "id": "task_img_abc123def456",
  "object": "generation.task",
  "model": "qwen-image-3.0-pro",
  "status": "completed",
  "progress": 100,
  "result": {
    "type": "image",
    "data": [
      { "url": "https://files.toapis.com/generated/qwen-image-result.png" }
    ]
  }
}
```

<Warning>생성된 이미지 URL은 24시간 동안 유효합니다. `expires_at` 전에 다운로드하거나 저장하세요.</Warning>

## 요금

* 성공한 출력: 요청당 `$0.03`
* 참조 이미지: 이미지당 `$0.003`
* 참조 이미지 무료 제공량 없음
* 두 모델은 현재 동일한 요금 규칙을 사용합니다