# API de Wan 3.0

Referencia completa de la API para los modelos de generación de vídeo Wan 3.0 de Alibaba.

## Variantes del modelo

Esta API admite cuatro variantes del modelo:

| Modelo | ID | Descripción |
|-------|-----|-------------|
| **Wan 3.0 Texto a vídeo** | `wan-3.0-text-to-video` | Genera vídeos a partir de instrucciones de texto |
| **Wan 3.0 Imagen a vídeo** | `wan-3.0-image-to-video` | Genera vídeos entre los fotogramas inicial y final obligatorios |
| **Wan 3.0 Edición de vídeo** | `wan-3.0-video-edit` | Aplica cambios guiados por instrucciones a un vídeo existente |
| **Wan 3.0 Referencia a vídeo** | `wan-3.0-reference-to-video` | Genera vídeos a partir de referencias multimodales opcionales |

## Comparación rápida

| Función | Texto a vídeo | Imagen a vídeo | Edición de vídeo | Referencia a vídeo |
|---------|---------------|----------------|------------|--------------------|
| Entrada principal | Instrucción de texto | Fotograma inicial + Fotograma final + Instrucción de texto | Instrucción de texto + Vídeo de origen opcional | Instrucción de texto + Referencias opcionales |
| Intervalo de duración | 2-30 segundos | 2-30 segundos | 2-30 segundos | 2-30 segundos |
| Opciones de resolución | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p |
| Relaciones de aspecto | 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 |
| Sonido | Opcional, `true` de forma predeterminada | Opcional, `true` de forma predeterminada | Opcional, `true` de forma predeterminada | Opcional, `true` de forma predeterminada |

## Endpoint compartido

Todas las variantes de Wan 3.0 utilizan el endpoint de tareas de vídeo:

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

## Parámetros compartidos

### Obligatorios

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `model_name` | string | ID del modelo Wan 3.0 para el modo de generación seleccionado |
| `prompt` | string | Instrucciones que describen el vídeo que se generará o la edición que se aplicará |
| `duration` | number | Duración del resultado en segundos, de 2 a 30 |
| `resolution` | string | Resolución del resultado: `"480p"`, `"720p"` o `"1080p"` |
| `aspect_ratio` | string | Relación de aspecto del resultado: `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` o `"3:4"` |

### Opcionales

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `sound` | boolean | Indica si se genera sonido. El valor predeterminado es `true` |
| `seed` | number | Semilla entera de 0 a 2147483647 |

## Wan 3.0 Texto a vídeo

Establece `model_name` en `"wan-3.0-text-to-video"` y proporciona los parámetros compartidos obligatorios.

### Ejemplo de solicitud

```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 Imagen a vídeo

### Entradas de imagen obligatorias

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `image_url` | string | URL de la imagen del fotograma inicial |
| `image_end_url` | string | URL de la imagen del fotograma final |

Ambas imágenes deben usar JPEG, JPG, PNG sin canal alfa, BMP o WEBP. Cada lado de la imagen debe tener entre 240 y 8000 píxeles.

### Ejemplo de solicitud

```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 Edición de vídeo

### Entrada de vídeo opcional

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `video_url` | string | URL opcional del vídeo de origen. Si se proporciona, el vídeo debe estar en formato MP4 o MOV, durar como máximo 15 segundos y tener cada lado entre 240 y 4096 píxeles |

Si se proporciona un vídeo de origen, la suma de su duración y la `duration` solicitada para el resultado no debe superar los 30 segundos.

### Ejemplo de solicitud

```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 Referencia a vídeo

Las entradas de referencia son opcionales y se pueden combinar, excepto `files` y `links`, que no pueden enviarse conjuntamente.

### Entradas de referencia opcionales

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `images` | string[] | Hasta 10 URL de imágenes. Admite JPEG, JPG, PNG sin canal alfa, BMP y WEBP; cada lado debe tener entre 240 y 8000 píxeles |
| `videos` | string[] | Hasta 5 URL de vídeos MP4 o MOV. Cada vídeo debe durar entre 1 y 15 segundos, la duración conjunta no debe superar los 15 segundos y cada lado debe tener entre 240 y 4096 píxeles |
| `audios` | string[] | Hasta 5 URL de audio WAV o MP3. Cada clip debe durar entre 1 y 15 segundos y la duración conjunta no debe superar los 15 segundos |
| `files` | string[] | URL de hasta un archivo DOCX, DOC, XLSX, XLS, PPTX, PPT, PDF, TXT, KEY, PAGES, NUMBERS o MD. Los documentos PDF, Word, PowerPoint, Keynote y Pages no deben superar las 50 páginas |
| `links` | string[] | URL de hasta una página web accesible públicamente que no requiera iniciar sesión. El servicio internacional admite URL extranjeras, pero el servicio nacional no puede analizarlas |

### Ejemplo de solicitud

```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 utilizar un archivo de referencia en lugar de una página web, omite `links` y pasa una única URL en `files`.

## Formato de respuesta

### Respuesta inicial

Todos los modelos devuelven un `task_id` para realizar consultas periódicas:

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

### Respuesta de consulta

Consulta `GET /api/v1/video/{taskId}` para comprobar el estado:

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

- `submitted`: Tarea aceptada y en espera de procesamiento
- `processing`: Generación de vídeo en curso
- `succeed`: Generación de vídeo completada
- `failed`: Error en la generación de vídeo

## Prácticas recomendadas

1. **Dirección de la instrucción**: Describe claramente los sujetos, las acciones, el movimiento de la cámara, el ritmo, el entorno y la intención del sonido.
2. **Entradas de imagen**: Utiliza imágenes iniciales, finales y de referencia que coincidan con la relación de aspecto solicitada. Las imágenes PNG no deben contener un canal alfa.
3. **Duración de la edición de vídeo**: Si se proporciona un vídeo de origen, comprueba su duración antes de elegir la duración solicitada para el resultado, de modo que el total se mantenga dentro de los 30 segundos.
4. **Límites de las referencias**: Valida el número, el formato, las dimensiones y la duración conjunta de cada colección de referencias antes del envío.
5. **Archivos y enlaces**: Envía un archivo de referencia o un enlace a una página web pública, nunca ambos en la misma solicitud.