# Transcreva áudio e vídeo

> Suba um áudio ou vídeo, transcreva com tempo por frase e, se quiser, quem está falando. Baixe em JSON, SRT, VTT ou texto.

A transcrição é independente da clipagem: serve para podcast, aula, entrevista ou qualquer arquivo de áudio ou vídeo. O resultado vem em frases com início e fim em segundos.

### Peça a URL de upload

```bash
curl -X POST https://api.cut.pro/api/v1/transcriptions/upload \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file_name": "entrevista.mp3", "file_size": 48210000, "content_type": "audio/mpeg" }'
```

```json title="200 OK"
{ "media_id": "7412950033118822", "kind": "audio", "upload_url": "https://...", "expires_in": 3600 }
```

A extensão de `file_name` decide se é áudio ou vídeo. O teto é o menor entre o limite de upload do plano e o espaço livre no storage.

### Envie o arquivo

```bash
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: audio/mpeg" \
  --upload-file entrevista.mp3
```

O `Content-Type` precisa ser o mesmo do passo anterior.

### Transcreva

```bash
curl -X POST https://api.cut.pro/api/v1/transcriptions \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "media_id": "7412950033118822",
    "file_name": "entrevista.mp3",
    "file_size": 48210000,
    "source_language": "pt",
    "speaker_labels": true
  }'
```

```json title="202 Accepted"
{ "id": "7412950040021177", "status": "processing", "credits_charged": 42 }
```

| Campo | Descrição |
|---|---|
| `media_id` | O do upload, ou um que já está na sua biblioteca. |
| `file_name`, `file_size` | Obrigatórios para um arquivo recém-enviado. |
| `source_language` | Idioma falado, como `pt`. Sem ele, a detecção é automática. Fixe em áudios curtos: a detecção confunde português com espanhol. |
| `speaker_labels` | Identifica quem fala em cada frase. Custa mais. |

### Espere ficar pronta

```bash
curl https://api.cut.pro/api/v1/transcriptions/7412950040021177 \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

Consulte a cada 5 a 10 segundos enquanto `status` for `processing`. Termina em `ready`, `no_speech` (o áudio não tem fala) ou `failed`. A resposta traz `language`, `duration_seconds` e, com `speaker_labels`, `speaker_count`.

## Pegue o texto

Em JSON, para indexar ou desenhar sua própria interface:

```bash
curl https://api.cut.pro/api/v1/transcriptions/7412950040021177/transcript \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

```json title="200 OK"
{
  "language": "pt",
  "speaker_labels": true,
  "cues": [
    { "start": 0.48, "end": 3.12, "text": "Bem-vindo de volta ao programa.", "speaker": "A" },
    { "start": 3.40, "end": 5.95, "text": "Obrigado pelo convite.", "speaker": "B" }
  ]
}
```

Como arquivo de legenda:

```bash
curl -o entrevista.srt "https://api.cut.pro/api/v1/transcriptions/7412950040021177/download?format=srt" \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

`format` aceita `srt` (padrão), `vtt` e `txt`. O corpo é o arquivo, não JSON. Numa transcrição com `speaker_labels`, os nomes dos falantes entram no arquivo; `speakers=false` tira.

As duas rotas respondem `409 TRANSCRIPTION_NOT_READY` enquanto a transcrição processa.

## Custo

| Situação | Cobrança |
|---|---|
| Transcrição nova | Por minuto de áudio medido (`duration_seconds`), debitada ao começar. |
| Com `speaker_labels` | Acréscimo por minuto. |
| O mesmo arquivo de novo | Grátis: responde `200 ready` na hora, com `credits_charged: 0`. |
| Áudio sem fala | Grátis: `200 no_speech`. |

Para acrescentar falantes a uma transcrição que foi feita sem eles, peça de novo com o mesmo `media_id` e `speaker_labels: true`. O áudio é processado outra vez e cobrado.

> `DELETE /transcriptions/{id}` tira a transcrição das listas, mas o arquivo fica na biblioteca. Transcrever o mesmo `media_id` depois sai de graça.

## Erros

| Code | Quando |
|---|---|
| `INVALID_FILE_TYPE` | Extensão de arquivo não aceita. `extra.allowed_extensions` traz as aceitas. |
| `FILE_TOO_LARGE` | Passa do teto efetivo, em `extra.max_size`. |
| `STORAGE_LIMIT_EXCEEDED` | O storage do plano está cheio. |
| `MEDIA_METADATA_REQUIRED` | Faltou `file_name` ou `file_size` para um arquivo recém-enviado. |
| `MEDIA_TOO_LONG` | Duração acima do permitido. `extra.duration` e `extra.max_duration` dizem quanto. |
| `MEDIA_NOT_FOUND` | O `media_id` não existe neste workspace. |
| `MEDIA_UNREADABLE` | O arquivo enviado não é um áudio ou vídeo legível. |
| `INSUFFICIENT_CREDITS` | Saldo insuficiente. `extra.credits_needed` diz quanto falta. |