# Qwen Image 2.0 API

Alibaba Qwen이 제공하는 Qwen Image 2.0 모델의 완전한 API 레퍼런스.

## 모델 변형

이 API는 네 가지 모델 변형을 지원합니다:

| 모델 | ID | 설명 |
|-------|-----|-------------|
| **Qwen Image 2** | `qwen-image-2.0` | 텍스트에서 이미지 생성 |
| **Qwen Image 2 Edit** | `qwen-image-2.0-edit` | 이미지 편집 및 다중 이미지 합성 |
| **Qwen Image 2 Pro** | `qwen-image-2.0-pro` | 더 높은 품질의 출력을 제공하는 향상된 텍스트에서 이미지 생성 |
| **Qwen Image 2 Pro Edit** | `qwen-image-2.0-pro-edit` | 향상된 이미지 편집 및 다중 이미지 합성 |

## 빠른 비교

| 기능 | Standard | Pro |
|---------|----------|-----|
| 텍스트에서 이미지 | ✅ 예 | ✅ 예 |
| 이미지 편집 | ✅ 예 | ✅ 예 |
| 화면 비율 | 7가지 옵션 | 7가지 옵션 |
| 이미지 입력（편집） | ✅ 예（1~6장） | ✅ 예（1~6장） |
| 다중 이미지 지원 | ✅ 예 | ✅ 예 |
| 출력 품질 | 표준 | 향상됨 |

| 기능 | Text-to-Image | Edit |
|---------|---------------|------|
| 입력 | 텍스트 프롬프트 | 이미지 + 텍스트 프롬프트 |
| 이미지 입력 | ❌ 아니오 | ✅ 예（1~6장） |
| 다중 이미지 지원 | ❌ 아니오 | ✅ 예 |
| Seed 지원 | ✅ 선택 사항 | ✅ 선택 사항 |

### 지원되는 화면 비율

Standard 및 Pro 모델 모두 7가지 화면 비율을 지원합니다:
- `16:9`（기본값）、`9:16`、`1:1`、`4:3`、`3:4`、`3:2`、`2:3`

## Qwen Image 2（텍스트에서 이미지）

### 엔드포인트

```
POST /api/v1/image/task
```

### 인증

```
Authorization: Bearer YOUR_API_KEY
```

### 요청 파라미터

#### 필수

| 파라미터 | 타입 | 설명 |
|-----------|------|-------------|
| `model_name` | string | `"qwen-image-2.0"` 이어야 합니다 |
| `prompt` | string | 이미지 생성 프롬프트 |
| `width` | number | 너비 비율 값（예: 16:9의 경우 16） |
| `height` | number | 높이 비율 값（예: 16:9의 경우 9） |

**참고:** width:height 비율은 다음 중 하나여야 합니다: `16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`3:2`、`2:3`

#### 선택 사항

| 파라미터 | 타입 | 설명 |
|-----------|------|-------------|
| `seed` | number | 재현 가능한 결과를 위한 랜덤 시드 |

### 요청 예시

```javascript
const response = await fetch('https://api.flaq.ai/api/v1/image/task', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model_name: 'qwen-image-2.0',
    prompt: 'A serene mountain landscape at sunset',
    width: 16,
    height: 9
  })
});

const { data } = await response.json();
const taskId = data.task_id;

// Poll for results
const pollResponse = await fetch(
  `https://api.flaq.ai/api/v1/image/${taskId}`,
  {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }
);

const result = await pollResponse.json();
console.log(result.data.task_result.images[0].url);
```

## Qwen Image 2 Edit（이미지 편집）

### 엔드포인트

```
POST /api/v1/image/task
```

### 요청 파라미터

#### 필수

| 파라미터 | 타입 | 설명 |
|-----------|------|-------------|
| `model_name` | string | `"qwen-image-2.0-edit"` 이어야 합니다 |
| `prompt` | string | 원하는 편집 내용 설명 |
| `width` | number | 너비 비율 값（예: 16:9의 경우 16） |
| `height` | number | 높이 비율 값（예: 16:9의 경우 9） |
| `image_url_list` | string[] | Array of input image URLs (1-6 items) |

**참고:** width:height 비율은 다음 중 하나여야 합니다: `16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`3:2`、`2:3`

#### 선택 사항

| 파라미터 | 타입 | 설명 |
|-----------|------|-------------|
| `seed` | number | 재현 가능한 결과를 위한 랜덤 시드 |

### 단일 이미지 편집 예시

```javascript
{
  model_name: 'qwen-image-2.0-edit',
  prompt: 'Change the sky to sunset colors',
  width: 16,
  height: 9,
  image_url_list: ['https://example.com/image.jpg']
}
```

### 다중 이미지 합성 예시

단일 요청에서 최대 6장의 이미지를 결합할 수 있습니다:

```javascript
{
  model_name: 'qwen-image-2.0-edit',
  prompt: 'Combine these images into a cohesive landscape',
  width: 16,
  height: 9,
  image_url_list: ['https://example.com/image1.jpg', 'https://example.com/image2.jpg', 'https://example.com/image3.jpg']
}
```

## Qwen Image 2 Pro（텍스트에서 이미지）

Qwen Image 2와 동일한 파라미터를 사용하며, 향상된 출력 품질을 위해 `model_name`을 `qwen-image-2.0-pro`로 설정합니다.

### 요청 예시

```javascript
const response = await fetch('https://api.flaq.ai/api/v1/image/task', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model_name: 'qwen-image-2.0-pro',
    prompt: 'A serene mountain landscape at sunset',
    width: 16,
    height: 9
  })
});

const { data } = await response.json();
const taskId = data.task_id;
```

## Qwen Image 2 Pro Edit（이미지 편집）

Qwen Image 2 Edit와 동일한 파라미터를 사용하며, 향상된 출력 품질을 위해 `model_name`을 `qwen-image-2.0-pro-edit`로 설정합니다.

### 요청 예시

```javascript
const response = await fetch('https://api.flaq.ai/api/v1/image/task', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model_name: 'qwen-image-2.0-pro-edit',
    prompt: 'Change the sky to sunset colors',
    width: 16,
    height: 9,
    image_url_list: ['https://example.com/image.jpg']
  })
});

const { data } = await response.json();
const taskId = data.task_id;
```

## 응답 형식

### 초기 응답

모든 모델은 폴링을 위한 `task_id`를 반환합니다:

```json
{
  "code": 0,
  "data": {
    "task_id": "{task_id}",
    "task_status": "submitted",
    "response_url": "https://api.flaq.ai/api/v1/image/{task_id}"
  },
  "message": "success"
}
```

### 폴링 응답

`GET /api/v1/image/{taskId}`를 폴링하여 상태를 확인합니다:

```json
{
  "code": 0,
  "data": {
    "task_id": "{task_id}",
    "task_status": "succeed",
    "task_status_msg": null,
    "response_url": "https://api.flaq.ai/api/v1/image/{task_id}",
    "task_result": {
      "credit": 0.0997,
      "images": [
        {
          "url": "https://example.com/generated-image.jpeg"
        }
      ]
    }
  },
  "message": "success"
}
```

### 상태 값

- `submitted`：작업이 수락되었습니다
- `processing`：생성 진행 중
- `succeed`：생성이 성공적으로 완료됨
- `failed`：생성 실패

## 오류 처리

### 일반적인 오류

**잘못된 화면 비율**
```json
{
  "code": 400,
  "message": "Ratio must be one of: 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3"
}
```

**이미지 URL 누락（편집 모드）**
```json
{
  "code": 400,
  "message": "image_url_list is required for edit models"
}
```

**이미지 수 초과（편집 모드）**
```json
{
  "code": 400,
  "message": "image_url_list supports a maximum of 6 images"
}
```

**인증 실패**
```json
{
  "code": 401,
  "message": "Invalid or missing API key"
}
```

## 모범 사례

### 텍스트에서 이미지 생성 팁

1. **구체적으로 작성하기**: 프롬프트에 피사체, 스타일, 조명, 구도 세부 사항을 포함하세요
2. **화면 비율 선택**: 용도에 맞는 비율을 선택하세요（웹 배너는 16:9, 모바일은 9:16, 소셜 미디어는 1:1）
3. **재현성을 위한 Seed 사용**: 요청 간에 일관된 결과가 필요할 때 고정된 `seed` 값을 설정하세요
4. **Standard vs Pro**: 출력 품질이 우선순위일 때 빠른 반복 작업에는 Standard를 사용하세요

### 이미지 편집 팁

1. **명확한 지시**: 프롬프트에서 변경할 내용을 구체적으로 명시하세요
2. **다중 이미지 합성**: 최대 6장의 이미지를 제공하고 어떻게 결합할지 설명하세요
3. **프롬프트 가이드**: 변경 사항을 나열하는 것보다 원하는 결과를 설명하세요
4. **이미지 품질**: 입력 이미지의 품질이 높을수록 일반적으로 더 나은 편집 결과를 얻을 수 있습니다