# API Wan 3.0

Referência completa da API para os modelos de geração de vídeo Wan 3.0 da Alibaba.

## Variantes do modelo

Esta API é compatível com quatro variantes do modelo:

| Modelo | ID | Descrição |
|-------|-----|-------------|
| **Wan 3.0 Text to Video** | `wan-3.0-text-to-video` | Gera vídeos a partir de prompts de texto |
| **Wan 3.0 Image to Video** | `wan-3.0-image-to-video` | Gera vídeos entre os quadros inicial e final obrigatórios |
| **Wan 3.0 Video Edit** | `wan-3.0-video-edit` | Aplica alterações orientadas por prompt a um vídeo existente |
| **Wan 3.0 Reference to Video** | `wan-3.0-reference-to-video` | Gera vídeos a partir de referências multimodais opcionais |

## Comparação rápida

| Recurso | Texto para vídeo | Imagem para vídeo | Edição de vídeo | Referência para vídeo |
|---------|---------------|----------------|------------|--------------------|
| Entrada principal | Prompt de texto | Quadro inicial + Quadro final + Prompt de texto | Prompt de texto + Vídeo de origem opcional | Prompt de texto + Referências opcionais |
| Intervalo de duração | 2 a 30 segundos | 2 a 30 segundos | 2 a 30 segundos | 2 a 30 segundos |
| Opções de resolução | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p |
| Proporções | 16:9, 9:16, 1:1, 4:3, 3:4 | 16:9, 9:16, 1:1, 4:3, 3:4 | 16:9, 9:16, 1:1, 4:3, 3:4 | 16:9, 9:16, 1:1, 4:3, 3:4 |
| Som | Opcional, o padrão é true | Opcional, o padrão é true | Opcional, o padrão é true | Opcional, o padrão é true |

## Endpoint compartilhado

Todas as variantes do Wan 3.0 usam o endpoint de tarefas de vídeo:

```
POST /api/v1/video/task
```

## Parâmetros compartilhados

### Obrigatórios

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `model_name` | string | ID do modelo Wan 3.0 para o modo de geração selecionado |
| `prompt` | string | Instruções que descrevem o vídeo a ser gerado ou a edição a ser aplicada |
| `duration` | number | Duração da saída em segundos, de 2 a 30 |
| `resolution` | string | Resolução da saída: `"480p"`, `"720p"` ou `"1080p"` |
| `aspect_ratio` | string | Proporção da saída: `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` ou `"3:4"` |

### Opcionais

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `sound` | boolean | Define se o som será gerado. O padrão é `true` |
| `seed` | number | Seed inteiro de 0 a 2147483647 |

## Wan 3.0 de texto para vídeo

Defina `model_name` como `"wan-3.0-text-to-video"` e forneça os parâmetros compartilhados obrigatórios.

### Exemplo de solicitação

```javascript
const response = await fetch('https://api.flaq.ai/api/v1/video/task', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model_name: 'wan-3.0-text-to-video',
    prompt: 'A cinematic tracking shot follows a cyclist through a rain-soaked neon city at night',
    duration: 8,
    resolution: '1080p',
    aspect_ratio: '16:9',
    sound: true,
    seed: 42
  })
});

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

## Wan 3.0 de imagem para vídeo

### Entradas de imagem obrigatórias

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `image_url` | string | URL da imagem do quadro inicial |
| `image_end_url` | string | URL da imagem do quadro final |

As duas imagens devem estar nos formatos JPEG, JPG, PNG sem canal alfa, BMP ou WEBP. Cada lado da imagem deve ter de 240 a 8000 pixels.

### Exemplo de solicitação

```javascript
{
  model_name: 'wan-3.0-image-to-video',
  prompt: 'The camera glides forward as daylight gradually shifts into a warm evening glow',
  image_url: 'https://example.com/start-frame.jpg',
  image_end_url: 'https://example.com/end-frame.jpg',
  duration: 8,
  resolution: '1080p',
  aspect_ratio: '16:9',
  sound: true,
  seed: 42
}
```

## Wan 3.0 edição de vídeo

### Entrada de vídeo opcional

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `video_url` | string | URL opcional do vídeo de origem. Se fornecido, o vídeo deve estar em MP4 ou MOV, ter no máximo 15 segundos e ter cada lado entre 240 e 4096 pixels |

Se um vídeo de origem for fornecido, sua duração somada à `duration` de saída solicitada não deve exceder 30 segundos.

### Exemplo de solicitação

```javascript
{
  model_name: 'wan-3.0-video-edit',
  prompt: 'Turn the daytime scene into a rainy evening while preserving the subject and camera movement',
  video_url: 'https://example.com/source-video.mp4',
  duration: 10,
  resolution: '1080p',
  aspect_ratio: '16:9',
  sound: true,
  seed: 42
}
```

## Wan 3.0 de referência para vídeo

As entradas de referência são opcionais e podem ser combinadas, exceto `files` e `links`, que não podem ser enviados juntos.

### Entradas de referência opcionais

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `images` | string[] | Até 10 URLs de imagens. Compatível com JPEG, JPG, PNG sem canal alfa, BMP e WEBP; cada lado deve ter de 240 a 8000 pixels |
| `videos` | string[] | Até 5 URLs de vídeos MP4 ou MOV. Cada vídeo deve ter de 1 a 15 segundos, a duração combinada não deve exceder 15 segundos, e cada lado deve ter de 240 a 4096 pixels |
| `audios` | string[] | Até 5 URLs de áudios WAV ou MP3. Cada clipe deve ter de 1 a 15 segundos, e a duração combinada não deve exceder 15 segundos |
| `files` | string[] | Até uma URL de arquivo DOCX, DOC, XLSX, XLS, PPTX, PPT, PDF, TXT, KEY, PAGES, NUMBERS ou MD. Documentos PDF, Word, PowerPoint, Keynote e Pages não devem exceder 50 páginas |
| `links` | string[] | Até uma URL de página da web acessível publicamente que não exija login. URLs internacionais são aceitas pelo serviço internacional, mas não podem ser analisadas pelo serviço nacional |

### Exemplo de solicitação

```javascript
{
  model_name: 'wan-3.0-reference-to-video',
  prompt: 'Use the references to create a cinematic product launch with coordinated motion and sound',
  duration: 12,
  resolution: '1080p',
  aspect_ratio: '16:9',
  sound: true,
  images: ['https://example.com/product-reference.jpg'],
  videos: ['https://example.com/motion-reference.mp4'],
  audios: ['https://example.com/sound-reference.mp3'],
  links: ['https://example.com/public-creative-brief'],
  seed: 42
}
```

Para usar um arquivo de referência em vez de uma página da web, omita `links` e informe uma única URL em `files`.

## Formato da resposta

### Resposta inicial

Todos os modelos retornam um `task_id` para polling:

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

### Resposta do polling

Faça polling de `GET /api/v1/video/{taskId}` para verificar o status:

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

### Valores de status

- `submitted`: Tarefa aceita e aguardando processamento
- `processing`: Geração do vídeo em andamento
- `succeed`: Geração do vídeo concluída
- `failed`: Falha na geração do vídeo

## Práticas recomendadas

1. **Orientação do prompt**: descreva claramente os sujeitos, as ações, o movimento da câmera, o ritmo, o ambiente e a intenção sonora.
2. **Entradas de imagem**: use imagens iniciais, finais e de referência que correspondam à proporção solicitada. Imagens PNG não devem conter canal alfa.
3. **Duração da edição de vídeo**: se um vídeo de origem for fornecido, verifique sua duração antes de escolher a duração de saída solicitada, para que o total permaneça dentro de 30 segundos.
4. **Limites de referência**: valide a quantidade, o formato, as dimensões e a duração combinada de cada conjunto de referências antes do envio.
5. **Arquivos e links**: envie um arquivo de referência ou um link de página da web pública, nunca ambos na mesma solicitação.