---
title: "API de transcrições para vídeo e áudio"
description: "Transforme links do YouTube, TikTok, Instagram, LinkedIn e Twitter/X em transcrições com carimbos de data e hora com uma única API REST: legendas primeiro e, quando não houver, IA."
canonical: "https://transcript.im/pt-BR/api"
markdown: "https://transcript.im/pt-BR/api.md"
---

# API de transcrições para vídeo e áudio

Transforme links do YouTube, TikTok, Instagram, LinkedIn e Twitter/X em transcrições com carimbos de data e hora com uma única API REST: legendas primeiro e, quando não houver, IA.

## Links

- [HTML canônico](https://transcript.im/pt-BR/api)
- [Markdown](https://transcript.im/pt-BR/api.md)


O transcript.im expõe como API versionada o mesmo pipeline de extração que alimenta o produto. Envie uma URL de vídeo ou áudio e receba texto com carimbos de data e hora, em JSON ou texto simples, com a plataforma detectada para você. As legendas existentes são usadas primeiro; quando um vídeo não tem nenhuma, a IA transcreve o áudio e o resultado é entregue de forma assíncrona.

- Um único `url` aceita um link completo ou curto e detecta YouTube, TikTok, Instagram, LinkedIn e Twitter/X; no YouTube, um id de vídeo puro também é reconhecido, e `platform` com `externalId` cobrem uma fonte que você já conhece.
- As legendas são usadas primeiro; quando um vídeo não tem nenhuma, a IA transcreve o áudio, e um arquivo local enviado por upload sempre passa pelo reconhecimento de fala.
- `format=json` retorna segmentos com carimbos de data e hora, enquanto `format=text` retorna texto simples pronto para colar.
- A extração em lote cobre listas de URLs, playlists e canais.
- A exportação em lote cobre txt, csv, json, srt, vtt e zip; uma transcrição salva é baixada como txt, srt, vtt, json ou md.
- As transcrições salvas ficam na biblioteca da conta, e a descoberta do YouTube cobre busca, vídeos, canais, envios, playlists e legendas.
- O contrato completo é publicado como documento OpenAPI.

## O que a API do transcript.im faz

A API do transcript.im transforma um link público de vídeo ou áudio em uma transcrição com carimbos de data e hora que seu produto pode ler, armazenar, pesquisar ou alimentar um modelo. Você envia uma URL; a API resolve a plataforma, procura a faixa de legendas que o criador já tem e retorna o texto escrito com um carimbo de data e hora em cada linha. Quando um vídeo não tem nenhuma legenda, a API não para em um erro: ela recorre à transcrição por IA do áudio falado para que a mesma requisição ainda produza texto.

Esse único comportamento é o sentido de uma API de extração de transcrições: você não precisa de um baixador, um raspador de legendas e um serviço de fala para texto costurados entre si. A API escolhe a fonte mais barata que funciona para cada link, mantém os carimbos de data e hora alinhados ao que foi realmente dito e informa em qual idioma respondeu. Uma transcrição que já existe volta na hora; um vídeo que precisa de reconhecimento de fala é entregue como job para que uma gravação longa nunca deixe sua requisição aberta.

- Uma requisição, texto real: resolva um link e retorne segmentos de transcrição com carimbos de data e hora ou texto simples.
- Legendas primeiro, IA depois: use a faixa do criador quando ela existe e transcreva o áudio quando não.
- Assíncrono por padrão para ASR: um job id permite consultar uma transcrição longa sem bloquear.
- Ciente do idioma: peça uma prioridade de idioma e leia de volta o idioma que a API resolveu.
- Independente da plataforma: quem chama não precisa saber onde o vídeo está hospedado.

## Uma API de transcrições para cinco plataformas

### YouTube

Transcrições de qualquer vídeo público, Short ou gravação ao vivo do YouTube, usando primeiro as legendas do criador e a transcrição por IA quando elas faltam. O YouTube também é a plataforma com uma superfície de descoberta completa — busca, vídeos, canais, envios, playlists e legendas — disponível ao lado da própria transcrição. O acervo de um canal ou uma playlist vira um lote de transcrições com carimbos de data e hora, enquanto um único link volta como texto legível que você pode pesquisar.

### TikTok

Transcrições de vídeos públicos do TikTok, com as legendas usadas primeiro e o reconhecimento de fala como alternativa. Cole um link de vídeo e leia o conteúdo falado como texto limpo com carimbos de data e hora que você pode reaproveitar, traduzir ou citar. A mesma chamada cobre um clipe curto e um envio mais longo, então uma tendência, um tutorial e um vídeo de alguém falando para a câmera voltam como texto.

### Instagram

Transcrições de Reels e publicações de vídeo públicas do Instagram. O Instagram não tem uma faixa de legendas para ler, então a extração é reconhecimento de fala assíncrono: envie o link, consulte o job e colete o texto quando estiver pronto. Isso torna um Reel citável e pesquisável mesmo que a plataforma nunca tenha publicado suas palavras como texto.

### LinkedIn

Transcrições de publicações de vídeo públicas do LinkedIn, com as legendas usadas primeiro e o reconhecimento de fala como alternativa. O resultado volta com carimbos de data e hora, então uma palestra, um clipe de produto ou uma reunião gravada vira texto pesquisável que você pode citar e reutilizar. Extraia o argumento da gravação de um webinar ou transforme a novidade de um fundador em um rascunho que você pode editar.

### Twitter/X

Transcrições de publicações de vídeo públicas do X. O X não tem uma faixa de legendas para ler, então a extração passa pelo reconhecimento de fala assíncrono: envie o link, consulte o job e colete texto com carimbos de data e hora que você pode pesquisar. Cite um vídeo com precisão ou arquive seu conteúdo falado antes que a publicação seja editada ou removida.

## Como flui uma requisição de transcrição

Uma única chamada leva um link ou um arquivo enviado da entrada até a transcrição, e a API informa qual caminho ela seguiu.

- Envie a fonte: publique um `url`, passe `platform` e `externalId` quando já os conhece, ou envie um arquivo como `multipart/form-data` para o mesmo endpoint.
- Obtenha uma correspondência de legendas: quando o vídeo tem legendas em um idioma da sua lista, a transcrição volta na resposta.
- Trate um idioma sem correspondência: quando existem legendas mas nenhuma corresponde à sua lista, a requisição continua para a transcrição por IA e retorna `202` com um job id; um `404` com `availableLanguages` só é retornado quando o reconhecimento de fala não é permitido para quem chama.
- Force o ASR ou recorra a ele: uma entrada `asr` explícita, um vídeo sem nenhuma faixa de legendas ou um arquivo enviado inicia um job de ASR e retorna um job id.
- Consulte ou receba em streaming: leia o job com `GET /v1/transcript/job/{id}` até que ele tenha sucesso ou falhe, ou assine seu fluxo `/events` para receber o progresso do servidor. Uma consulta de job retorna `200` mesmo quando o job falhou, então ramifique pelo campo `status`.
- Leia o resultado: uma transcrição finalizada traz seu idioma resolvido, duração, segmentos com carimbos de data e hora e, quando solicitado, metadados como título, autor e data de publicação.
- Repita com segurança: uma transcrição que já foi extraída é servida do cache em vez de iniciar um novo job, então a mesma fonte pode ser solicitada de novo.
- Inspecione antes: `GET /v1/transcript/info` resolve uma fonte e lista os idiomas que ela pode servir antes de você assumir uma extração.

Como o mesmo endpoint serve um acerto de cache e uma extração nova, sua integração não ramifica pela fonte: ela sempre envia a fonte e reage ao status que recebe. Uma correspondência de legendas retorna a transcrição diretamente, um idioma sem correspondência continua para a transcrição por IA e retorna `202` com um job id, e um recurso realmente ausente ou uma alternativa não permitida retorna `404`. Cada caminho retorna o mesmo formato de transcrição quando o texto está pronto.

## Extração em lote e exportações

Cargas de trabalho reais raramente param em um único vídeo, então a API aceita um lote como lista de URLs, playlist ou canal. Cada lote acompanha seus próprios totais — quantos itens estão pendentes, quantos tiveram sucesso e quantos falharam — e retorna itens página a página, para que um canal longo não chegue como uma única carga enorme.

- Três formas de lote: `POST /v1/batch` aceita uma lista de URLs, uma playlist ou um canal, conforme o corpo que você envia.
- Status independente: um link que falhou é marcado sozinho e nunca descarta o restante do lote; os itens com falha podem ser repetidos com `/retry`.
- Itens paginados: leia o lote com `GET /v1/batch/{batchId}` e siga o token de página retornado para os itens restantes.
- Progresso ao vivo: cada consulta retorna contagens atualizadas, para que quem chama possa mostrar quanto de uma execução longa terminou.
- Exporte no seu formato: baixe um lote finalizado em `/export` como `txt`, `csv`, `json`, `srt`, `vtt` ou `zip`.

Para um pipeline de legendas, as exportações `srt` e `vtt` entram direto em um editor ou reprodutor. Para um arquivo, `csv`, `json` e `zip` mantêm toda uma biblioteca de gravações pesquisável como um único corpus. Os formatos acompanham as respostas de transcrição única, então um consumidor que trata um resultado já sabe ler um lote.

## Transcrições salvas na biblioteca da conta

Extração e armazenamento são coisas separadas: uma transcrição passa a fazer parte da biblioteca da conta quando é salva, e a biblioteca é onde você a lê, pesquisa, baixa e remove depois sem executar a extração de novo.

- Liste o conteúdo salvo: `GET /v1/library/transcripts` percorre por páginas as transcrições da conta, os registros de lote e as linhas de histórico com falha, com busca, filtros de plataforma e idioma e ordenação.
- Leia um item: `GET /v1/library/transcripts/{platform}/{externalId}` retorna uma transcrição salva por plataforma e id externo, ou para o idioma que você indicar.
- Baixe: a rota `/download` exporta uma transcrição salva como `txt`, `srt`, `vtt`, `json` ou `md`.
- Conteúdo relacionado: a rota `/related` lista outros itens salvos do mesmo canal.
- Remova: `DELETE` tira um item da biblioteca sem tocar na cópia de ninguém mais.
- Leituras restritas à conta: uma requisição à biblioteca retorna apenas o que a conta salvou e nunca inicia uma extração nova, então revisitar uma transcrição salva é uma leitura, não outro job.

## Descoberta do YouTube além das transcrições

O YouTube é a plataforma em que a API também responde às perguntas ao redor de uma transcrição, usando os mesmos nomes de recursos da API de Dados do YouTube.

- Busca: `GET /v1/youtube/search` encontra vídeos, canais ou playlists por consulta e retorna resultados paginados por cursor.
- Vídeos: `GET /v1/youtube/videos` retorna detalhes de um vídeo, incluindo se há legendas disponíveis.
- Canais: `GET /v1/youtube/channels` resolve um canal por id ou `@handle`.
- Envios de um canal: `GET /v1/youtube/channels/{channelId}/videos` percorre os envios de um canal.
- Itens de playlist: `GET /v1/youtube/playlists/{playlistId}/items` percorre uma playlist.
- Legendas: `GET /v1/youtube/captions` retorna os metadados da faixa de legendas e o texto das legendas de um vídeo. Ela nunca inicia um job de reconhecimento de fala: quando informa `requiresAsync`, chame `POST /v1/transcript` para executar a transcrição.

A descoberta responde o que transcrever; a extração responde o que foi dito. Manter as duas separadas significa que você pode buscar e enumerar primeiro e depois enviar apenas os links escolhidos para uma requisição de transcrição ou de lote.

## Feita para uso em produção

A superfície é pequena de propósito, e as partes que importam para um serviço estão documentadas em vez de adivinhadas.

- Uma credencial: autentique-se com uma chave de API enviada como token Bearer, ou com `X-API-Key` de um script ou servidor.
- Chaves com escopo: conceda apenas os escopos de que quem chama precisa, com `transcripts` e `batches` cobrindo a extração e o trabalho em lote.
- Erros estruturados: falhas de extração e validação retornam um objeto de erro com um `code` estável e um `message` legível; as respostas de autenticação (401) e de limite de taxa (429) usam um corpo de erro plano mais simples.
- Limites acionáveis: uma requisição limitada por taxa retorna `429` com `Retry-After`, e as respostas bem-sucedidas trazem cabeçalhos `X-RateLimit-*` para que um cliente possa recuar corretamente.
- Um contrato publicado: o documento OpenAPI completo sustenta a API, então você pode gerar um cliente, simular um servidor ou validar respostas reais contra o esquema.
- Um irmão para agentes: a mesma conta e as mesmas ferramentas são acessíveis pelo servidor MCP do transcript.im se quem chama for um cliente de IA em vez de um serviço.

## Relacionados

- [Documentação da API](/docs)
- [Documento OpenAPI](/docs/openapi.json)
- [Servidor MCP](/pt-BR/mcp)
- [Agent Skills](/pt-BR/skills)
- [Gerador de transcrições do YouTube](/pt-BR/youtube-transcript)
- [Resumidor de vídeos do YouTube](/pt-BR/youtube-video-summarizer)
- [Gerador de legendas do YouTube](/pt-BR/youtube-subtitle-generator)
- [Baixador de legendas do YouTube](/pt-BR/youtube-subtitle-downloader)
- [Transcrição de canais do YouTube](/pt-BR/youtube-channel-transcript)
- [Transcrição de playlists do YouTube](/pt-BR/youtube-playlist-transcript)
## Perguntas frequentes sobre a API de transcrições

### O que é a API do transcript.im?

A API do transcript.im é uma superfície REST que transforma um link público de vídeo ou áudio em uma transcrição com carimbos de data e hora, usando primeiro as legendas existentes e a transcrição por IA quando um vídeo não tem nenhuma.

### Quais plataformas a API do transcript.im suporta?

Ela extrai transcrições do YouTube, TikTok, Instagram, LinkedIn e Twitter/X detectando a plataforma do link que você envia. YouTube, TikTok e LinkedIn usam as legendas primeiro com o reconhecimento de fala como alternativa; Instagram e X não têm faixa de legendas e vão direto para o reconhecimento de fala.

### O que acontece quando um vídeo não tem legendas?

Quando um vídeo não tem nenhuma faixa de legendas, a API inicia um job de ASR e retorna um job id; você consulta esse job até a transcrição ficar pronta, então a requisição nunca bloqueia no reconhecimento de fala.

### Posso transcrever um arquivo local de áudio ou vídeo?

Sim. `POST /v1/transcript` aceita um corpo `multipart/form-data` com uma parte `file` em vez de uma URL. Um arquivo enviado vai direto para o reconhecimento de fala, então retorna um job `202` — ou um resultado `200` se terminar dentro do orçamento de espera.

### A API do transcript.im pode retornar carimbos de data e hora com o texto?

Sim. As respostas JSON trazem segmentos com carimbos de data e hora e as respostas de texto podem manter um prefixo de carimbo de data e hora por linha, para você voltar ao momento em que uma fala foi dita.

### Como peço uma transcrição em um idioma específico?

Envie uma lista de prioridade de idiomas separada por vírgulas, incluindo entradas `asr` e `asr-<code>`. Uma correspondência de legendas é retornada diretamente; quando existem legendas mas nenhuma corresponde à lista, a requisição continua para a transcrição por IA e retorna um job `202`, e um `404` com os idiomas disponíveis só é retornado quando o reconhecimento de fala não é permitido.

### Como sei quando uma transcrição assíncrona está pronta?

Consulte `GET /v1/transcript/job/{id}` com a mesma credencial até que ele informe sucesso ou falha, ou assine `GET /v1/transcript/job/{id}/events` para receber atualizações do servidor. Uma consulta de job retorna `200` mesmo quando o job falhou, então leia os campos `status` e `error` em vez do código HTTP.

### A API do transcript.im suporta extração em lote?

Sim. Um lote aceita uma lista de URLs, uma playlist ou um canal, acompanha o status de cada item e retorna os itens página a página.

### Quais formatos de exportação posso baixar?

Um lote finalizado é exportado como `txt`, `csv`, `json`, `srt`, `vtt` ou `zip`; uma única transcrição salva é baixada como `txt`, `srt`, `vtt`, `json` ou `md`.

### Onde ficam as transcrições salvas?

A biblioteca da conta é onde ficam as transcrições salvas e os registros de lote, em `/v1/library`. Ela expõe rotas de listar, ler, baixar, relacionado e excluir, e suas leituras são restritas à conta e nunca iniciam uma extração nova.

### O que o endpoint de legendas do YouTube retorna?

`GET /v1/youtube/captions` retorna os metadados da faixa de legendas de um vídeo junto com o texto das legendas. Ela nunca inicia um job de reconhecimento de fala; quando informa `requiresAsync`, chame `POST /v1/transcript` para executar a transcrição.

### Como a API do transcript.im informa erros e limites de taxa?

Erros de extração e validação usam um objeto com `code` e `message`; a autenticação retorna um `401` plano, e o limite de taxa retorna um `429` plano com `Retry-After` mais cabeçalhos `X-RateLimit-*` para que um cliente possa recuar corretamente.

## Adicione transcrições ao seu produto

Crie uma chave de API, envie um link de vídeo ou um arquivo local e leia a transcrição como JSON ou texto simples.

- [Criar uma chave de API](/app/account/api-keys)
- [Ler a documentação](/docs)