> ## 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로 이미지를 생성합니다

> [!NOTE]
>
> **중국 본토 사용자 안내:** 중국 본토 사용자는 `https://toapis.cn` 를 API 엔드포인트(Base URL)로 사용해 주세요. 본 문서의 예시에서 `https://toapis.com` 을 `https://toapis.cn` 로 바꿔 주세요.

* `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](https://docs.toapis.com/docs/ko/api-reference/uploads/images.md)로 업로드하세요.

## 지원 모델

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

## Authorizations

**Authorization** `string` *required*

모든 API는 Bearer Token 인증이 필요합니다.

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

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

**model** `string` *required*

모델 이름:

* `qwen-image-3.0`
* `qwen-image-3.0-pro`

**prompt** `string` *required*

이미지 설명 또는 편집 지시문입니다. 빈 문자열은 사용할 수 없습니다.

**size** `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` 사이여야 합니다. 생략하면 모델이 크기를 선택합니다.

**resolution** `string` (default: 1K)

`size`에 화면 비율을 지정했을 때의 해상도:

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

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

**n** `integer` (default: 1)

생성할 이미지 수입니다. `1`로 고정됩니다. `2` 이상이면 `400 invalid_request`가 반환됩니다.

**image\_urls** `string[]`

이미지 편집, 이미지-이미지 또는 여러 참조 이미지에 사용할 URL 배열입니다.

* 최대 3장
* URL만 지원하며 base64는 지원하지 않음
* 로컬 파일은 [이미지 업로드 API](https://docs.toapis.com/docs/ko/api-reference/uploads/images.md) 사용

**client\_business\_id** `string`

주문 번호나 내부 업무 ID입니다. 지정하면 같은 상태 조회 API에서 이 ID로 조회할 수 있습니다.

**metadata** `object`

Qwen Image 고급 파라미터입니다.

**metadata 속성**

**metadata.prompt\_extend** `boolean` (default: true)

프롬프트를 자동으로 최적화하고 확장할지 여부입니다.

**metadata.prompt\_extend\_mode** `string`

확장 모드: `direct`, 또는 텍스트-이미지 전용 `agent`. `image_urls`가 있으면 `agent`는 자동으로 `direct`가 됩니다.

**metadata.negative\_prompt** `string`

생성하지 않을 내용을 지정하는 네거티브 프롬프트입니다.

**metadata.seed** `integer`

랜덤 시드입니다. 유사한 결과에 도움을 주지만 완전히 동일한 결과를 보장하지는 않습니다.

**metadata.watermark** `boolean` (default: false)

워터마크 추가 여부입니다.

## 해상도와 픽셀 매핑

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

| 화면 비율 | 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

**id** `string`

상태 조회에 사용하는 작업 ID입니다.

**object** `string`

항상 `generation.task`입니다.

**model** `string`

사용한 모델입니다.

**status** `string`

`queued`, `in_progress`, `completed`, `failed` 중 하나입니다.

**progress** `integer`

0-100 진행률입니다.

**created\_at** `integer`

Unix 타임스탬프 형식의 생성 시간입니다.

## 요청 예시

```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
  }'
```

## 제출 성공 응답

```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>'
```

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

```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` 전에 다운로드하거나 저장하세요.

## 요금

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.