# API de Busca de Momentos
> Identifique e extraia momentos-chave de vídeos usando consultas em linguagem natural.
## API de Busca de Momentos
A API de Busca de Momentos permite que você descreva os momentos desejados em linguagem natural — como `"reações engraçadas"` ou `"demonstrações de produto"` — e a API encontra e extrai clipes correspondentes com timestamps, títulos, descrições e hashtags de vídeos de qualquer duração, incluindo conteúdo de horas. Se a exportação estiver ativada, a resposta também inclui links de download dos vídeos renderizados.
Você pode publicar clipes gerados por Buscar Momentos 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 pesquisar em [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.
---
## Enviar Tarefa de Busca de Momentos
```
POST https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments
```
### 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. |
| `query` | string | Sim | `""` | Consulta em linguagem natural descrevendo os momentos desejados (ex.: `"reações engraçadas"`, `"demonstrações de produto"`) |
| `project_name` | string | Não | `""` | Nome personalizado para esta tarefa |
| `source_lang` | string | Não | `null` | Idioma de origem do vídeo. 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`. |
| `limit` | number | Não | `null` | Número máximo de clipes a retornar. |
| `enable_export` | boolean | Não | `false` | `false`: apenas metadados; `true`: renderiza imediatamente com link de download. |
| `resolution` | string | Não | `SD_480` | Resolução: `SD_480`, `HD_720`, `FHD_1080`, `QHD_2K`, `UHD_4K`. Apenas quando `enable_export` é `true`. |
| `enable_caption` | boolean | Não | `false` | Adicionar legenda animada. Apenas quando `enable_export` é `true`. |
| `caption_display` | string | Não | `original` | Modo de legenda: `both`, `original`, `translation`. |
| `cc_style_tpl` | string | Não | `temp-7` | ID do modelo de estilo de legenda. |
| `enable_ai_hook` | boolean | Não | `false` | Adicionar texto de gancho gerado por IA. |
| `ai_hook_script_style` | string | Não | `serious` | Estilo do gancho: `serious`, `casual`, `informative`, `conversational`, `humorous`, `parody`, `inspirational`, `dramatic`, `empathetic`, `persuasive`, `neutral`, `excited`, `calm`. |
| `ai_hook_position` | string | Não | `beginning` | Posição: `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. |
### 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` |
**Requisição** (`enable_export: true`)
```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments \
-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", "query": "sample query", "enable_export": true, "resolution": "FHD_1080", "enable_caption": true, "enable_ai_reframe": true, "ratio": "RATIO_9_16"}'
```
```json
{"data": {"id": "proj_moment_789", "name": "sample project name", "status": "CREATED"}}
```
**Requisição** (sem exportação)
```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments \
-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", "query": "sample query"}'
```
```json
{"data": {"id": "proj_moment_456", "name": "sample project name", "status": "CREATED"}}
```
---
## Exemplos
Cenários comuns de Find Moments. Substitua `YOUR_API_KEY` por uma chave do [API Dashboard](https://wayin.ai/wayinvideo/api-dashboard).
### Encontrar momentos engraçados em um vídeo do YouTube
```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments \
-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",
"query": "funny reactions"
}'
```
### Extrair segmentos de demonstração de produto de um vídeo de marketing longo
```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments \
-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",
"query": "product demos and feature walkthroughs",
"limit": 10
}'
```
### Encontrar destaques esportivos e exportar como clipes verticais com legendas
```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments \
-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",
"query": "goal moments and key plays",
"enable_export": true,
"resolution": "FHD_1080",
"enable_caption": true,
"enable_ai_reframe": true,
"ratio": "RATIO_9_16"
}'
```
---
## Obter Resultados de Busca de Momentos
```
GET https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments/results/{id}
```
> **Resultados incrementais:** Quando `status` é `ONGOING`, cada chamada retorna os clipes gerados até o momento.
```bash
curl -X GET https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments/results/proj_moment_456 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "x-wayinvideo-api-version: v2"
```
```json
{
"data": {
"id": "proj_moment_789", "status": "SUCCEEDED", "expire_at": 1775831883112, "cost_usage": 120.0,
"clips": [{"idx": 0, "title": "sample title", "begin_ms": 120000, "end_ms": 185000,
"thumbnail": "https://cdn.example.com/thumb/moment_001.jpg",
"tags": ["product", "announcement"], "desc": "sample description",
"score": 81, "export_link": "https://cdn.example.com/export/moment_001.mp4"}]
}
}
```
```json
{
"data": {
"id": "proj_moment_456", "status": "SUCCEEDED", "expire_at": 1775831883112, "cost_usage": 120.0,
"clips": [{"idx": 0, "title": "sample title", "begin_ms": 120000, "end_ms": 185000,
"thumbnail": "https://cdn.example.com/thumb/moment_001.jpg",
"tags": ["product", "announcement"], "desc": "sample description", "score": 81}]
}
}
```
### 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 `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 clipes |
### Objeto de Clipe
| Campo | Tipo | Descrição |
|-------|------|-----------|
| `idx` | integer | Índice do clipe (baseado em 0) |
| `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 com diferentes configurações.
---
## Perguntas Frequentes
### Em que o Find Moments difere do AI Clipping?
O [AI Clipping](https://wayin.ai/pt/api-docs/ai-clipping/) retorna clipes classificados automaticamente por potencial viral — sem necessidade de consulta. O **Find Moments** permite que você descreva o que deseja em linguagem natural (ex.: `"reações engraçadas"`, `"demonstrações de produto"`, `"momentos de gol"`) e retorna apenas os clipes correspondentes.
### Posso limitar o número de momentos retornados?
Sim. Passe `limit: N` para retornar apenas as N principais correspondências classificadas por relevância. Útil quando o vídeo de origem é longo e você só quer as correspondências mais fortes.
### O Find Moments suporta resultados parciais?
Sim — ao consultar, os segmentos com `status: ONGOING` já contêm os clipes gerados até o momento, para que você possa iniciar o processamento downstream sem esperar a tarefa terminar completamente.