Referência da API REST

Use https://api.transcript1.com/v1 como URL base da API.

• Envie e receba corpos JSON. Os nomes dos campos usam snake_case.
• Datas e horários vêm em UTC no formato ISO 8601, como 2026-10-13T09:30:00.000Z.
• Durações e marcações de tempo da transcrição usam segundos.
• As respostas de erro seguem um formato único. Consulte Erros.
• Nas respostas a chamadas autenticadas, confira X-RateLimit-Limit e X-RateLimit-Remaining para acompanhar sua cota de requisições. Os limites estão em Planos, minutos e limites.
• Com source=auto, buscamos primeiro legendas no idioma original do YouTube, X, TikTok, Bluesky, Dailymotion e LinkedIn. Se não pudermos usá-las, transcrevemos o áudio com speech-to-text. Nem todo vídeo tem legendas. O modo source=captions (somente legendas) não baixa áudio nem recorre ao STT: se não houver uma faixa que possa ser usada, retorna no_captions. Com source=stt ou identificação de falantes, vamos direto ao áudio. Em Links aceitos e opções, você encontra as restrições de cada plataforma e quais trazem marcações de tempo por segmento ou por palavra.

A especificação OpenAPI está disponível para download nestes formatos:

• JSON
• YAML

Para autenticar a chamada, use o cabeçalho Authorization no formato Authorization: Bearer <token>.

• Chave de API: começa com t1_ e permite chamar qualquer endpoint. Crie a sua em “API keys”.
• Token de acesso OAuth: começa com t1o_. Clientes MCP, como Claude e ChatGPT, recebem esse token ao conectar sua conta. Ele usa os escopos transcriptions:read e transcriptions:write.

Escopo	Chamadas permitidas
transcriptions:read	GET /v1/transcriptions, GET /v1/transcriptions/:id, GET /v1/transcriptions/:id/upload e GET /v1/account
transcriptions:write	POST /v1/transcriptions, DELETE /v1/transcriptions/:id e POST /v1/transcriptions/:id/upload/complete

• Se faltar o escopo exigido pela chamada, a API responde 403 insufficient_scope.
• Se você não enviar uma credencial válida, a resposta será 401 unauthorized.

O envio de partes do arquivo usa outro token: o X-Upload-Token, que você recebe ao criar o upload. Passe esse cabeçalho em PUT /v1/transcriptions/:id/upload/chunks/:index. Veja o passo a passo em Uploads.

Use Idempotency-Key para poder repetir uma chamada a POST /v1/transcriptions sem criar outra transcrição por engano.

Escolha um valor de 1 a 255 caracteres e envie no cabeçalho da requisição. Esse campo não vai na query string.

• Se a chave e os parâmetros forem os mesmos, a API devolve a transcrição original e não cobra de novo.
• Se você mantiver a chave, mas mudar os parâmetros, receberá 409 idempotency_conflict.
• Ao repetir a criação de um upload em partes com a mesma chave, você recebe um token de upload novo.

• Quando a API recusa a chamada, você recebe um erro de requisição.
• Quando ela aceita a transcrição, mas o processamento falha depois, o objeto da transcrição fica com status igual a failed.

Como ler a resposta de erro

Se uma chamada a /v1 falhar, procure o objeto error na resposta. Ele traz code, message e retryable.

• Use code para decidir o que fazer na sua aplicação.
• Exiba message como explicação para o usuário. O texto pode mudar.
• Se retryable for true, vale repetir a mesma chamada mais tarde.

Dependendo do erro, outros campos aparecem junto de retryable:

Campo	Código associado	O que informa
action_url	insufficient_minutes	Link para contratar um plano ou comprar uma recarga.
minutes_needed, minutes_remaining	insufficient_minutes	Quantos minutos a chamada precisa consumir e quantos você tem. Se a duração ainda não for conhecida, o primeiro valor será null.
supported_platforms	unsupported_platform	Valores de plataforma aceitos: ["youtube", "x", "tiktok", "instagram", "facebook", "bluesky", "twitch", "dailymotion", "pinterest", "linkedin", "snapchat"].
missing_chunks	upload_incomplete	Índices das partes que ainda faltam no upload.
max_bytes	media_too_large	Tamanho máximo de arquivo permitido na sua conta, em bytes.
params	invalid_request	Objeto com os campos inválidos do corpo ou da query string e a explicação do problema em cada um.

Quando a API recusa a chamada

Status HTTP	code	Pode repetir?	O que aconteceu
400, 422	invalid_request	Não	Falta um parâmetro ou há um campo inválido no corpo. Isso inclui combinar diarize com source: "captions", combinar reuse_recent com webhook_url ou enviar um JSON inválido.
422	invalid_url	Não	O link não foi aceito ou platform não corresponde ao endereço. Use YouTube, X, TikTok, Instagram, Facebook, Bluesky ou outra plataforma de Links aceitos e opções.
422	unsupported_platform	Não	O valor de platform não está entre as plataformas aceitas.
422	unsupported_media	Não	A extensão do arquivo enviado não está entre as aceitas.
401	unauthorized	Não	Falta a credencial, ou ela é inválida, expirou ou foi revogada. Também vale para token de upload inválido ou expirado.
403	insufficient_scope	Não	O token OAuth não tem o escopo necessário: transcriptions:read ou transcriptions:write.
403	email_not_verified	Não	Você precisa confirmar o e-mail antes de criar uma transcrição.
402	insufficient_minutes	Não	O saldo disponível é 0 ou não cobre a duração da transcrição.
402	no_active_plan	Não	A compra de recarga exige um plano pago ativo. Esse erro vem do endpoint de cobrança do painel, não dos endpoints de transcrição.
404	not_found	Não	Essa transcrição não existe ou é de outra equipe.
409	upload_incomplete	Não	Ainda faltam partes do arquivo. Envie o que falta e peça a conclusão do upload novamente.
409	invalid_state	Não	A transcrição já saiu da etapa de espera pelo upload. Não é mais possível enviar partes ou concluir o envio.
409	idempotency_conflict	Não	Você já usou esse Idempotency-Key com outros parâmetros.
413	media_too_large	Não	O tamanho do arquivo ultrapassa o seu limite. Confira Uploads.
413	invalid_request	Não	O corpo JSON ultrapassa 1 MB. Para arquivos grandes, o código é media_too_large.
429	rate_limited	Sim	Você atingiu o limite de chamadas por minuto. Aguarde o número de segundos de Retry-After.
429	too_many_active_jobs	Sim	Você atingiu o limite de transcrições em andamento ou de uploads abertos. Aguarde o número de segundos de Retry-After.
500	internal_error	Sim	Tivemos um erro interno. Aguarde um pouco e tente novamente.
503	service_unavailable	Sim	O transcript1 está indisponível no momento. Aguarde um pouco e tente novamente.

Quando o navegador autentica a chamada pelo cookie de login, também conferimos a origem. Se a chamada vier de outro site, a resposta será 403 forbidden_origin.

Essa verificação não afeta chamadas à API com o cabeçalho Authorization.

Toda resposta 429 informa em Retry-After quantos segundos você deve esperar. Consulte os valores de cada plano em Planos, minutos e limites.

Quando e como tentar novamente

• Repita a chamada apenas se retryable for true. Isso vale para rate_limited, too_many_active_jobs, internal_error e service_unavailable.
• Respeite a espera de Retry-After quando ele vier na resposta. Sem esse cabeçalho, aumente o intervalo a cada tentativa.
• Para repetir POST /v1/transcriptions, mantenha o mesmo Idempotency-Key. Assim você evita outra cobrança caso a primeira chamada tenha funcionado.
• Nos demais erros, corrija a causa antes de enviar a chamada novamente.

Falhas durante a transcrição

Se o processamento falhar, o objeto da transcrição fica com status igual a failed. O objeto error traz code e message para explicar o problema.

Isso pode acontecer depois da resposta à chamada de criação. Leia error nas consultas de status ou ao receber o webhook transcription.failed.

error.code	O que aconteceu	Vale tentar novamente?
media_unavailable	O vídeo não existe ou saiu do ar.	Não. Confira o link.
media_private	O vídeo é privado.	Não. Envie um post público ou um vídeo do YouTube público ou não listado.
login_required	A plataforma só libera o conteúdo após login.	Não. O serviço não repete essa tentativa.
no_audio	Não há faixa de áudio no vídeo.	Não. O serviço não repete essa tentativa.
age_restricted	O acesso ao vídeo tem restrição de idade.	Não pelo link. Envie o arquivo por upload.
live_stream	A transmissão está ao vivo ou ainda não começou.	Espere a transmissão terminar.
no_captions	Você escolheu captions em source, mas não há uma faixa de legendas que possa ser usada.	Troque para source: "auto" ou "stt".
media_too_long	A gravação ultrapassa o limite de 5 horas do speech-to-text.	Divida a gravação antes de enviar.
unsupported_media	Não foi possível ler o arquivo, ou ele não tem faixa de áudio.	Envie outro arquivo em um formato aceito.
no_speech	Nenhuma fala detectada.	Não.
unsupported_language	O serviço não aceita o idioma da gravação.	Corrija language para um código aceito ou "auto".
insufficient_minutes	O saldo acabou antes de cobrarmos a transcrição.	Faça uma recarga antes de tentar.
fetch_failed	Não conseguimos baixar o áudio ou vídeo, mesmo após várias tentativas.	Sim. Tente mais tarde.
transcription_failed	A transcrição por speech-to-text falhou após várias tentativas.	Sim. Tente mais tarde.

Se a transcrição falhar ou você cancelar, não paga por ela. Se já tivermos descontado os minutos, eles voltam para o seu saldo.

Informe webhook_url na criação para receber um aviso quando a transcrição ficar pronta ou falhar. O transcript1 envia um POST assinado para esse endereço.

Esse recurso está disponível só na API REST. As ferramentas do servidor MCP não aceitam um parâmetro de webhook.

Configure o endereço de entrega

Na chamada a POST /v1/transcriptions, envie webhook_url assim:

• Se estiver enviando um link aceito ou criando um upload em partes, coloque o campo no corpo JSON.
• Se enviar o arquivo de uma vez, use um campo de formulário.

Confira os requisitos da URL:

• Precisa usar HTTPS.
• Não pode incluir usuário ou senha no endereço.
• Precisa apontar para um IP público.

Se o endereço for privado, de loopback, link-local ou de qualquer outro tipo não público, você recebe 422 invalid_request. Conferimos o endereço na criação da transcrição e antes de cada entrega.

Não envie webhook_url junto com reuse_recent=true.

Eventos

type	Quando você recebe
transcription.completed	O status muda para completed.
transcription.failed	O status muda para failed. Confira code e message em data.error.

Se você cancelar a transcrição, não enviamos webhook.

Payload

O aviso chega em JSON, com estes campos:

• created_at informa quando o evento foi criado.
• data traz o objeto da transcrição, mas sem o campo transcript.

Para buscar o texto, use o id de data em GET /v1/transcriptions/:id.

Também enviamos estes cabeçalhos:

• Content-Type: application/json
• User-Agent: transcript1-webhooks/1.0
• X-Transcript1-Signature, com a assinatura explicada abaixo.

Confira a assinatura antes de ler o JSON

Você encontra a assinatura de cada entrega em X-Transcript1-Signature, no formato t=<unix seconds>,v1=<hex digest>.

• t informa quando assinamos a requisição, em segundos Unix.
• v1 contém o HMAC-SHA256 em hexadecimal da string "<t>.<raw body>". Monte essa string com o valor de t, um ponto e o corpo exatamente como chegou. Use o segredo de assinatura inteiro como chave, com o prefixo whsec_.

Calcule a assinatura sobre os bytes originais do corpo antes de fazer o parse do JSON. Converter o JSON em objeto e depois em texto pode mudar os espaços ou a ordem das chaves. Se isso acontecer, a assinatura deixa de conferir.

• Faça a comparação das assinaturas em tempo constante.
• Recuse requisições com t muito distante da hora atual. A tolerância dos exemplos é de 5 minutos.
• No Express, receba o corpo como texto, sem passar pelo parser de JSON antes da verificação.
• No Flask, obtenha o corpo com request.get_data(as_text=True) e passe esse texto em raw_body.

Consulte ou troque o segredo de assinatura

Cada equipe tem um segredo de assinatura com o prefixo whsec_. Usamos esse mesmo segredo nos webhooks de todas as transcrições da equipe.

Você pode consultá-lo ou gerar outro na página “Webhooks”.

A troca vale imediatamente. A partir daí, todas as entregas usam o novo segredo.

Entregas e novas tentativas

• Responda com qualquer status 2xx para confirmar o recebimento.
• Outro status, erro de conexão ou falta de resposta em 10 segundos faz a tentativa falhar.
• Se a entrega falhar, tentamos de novo com backoff exponencial, até 6 tentativas no total. Os intervalos são de 2, 4, 8, 16 e 32 minutos. A última tentativa ocorre cerca de uma hora após a primeira.
• Informe a URL final. O transcript1 não segue redirecionamentos e considera respostas 3xx uma falha de entrega.
• Seu servidor pode receber o mesmo aviso mais de uma vez, por exemplo se responder depois do timeout. Confira data.id e type para não processar duplicatas.