# API Qwen Image 2.0

Referência completa da API para os modelos Qwen Image 2.0, alimentados pelo Alibaba Qwen.

## Variantes de Modelo

Esta API oferece suporte a quatro variantes de modelo:

| Modelo | ID | Descrição |
|-------|-----|-------------|
| **Qwen Image 2** | `qwen-image-2.0` | Geração de texto para imagem |
| **Qwen Image 2 Edit** | `qwen-image-2.0-edit` | Edição de imagem e composição de múltiplas imagens |
| **Qwen Image 2 Pro** | `qwen-image-2.0-pro` | Geração aprimorada de texto para imagem com saída de maior qualidade |
| **Qwen Image 2 Pro Edit** | `qwen-image-2.0-pro-edit` | Edição aprimorada de imagem e composição de múltiplas imagens |

## Comparação Rápida

| Recurso | Standard | Pro |
|---------|----------|-----|
| Texto para Imagem | ✅ Sim | ✅ Sim |
| Edição de Imagem | ✅ Sim | ✅ Sim |
| Proporções de Aspecto | 7 opções | 7 opções |
| Entrada de Imagem (Edit) | ✅ Sim (1-6 imagens) | ✅ Sim (1-6 imagens) |
| Suporte a Múltiplas Imagens | ✅ Sim | ✅ Sim |
| Output Quality | Standard | Aprimorada |

| Recurso | Texto para Imagem | Edit |
|---------|---------------|------|
| Entrada | Prompt de texto | Imagem(s) + prompt de texto |
| Entrada de Imagem | ❌ Não | ✅ Sim (1-6 imagens) |
| Suporte a Múltiplas Imagens | ❌ Não | ✅ Sim |
| Seed Support | ✅ Opcional | ✅ Opcional |

### Proporções de Aspecto Compatíveis

Tanto os modelos Standard quanto Pro suportam 7 proporções de aspecto:
- `16:9` (padrão), `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`

## Qwen Image 2 (Texto para Imagem)

### Ponto de extremidade

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

### Autenticação

```
Authorization: Bearer YOUR_API_KEY
```

### Parâmetros da Solicitação

#### Obrigatório

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `model_name` | string | Deve ser `"qwen-image-2.0"` |
| `prompt` | string | Prompt de geração de imagem |
| `width` | number | Valor da proporção da largura (por exemplo, 16 para 16:9) |
| `height` | number | Valor da proporção da altura (por exemplo, 9 para 16:9) |

**Observação:** A proporção width:height deve ser uma das seguintes: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`

#### Opcional

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `seed` | number | Semente aleatória para resultados reproduzíveis |

### Exemplo de Solicitação

```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 (Edição de Imagem)

### Ponto de extremidade

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

### Parâmetros da Solicitação

#### Obrigatório

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `model_name` | string | Deve ser `"qwen-image-2.0-edit"` |
| `prompt` | string | Descrição das edições desejadas |
| `width` | number | Valor da proporção da largura (por exemplo, 16 para 16:9) |
| `height` | number | Valor da proporção da altura (por exemplo, 9 para 16:9) |
| `image_url_list` | string[] | Array of input image URLs (1-6 items) |

**Observação:** A proporção width:height deve ser uma das seguintes: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`

#### Opcional

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `seed` | number | Semente aleatória para resultados reproduzíveis |

### Exemplo de Edição de Uma Imagem

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

### Exemplo de Composição com Múltiplas Imagens

Até 6 imagens podem ser combinadas em uma única solicitação:

```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 (Texto para Imagem)

Usa os mesmos parâmetros do Qwen Image 2, com `model_name` definido como `qwen-image-2.0-pro` para uma qualidade de saída aprimorada.

### Exemplo de Solicitação

```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 (Edição de Imagem)

Usa os mesmos parâmetros do Qwen Image 2 Edit, com `model_name` definido como `qwen-image-2.0-pro-edit` para uma qualidade de saída aprimorada.

### Exemplo de Solicitação

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

## Formato da Resposta

### Resposta Inicial

Todos os modelos retornam um `task_id` para consulta:

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

### Resposta de Consulta

Consulte `GET /api/v1/image/{taskId}` para verificar o status:

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

### Valores de Status

- `submitted`: Tarefa aceita
- `processing`: Geração em andamento
- `succeed`: Geração concluída com sucesso
- `failed`: Geração falhou

## Tratamento de Erros

### Erros Comuns

**Proporção Inválida**
```json
{
  "code": 400,
  "message": "Ratio must be one of: 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3"
}
```

**URL da Imagem Ausente (Modo de Edição)**
```json
{
  "code": 400,
  "message": "image_url_list is required for edit models"
}
```

**Muitas Imagens (Modo de Edição)**
```json
{
  "code": 400,
  "message": "image_url_list supports a maximum of 6 images"
}
```

**Não Autorizado**
```json
{
  "code": 401,
  "message": "Invalid or missing API key"
}
```

## Melhores Práticas

### Dicas de Texto para Imagem

1. **Seja Específico**: Inclua detalhes do sujeito, estilo, iluminação e composição no prompt
2. **Seleção de Proporção**: Escolha a proporção com base no seu caso de uso (16:9 para banners web, 9:16 para mobile, 1:1 para redes sociais)
3. **Use Seed para Reprodutibilidade**: Defina um valor fixo de `seed` quando precisar de resultados consistentes entre solicitações
4. **Standard vs Pro**: Use Standard para iteração rápida quando a qualidade de saída for a prioridade

### Dicas de Edição de Imagem

1. **Instruções Claras**: Seja específico sobre o que alterar no prompt
2. **Composição com Múltiplas Imagens**: Forneça até 6 imagens e descreva como elas devem ser combinadas
3. **Orientação do Prompt**: Descreva o resultado desejado em vez de apenas listar alterações
4. **Qualidade da Imagem**: Imagens de entrada de maior qualidade geralmente produzem melhores resultados de edição