# API de Transcrição de Vídeo

> Extraia transcrições em nível de palavra com diarização de locutores (rótulos de locutor) de conteúdo de vídeo ou áudio.

## API de Transcrição de Vídeo

Envie um arquivo de vídeo ou áudio e receba uma transcrição em nível de palavra com diarização de locutores (cada segmento rotulado com o locutor detectado). A API suporta vídeos das principais plataformas e arquivos de vídeo/áudio enviados localmente, com suporte a configurações de idioma.

## 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 transcrever [arquivos locais de áudio ou vídeo que você enviar](https://wayin.ai/pt/api-docs/upload/) — o upload local requer um plano de assinatura **Starter** ou superior.

### Fluxo de Trabalho

1. **Envie** uma tarefa de transcrição a partir de uma URL de vídeo
2. **Consulte** os resultados até que o status seja `SUCCEEDED`

---

## Enviar Tarefa de Transcrição

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

### Corpo da Requisição

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
|-----------|------|-------------|--------|-----------|
| `video_url` | string | Sim | — | URL do vídeo/áudio de origem ou identificador do arquivo enviado |
| `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 o idioma original. |
| `target_lang` | string | Não | `null` | Idioma de destino para a transcrição (consulte [Idiomas Suportados](https://wayin.ai/pt/api-docs/supported-languages/)). Quando `null`, nenhuma tradução é aplicada. Se `target_lang` diferir do idioma original do vídeo, a transcrição será automaticamente traduzida para o idioma de destino. |

### Exemplo de Requisição

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/transcripts \
  -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", "target_lang": "en"}'
```

```python
import requests

requests.post(
    "https://wayinvideo-api.wayin.ai/api/v2/transcripts",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "x-wayinvideo-api-version": "v2",
    },
    json={
        "video_url": "https://www.youtube.com/watch?v=example",
        "target_lang": "en",
    },
)
```

```javascript
await fetch("https://wayinvideo-api.wayin.ai/api/v2/transcripts", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "x-wayinvideo-api-version": "v2",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    video_url: "https://www.youtube.com/watch?v=example",
    target_lang: "en",
  }),
});
```

### Resposta

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

---

## Exemplos

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

### Transcrever um vídeo do YouTube

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/transcripts \
  -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"}'
```

### Transcrever um podcast com vários locutores

Passe qualquer URL de áudio de podcast (ou um [identificador de arquivo enviado](https://wayin.ai/pt/api-docs/upload/)) — a diarização de locutores é automática; cada segmento na resposta carrega um rótulo `speaker`.

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/transcripts \
  -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"}'
```

### Traduzir uma transcrição não inglesa para o inglês

Defina `target_lang` para traduzir em tempo real. Combine com `source_lang` se você já souber o idioma de origem.

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/transcripts \
  -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",
    "source_lang": "ja",
    "target_lang": "en"
  }'
```

---

## Obter Resultados da Transcrição

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

```bash
curl -X GET https://wayinvideo-api.wayin.ai/api/v2/transcripts/results/trans_proj_001 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2"
```

### Resposta

```json
{
  "data": {
    "status": "SUCCEEDED",
    "cost_usage": 27.0,
    "transcript": [
      {"text": "Welcome to today's presentation", "language": null, "start": 200, "end": 4500, "speaker": "Speaker 1"},
      {"text": "Thanks for coming", "language": null, "start": 5000, "end": 8200, "speaker": "Speaker 2"}
    ]
  }
}
```

### Campos da Resposta

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `status` | string | `CREATED`, `QUEUED`, `ONGOING`, `SUCCEEDED`, `FAILED` |
| `error_message` | string | Motivo do erro (somente quando `status` é `FAILED`) |
| `cost_usage` | number | API Units consumidas por esta requisição |
| `transcript` | array | Lista de segmentos de transcrição |

### Segmento de Transcrição

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `text` | string | Texto transcrito |
| `language` | string \| null | Código do idioma detectado, ou `null` se não detectado |
| `start` | integer | Tempo de início em milissegundos |
| `end` | integer | Tempo de término em milissegundos |
| `speaker` | string | Rótulo do locutor (ex.: `"Speaker 1"`) |


---

## Perguntas Frequentes

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

Não há limite rígido de duração. A API suporta tanto clipes curtos quanto conteúdo longo de vídeo ou áudio nas plataformas de origem compatíveis.

### A API retorna timestamps em nível de palavra?

Sim. Cada segmento da transcrição inclui timestamps de `start` e `end` em milissegundos, o `text` transcrito, o idioma detectado (`language`) e o rótulo `speaker` atribuído pela diarização de locutores.

### Como funciona a diarização de locutores?

Os locutores são detectados e rotulados automaticamente (`Speaker 1`, `Speaker 2`, …) por segmento. Nenhuma configuração é necessária — a diarização é executada em todas as tarefas de transcrição.

### Quais formatos de áudio e vídeo são suportados?

URLs de origem são suportadas do YouTube, Vimeo, Dailymotion, Kick, Twitch, TikTok, Facebook, Zoom, Rumble e outros. Para uploads locais, envie `mp4`, `mov`, `webm` ou `avi` (arquivos apenas de áudio podem ser empacotados em um desses contêineres).

### Posso traduzir a transcrição para outro idioma?

Sim — passe o parâmetro `target_lang`. A transcrição é traduzida quando `target_lang` difere do idioma de origem. Veja [Idiomas Suportados](https://wayin.ai/pt/api-docs/supported-languages/) para a lista completa de códigos de idioma.