# API de Clipping com IA

> Envie um vídeo longo e receba clipes virais gerados por IA com timestamps, títulos, descrições e hashtags.

## API de Clipping com IA

Envie um vídeo de qualquer duração e receba todos os clipes virais classificados por potencial viral. Cada clipe inclui timestamps de início/fim detectados automaticamente, títulos, descrições e hashtags gerados por IA. Se a exportação estiver ativada, a resposta também inclui links de download dos vídeos renderizados, com reencadramento automático opcional e legendas animadas.

Você pode publicar clipes gerados por Clipping com IA diretamente em contas de redes sociais conectadas. Consulte a [API de Publicação em Redes Sociais](https://wayin.ai/pt/api-docs/social-media-publishing/) para conectar contas e criar tarefas de publicação.

## Fontes de Vídeo Suportadas

A API aceita URLs das seguintes plataformas: YouTube, Vimeo, Dailymotion, Kick, Twitch, TikTok, Facebook, Zoom, Rumble e outras.

Você também pode gerar clipes a partir de [arquivos de vídeo locais que você enviar](https://wayin.ai/pt/api-docs/upload/) — o upload local requer um plano de assinatura [**Starter** ou superior](https://wayin.ai/pricing/).

---

## Enviar Tarefa de Clipping

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

### Corpo da Requisição

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
|-----------|------|-------------|--------|-----------|
| `video_url` | string | Sim | — | URL do vídeo de origem ou identificador do arquivo enviado pela [API de Upload](https://wayin.ai/pt/api-docs/upload/). |
| `project_name` | string | Não | `""` | Nome personalizado para esta tarefa |
| `source_lang` | string | Não | `null` | Idioma de origem do vídeo (consulte [Idiomas Suportados](https://wayin.ai/pt/api-docs/supported-languages/)). Quando `null`, o sistema detecta automaticamente. |
| `target_lang` | string | Não | `null` | Idioma de destino para títulos, descrições e legendas. Quando `null`, corresponde ao `source_lang`. |
| `target_duration` | string | Não | `DURATION_0_90` | Duração esperada por clipe: `DURATION_0_30`, `DURATION_0_90`, `DURATION_30_60`, `DURATION_60_90`, `DURATION_90_180`, `DURATION_180_300`. |
| `limit` | number | Não | `null` | Número máximo de clipes a retornar. Quando `null`, retorna todos. |
| `enable_export` | boolean | Não | `false` | `false`: retorna apenas metadados; `true`: renderiza imediatamente com link de download. |
| `resolution` | string | Não | `SD_480` | Resolução de saída: `SD_480`, `HD_720`, `FHD_1080`, `QHD_2K`, `UHD_4K`. Apenas quando `enable_export` é `true`. |
| `enable_caption` | boolean | Não | `false` | Adicionar legenda animada ao renderizar. Apenas quando `enable_export` é `true`. |
| `caption_display` | string | Não | `original` | Modo de legenda: `both`, `original`, `translation`. Apenas quando `enable_export` e `enable_caption` são `true`. |
| `cc_style_tpl` | string | Não | `temp-7` | ID do modelo de estilo de legenda (consulte [Estilos de Legenda](https://wayin.ai/pt/api-docs/subtitles-style/)). |
| `enable_ai_hook` | boolean | Não | `false` | Adicionar texto de gancho gerado por IA no início ou no fim de cada clipe renderizado. |
| `ai_hook_script_style` | string | Não | `serious` | Estilo do texto de gancho: `serious`, `casual`, `informative`, `conversational`, `humorous`, `parody`, `inspirational`, `dramatic`, `empathetic`, `persuasive`, `neutral`, `excited`, `calm`. |
| `ai_hook_position` | string | Não | `beginning` | Posição do gancho: `beginning`, `end`. |
| `enable_ai_reframe` | boolean | Não | `false` | Ativar Reencadramento com IA. Quando `true`, `ratio` é obrigatório. |
| `ratio` | string | Obrigatório quando `enable_ai_reframe` é `true` | — | Proporção: `RATIO_9_16`, `RATIO_1_1`, `RATIO_4_5`, `RATIO_16_9`. |
| `reframe_layout` | string | Não | `Auto` | Layout do Reencadramento com IA. Veja a seção de valores de layout. |
| `enable_more_results` | boolean | Não | `false` | Produzir mais clipes. Apenas com assinatura **Enterprise**. |
| `enable_express_mode` | boolean | Não | `false` | **Modo Express**: consome metade das API Units. Apenas com assinatura **Enterprise**. |

### Valores de Layout de Reencadramento

| `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="Com exportação|Sem exportação" data-group="export-mode"></div>

`enable_export` definido como `true`. Clipes renderizados com `export_link`.

**Requisição**

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

**Resposta de Envio**

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

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

`enable_export` omitido ou `false`. Apenas metadados, sem renderização.

**Requisição**

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

**Resposta de Envio**

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

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

---

## Exemplos

Cenários comuns de AI Clipping. Substitua `YOUR_API_KEY` por uma chave do [API Dashboard](https://wayin.ai/wayinvideo/api-dashboard).

### Recortar um vídeo do YouTube em clipes virais

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

### Recortar a gravação de um webinar em shorts verticais 9:16 com legendas

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

### Recortar um podcast nos shorts mais bem classificados

Útil para conteúdo longo no qual você quer apenas os clipes com maior pontuação de potencial 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"
  }'
```

---

## Obter Resultados de Clipping

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

> **Resultados incrementais:** Quando `status` é `ONGOING`, cada chamada retorna os clipes gerados até o momento — você pode começar a processar resultados parciais imediatamente.

```bash
curl -X GET https://wayinvideo-api.wayin.ai/api/v2/clips/results/proj_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2"
```

<div class="tabs" data-labels="Com exportação|Sem exportação" data-group="export-mode"></div>

```json
{
  "data": {
    "id": "proj_xyz789", "name": "sample project name", "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", "analysis"], "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", "name": "sample project name", "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", "analysis"], "desc": "sample description", "score": 81}
    ]
  }
}
```

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

### Campos da Resposta

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `id` | string | Identificador único da tarefa |
| `name` | string | Nome da tarefa |
| `status` | string | `CREATED`, `QUEUED`, `ONGOING`, `SUCCEEDED`, `FAILED` |
| `error_message` | string | Motivo do erro (apenas quando `status` é `FAILED`) |
| `expire_at` | integer | Timestamp de expiração em milissegundos. `-1` significa que o resultado não expira enquanto uma assinatura paga estiver ativa. Depois que a assinatura paga termina, o resultado é mantido por mais um mês e então expira. |
| `cost_usage` | number | API Units consumidas |
| `clips` | array | Lista de objetos de clipe |

### Objeto de Clipe

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `idx` | integer | Índice do clipe (baseado em 0, classificado por potencial viral) |
| `title` | string | Título gerado por IA |
| `begin_ms` | number | Tempo de início em milissegundos |
| `end_ms` | number | Tempo de término em milissegundos |
| `thumbnail` | string | URL da miniatura |
| `tags` | string[] | Hashtags geradas por IA |
| `desc` | string | Descrição gerada por IA |
| `score` | number | Pontuação de potencial viral (0–100) |
| `export_link` | string | URL de download do vídeo renderizado. Expira após 24 horas. |

---

## Reexportar Clipes Existentes

Use a [API de Exportação de Clipes](https://wayin.ai/pt/api-docs/clips-export/) para renderizar clipes posteriormente ou reexportá-los com diferentes configurações.


---

## Perguntas Frequentes

### Qual é a duração máxima do vídeo?

Não há limite rígido de duração — a API foi projetada para conteúdo de horas, como podcasts, livestreams de games e webinars. Os limites de tamanho de arquivo se aplicam apenas a [uploads locais](https://wayin.ai/pt/api-docs/upload/); fontes baseadas em URL não têm limite.

### Como os clipes são classificados?

Cada clipe recebe uma pontuação de potencial viral — completude narrativa, força do gancho, picos emocionais e sinais de engajamento. Use o parâmetro `limit` para manter apenas os N clipes com maior pontuação.

### Posso obter clipes sem renderizá-los?

Sim. Omita `enable_export` (ou defina como `false`) para receber apenas timestamps, títulos, descrições e tags. Renderize clipes selecionados depois usando a [Clips Export API](https://wayin.ai/pt/api-docs/clips-export/).

### Quais proporções o AI Reframe suporta?

`RATIO_9_16` (TikTok / Reels / Shorts), `RATIO_1_1` (feed do Instagram), `RATIO_4_5` (Instagram retrato) e `RATIO_16_9` (paisagem). Veja os valores de layout de reencadramento para opções de layout por proporção.

### De quais plataformas posso gerar clipes?

YouTube, Vimeo, Dailymotion, Kick, Twitch, TikTok, Facebook, Zoom, Rumble e outras, além de arquivos enviados localmente (`mp4`, `mov`, `webm`, `avi`).