# API de Clipping con IA

> Envía un vídeo largo y recibe clips virales generados por IA con timestamps, títulos, descripciones y hashtags.

## API de Clipping con IA

Envía un vídeo de cualquier duración y recibe todos los clips clasificados por potencial viral. Cada clip incluye timestamps de inicio/fin detectados automáticamente, títulos, descripciones y hashtags generados por IA. Si la exportación está habilitada, la respuesta también incluye enlaces de descarga de vídeos renderizados con reencuadre automático y subtítulos animados opcionales.

Puedes publicar clips generados por Clipping con IA directamente en cuentas de redes sociales conectadas. Consulta la [API de Publicación en Redes Sociales](https://wayin.ai/es/api-docs/social-media-publishing/) para conectar cuentas y crear tareas de publicación.

## Fuentes de Vídeo Compatibles

YouTube, Vimeo, Dailymotion, Kick, Twitch, TikTok, Facebook, Zoom, Rumble y otras.

También puedes generar clips de [archivos de video locales que subas](https://wayin.ai/es/api-docs/upload/) — la subida local requiere un plan de suscripción [**Starter** o superior](https://wayin.ai/pricing/).

---

## Enviar Tarea de Clipping

```
POST https://wayinvideo-api.wayin.ai/api/v2/clips
```

### Cuerpo de la Solicitud

| Parámetro | Tipo | Requerido | Predeterminado | Descripción |
|-----------|------|-----------|----------------|-------------|
| `video_url` | string | Sí | — | URL del vídeo de origen o identificador del archivo de la [API de Subida](https://wayin.ai/es/api-docs/upload/). |
| `project_name` | string | No | `""` | Nombre personalizado para esta tarea |
| `source_lang` | string | No | `null` | Idioma de origen del vídeo. Cuando `null`, se detecta automáticamente. |
| `target_lang` | string | No | `null` | Idioma de destino para títulos, descripciones y subtítulos. Cuando `null`, corresponde al `source_lang`. |
| `target_duration` | string | No | `DURATION_0_90` | Duración esperada por clip: `DURATION_0_30`, `DURATION_0_90`, `DURATION_30_60`, `DURATION_60_90`, `DURATION_90_180`, `DURATION_180_300`. |
| `limit` | number | No | `null` | Número máximo de clips a devolver. Cuando `null`, devuelve todos. |
| `enable_export` | boolean | No | `false` | `false`: solo metadatos; `true`: renderiza inmediatamente con enlace de descarga. |
| `resolution` | string | No | `SD_480` | Resolución: `SD_480`, `HD_720`, `FHD_1080`, `QHD_2K`, `UHD_4K`. Solo cuando `enable_export` es `true`. |
| `enable_caption` | boolean | No | `false` | Añadir subtítulos animados. Solo cuando `enable_export` es `true`. |
| `caption_display` | string | No | `original` | Modo de subtítulos: `both`, `original`, `translation`. |
| `cc_style_tpl` | string | No | `temp-7` | ID de plantilla de estilo de subtítulos (ver [Estilos de Subtítulos](https://wayin.ai/es/api-docs/subtitles-style/)). |
| `enable_ai_hook` | boolean | No | `false` | Añadir texto de gancho generado por IA al inicio o al final. |
| `ai_hook_script_style` | string | No | `serious` | Estilo del gancho: `serious`, `casual`, `informative`, `conversational`, `humorous`, `parody`, `inspirational`, `dramatic`, `empathetic`, `persuasive`, `neutral`, `excited`, `calm`. |
| `ai_hook_position` | string | No | `beginning` | Posición: `beginning`, `end`. |
| `enable_ai_reframe` | boolean | No | `false` | Activar Reencuadre con IA. Cuando `true`, `ratio` es obligatorio. |
| `ratio` | string | Obligatorio cuando `enable_ai_reframe` es `true` | — | Proporción: `RATIO_9_16`, `RATIO_1_1`, `RATIO_4_5`, `RATIO_16_9`. |
| `reframe_layout` | string | No | `Auto` | Diseño del Reencuadre con IA. Ver la sección de valores de diseño. |
| `enable_more_results` | boolean | No | `false` | Producir más clips. Solo con suscripción **Enterprise**. |
| `enable_express_mode` | boolean | No | `false` | **Modo Express**: consume la mitad de API Units. Solo con suscripción **Enterprise**. |

### Valores de Diseño de Reencuadre

| `ratio` | Valores permitidos de `reframe_layout` |
|---------|----------------------------------------|
| `RATIO_16_9` | `Auto`, `Full`, `Fit`, `Grid 4`, `Split 2`, `Trio`, `PiP`, `OTS`, `Screen First` |
| `RATIO_9_16` | `Auto`, `Full`, `Fit`, `Grid 4`, `Split 2`, `Trio`, `PiP`, `Screen First`, `Gameplay A`, `Gameplay B` |
| `RATIO_1_1` | `Auto`, `Full`, `Fit`, `Grid 4`, `Trio` |
| `RATIO_4_5` | `Auto`, `Full`, `Fit`, `Grid 4`, `Split 2`, `Trio`, `PiP`, `Screen First`, `Gameplay A`, `Gameplay B` |

<div class="tabs" data-labels="Con exportación|Sin exportación" data-group="export-mode"></div>

`enable_export` establecido en `true`. Clips renderizados con `export_link`.

**Solicitud**

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -d '{"video_url": "https://www.youtube.com/watch?v=example", "project_name": "sample project name", "target_duration": "DURATION_30_60", "enable_export": true, "resolution": "HD_720", "enable_caption": true, "enable_ai_reframe": true, "ratio": "RATIO_9_16"}'
```

**Respuesta de Envío**

```json
{"data": {"id": "proj_xyz789", "name": "sample project name", "status": "CREATED"}}
```

<div class="tab-divider"></div>

`enable_export` omitido o `false`. Solo metadatos, sin renderización.

**Solicitud**

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -d '{"video_url": "https://www.youtube.com/watch?v=example", "project_name": "sample project name", "target_duration": "DURATION_30_60"}'
```

**Respuesta de Envío**

```json
{"data": {"id": "proj_abc123", "name": "sample project name", "status": "CREATED"}}
```

<div class="tabs-end"></div>

---

## Ejemplos

Escenarios comunes de AI Clipping. Reemplaza `YOUR_API_KEY` con una clave del [API Dashboard](https://wayin.ai/wayinvideo/api-dashboard).

### Convertir un video de YouTube en clips virales

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -H "Content-Type: application/json" \
  -d '{"video_url": "https://www.youtube.com/watch?v=EXAMPLE"}'
```

### Convertir la grabación de un webinar en shorts verticales 9:16 con subtítulos

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=EXAMPLE",
    "target_duration": "DURATION_30_60",
    "enable_export": true,
    "resolution": "HD_720",
    "enable_caption": true,
    "enable_ai_reframe": true,
    "ratio": "RATIO_9_16"
  }'
```

### Convertir un podcast en los shorts mejor clasificados

Útil para contenido de larga duración cuando solo quieres los clips con mayor puntuación viral.

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=EXAMPLE",
    "limit": 5,
    "target_duration": "DURATION_60_90",
    "enable_export": true,
    "resolution": "HD_720",
    "enable_caption": true,
    "enable_ai_reframe": true,
    "ratio": "RATIO_9_16"
  }'
```

---

## Obtener Resultados de Clipping

```
GET https://wayinvideo-api.wayin.ai/api/v2/clips/results/{id}
```

> **Resultados incrementales:** Cuando `status` es `ONGOING`, cada llamada devuelve los clips generados hasta el momento.

<div class="tabs" data-labels="Con exportación|Sin exportación" data-group="export-mode"></div>

```json
{
  "data": {"id": "proj_xyz789", "status": "SUCCEEDED", "expire_at": 1741824000000, "cost_usage": 120.0,
           "clips": [{"idx": 0, "title": "sample title", "begin_ms": 15000, "end_ms": 75000,
                      "thumbnail": "https://cdn.example.com/thumb/clip_001.jpg",
                      "tags": ["insight"], "desc": "sample description", "score": 81,
                      "export_link": "https://cdn.example.com/export/clip_001.mp4"}]}
}
```

<div class="tab-divider"></div>

```json
{
  "data": {"id": "proj_abc123", "status": "SUCCEEDED", "expire_at": 1741824000000, "cost_usage": 120.0,
           "clips": [{"idx": 0, "title": "sample title", "begin_ms": 15000, "end_ms": 75000,
                      "thumbnail": "https://cdn.example.com/thumb/clip_001.jpg",
                      "tags": ["insight"], "desc": "sample description", "score": 81}]}
}
```

<div class="tabs-end"></div>

### Campos de la Respuesta

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `id` | string | Identificador único de la tarea |
| `name` | string | Nombre de la tarea |
| `status` | string | `CREATED`, `QUEUED`, `ONGOING`, `SUCCEEDED`, `FAILED` |
| `error_message` | string | Motivo del error (solo cuando `FAILED`) |
| `expire_at` | integer | Timestamp de expiración en milisegundos. `-1` significa que el resultado no caduca mientras la suscripción de pago está activa. Cuando termina la suscripción de pago, el resultado se conserva un mes más y después caduca. |
| `cost_usage` | number | API Units consumidas |
| `clips` | array | Lista de objetos de clip |

### Objeto de Clip

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `idx` | integer | Índice del clip (base 0, clasificado por potencial viral) |
| `title` | string | Título generado por IA |
| `begin_ms` | number | Tiempo de inicio en milisegundos |
| `end_ms` | number | Tiempo de fin en milisegundos |
| `thumbnail` | string | URL de la miniatura |
| `tags` | string[] | Hashtags generados por IA |
| `desc` | string | Descripción generada por IA |
| `score` | number | Puntuación de potencial viral (0–100) |
| `export_link` | string | URL de descarga del vídeo renderizado. Expira después de 24 horas. |

---

## Reexportar Clips Existentes

Usa la [API de Exportación de Clips](https://wayin.ai/es/api-docs/clips-export/) para renderizar clips posteriormente o reexportarlos con diferentes configuraciones.


---

## Preguntas frecuentes

### ¿Cuál es la duración máxima del video?

No hay un límite estricto de duración — la API está diseñada para contenido de varias horas, como podcasts, transmisiones de videojuegos en vivo y webinars. Los límites de tamaño de archivo solo se aplican a las [subidas locales](https://wayin.ai/es/api-docs/upload/); las fuentes basadas en URL no tienen tope.

### ¿Cómo se clasifican los clips?

Cada clip se puntúa según su potencial viral — integridad narrativa, fuerza del gancho, picos emocionales y señales de engagement. Usa el parámetro `limit` para conservar solo los N clips con mejor puntuación.

### ¿Puedo obtener clips sin renderizarlos?

Sí. Omite `enable_export` (o ponlo en `false`) para recibir solo timestamps, títulos, descripciones y etiquetas. Renderiza los clips seleccionados más tarde usando la [API de Exportación de Clips](https://wayin.ai/es/api-docs/clips-export/).

### ¿Qué proporciones admite AI Reframe?

`RATIO_9_16` (TikTok / Reels / Shorts), `RATIO_1_1` (feed de Instagram), `RATIO_4_5` (retrato de Instagram) y `RATIO_16_9` (horizontal). Consulta los los valores de diseño de reencuadre para ver las opciones de diseño por proporción.

### ¿Desde qué plataformas puedo crear clips?

YouTube, Vimeo, Dailymotion, Kick, Twitch, TikTok, Facebook, Zoom, Rumble y más, además de archivos subidos localmente (`mp4`, `mov`, `webm`, `avi`).