Referência da API

Como funciona#

Cada transcrição é uma tarefa. Você envia uma fonte, a tarefa roda em segundo plano e, quando ela termina com sucesso, aponta para uma transcrição que você pode ler ou exportar quantas vezes quiser. URL base: https://www.transcriptdock.com. Todas as requisições e respostas são em JSON.

# 1. Submit
curl -X POST https://www.transcriptdock.com/v1/jobs \
  -H "Authorization: Bearer td_live_YOUR_KEY" \
  -H "Idempotency-Key: video-7680721699171601694" \
  -H "Content-Type: application/json" \
  -d '{ "source": { "url": "https://www.tiktok.com/@tiktok/video/7680721699171601694" }, "mode": "captions_only" }'
 
# 2. Wait (returns as soon as the job finishes, up to 25 s per call)
curl "https://www.transcriptdock.com/v1/jobs/11111111-1111-4111-8111-111111111111?wait=25" \
  -H "Authorization: Bearer td_live_YOUR_KEY"
 
# 3. Export
curl "https://www.transcriptdock.com/v1/transcripts/22222222-2222-4222-8222-222222222222/export?format=srt" \
  -H "Authorization: Bearer td_live_YOUR_KEY"

Autenticação#

Crie chaves na página Chaves de API. Uma chave é mostrada uma única vez, tem o formato td_live_... e vai no cabeçalho Authorization de cada requisição. As chaves têm escopos escolhidos na criação: jobs:read, jobs:write, transcripts:read, uploads:write. Crie uma chave por integração, para poder revogar uma delas sozinha.

Authorization: Bearer td_live_YOUR_KEY

Idempotency-Key#

Obrigatório em POST /v1/jobs, /v1/batches, /v1/jobs/{id}/retry, /v1/video-discoveries e /v1/language-discoveries: qualquer texto de 8 a 128 caracteres ASCII imprimíveis. Enviar a mesma chave com o mesmo corpo em até 48 horas devolve o objeto original, então uma requisição repetida nunca cria nem cobra duas vezes. A mesma chave com um corpo diferente retorna 409 IDEMPOTENCY_CONFLICT. Uma boa chave é o seu próprio id para o item que você está transcrevendo.

X-Request-Id#

Toda resposta traz um. Informe-o ao entrar em contato com o suporte.

Endpoints#

Criar uma tarefa#

source.urlstringOpcional

Um vídeo público: do YouTube (watch?v=, youtu.be, shorts, live) ou do TikTok (tiktok.com/@user/video/…, links de compartilhamento vm.tiktok.com). Qualquer outro link https para um arquivo de áudio ou vídeo é tratado como link direto de mídia (transcrição por IA). Um entre url ou upload_id é obrigatório.

source.upload_iduuidOpcional

Um arquivo que você enviou (veja Envios de arquivo). Sempre transcrição por IA.

mode"captions_only" | "auto" | "transcribe"Obrigatório

captions_only: as legendas do próprio vídeo, 1 crédito; falha com NO_CAPTIONS se não houver nenhuma. auto: legendas quando existirem (1 crédito), caso contrário transcrição por IA. transcribe: sempre transcrição por IA do áudio, 2 créditos por minuto iniciado, com tempo de cada palavra. A transcrição por IA exige um plano pago.

caption_languagesstring[]Opcional

Idiomas de legenda preferidos, em ordem, por exemplo ["en", "es"], até 5. Padrão: a faixa padrão do vídeo. Somente para captions_only e auto.

caption_preference"prefer_creator" | "creator_only" | "automatic_only"Opcional

Se aceita legendas enviadas pelo criador, legendas automáticas do YouTube ou ambas (padrão prefer_creator: a do criador primeiro).

languagestringOpcional

Dica do idioma falado para a transcrição por IA (BCP 47). Padrão: detectar.

max_creditsintegerOpcional

Limite de gasto para a transcrição por IA. A mídia é medida antes; se o custo passar do limite, a tarefa falha com BUDGET_EXCEEDED e nada é cobrado. Padrão: o suficiente para 2 horas.

webhook_endpoint_iduuidOpcional

Recebe job.succeeded / job.failed neste webhook.

metadataobjectOpcional

Até 10 valores de texto (chaves com até 64 e valores com até 256 caracteres). Devolvidos nos eventos de webhook. Não afeta o cache.

Retorna 202 com a tarefa. Se o seu workspace já tiver uma transcrição do mesmo vídeo com as mesmas opções, retorna 200 com uma tarefa concluída, sem custo (billing.kind: "cached").

{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "queued",
  "stage": "resolve",
  "result_id": null,
  "error": null,
  "billing": { "credits_reserved": 2, "credits_charged": 0, "kind": "captions" },
  "source": { "platform": "tiktok", "media_id": "7680721699171601694", "canonical_url": "https://www.tiktok.com/@tiktok/video/7680721699171601694", "title": null, "upload_id": null },
  "options": { "mode": "auto", "language": null, "caption_preference": "prefer_creator" },
  "created_at": "2026-09-16T10:00:00.000Z"
}

O objeto da tarefa#

iduuidOpcional

Id da tarefa.

statusstringOpcional

queued → processing (→ awaiting_provider durante a transcrição por IA) → succeeded, failed ou cancelled. Os três últimos são finais.

stagestring | nullOpcional

Em que etapa uma tarefa em execução está: resolve, captions, acquire_audio, submit_asr, wait_asr, finalize. Apenas informativo.

result_iduuid | nullOpcional

A transcrição, quando a tarefa termina com succeeded.

errorobject | nullOpcional

Em caso de falha: code, message, retryable e, opcionalmente, details.detail. Os mesmos códigos de Erros.

billingobjectOpcional

credits_reserved (reservados durante a execução, 0 quando termina), credits_charged (final), kind: captions, ai_transcription ou cached.

sourceobjectOpcional

platform, media_id, canonical_url, title, upload_id.

optionsobjectOpcional

mode, language, caption_preference, como aceitos.

created_atdate-timeOpcional

UTC.

Obter uma tarefa#

Retorna a tarefa. Com wait (de 0 a 25 segundos), a requisição fica aberta e responde assim que a tarefa estiver final, então uma única chamada substitui um laço de consultas. As leituras têm limite próprio, de 120 por minuto.

Listar tarefas#

Da mais recente para a mais antiga, com limit de 1 a 100. Envie o next_cursor da resposta de volta como cursor para a próxima página. Adicione platform e source_id (o source.media_id de uma tarefa) juntos para ver apenas as tarefas de um vídeo, em qualquer modo. É assim que um cliente verifica se o workspace já tem uma transcrição antes de enviar o mesmo vídeo de novo.

Cancelar uma tarefa#

Cancela uma tarefa que ainda não começou a transcrição por IA; a reserva é liberada. Depois disso, retorna 409 CANCELLATION_NOT_ALLOWED e a tarefa termina.

Tentar de novo uma tarefa#

Cria uma nova tarefa a partir de uma que falhou com erro retryable. Exige um novo Idempotency-Key; corpo opcional { "max_credits": 40 }. Tem o mesmo preço de uma tarefa nova. Falhas definitivas (vídeo privado, sem legendas) retornam 409 JOB_NOT_RETRYABLE: corrija a entrada e envie de novo.

A transcrição#

iduuidOpcional

Igual ao result_id da tarefa.

sourceobjectOpcional

platform, media_id, canonical_url, title.

source_originstringOpcional

creator_captions, platform_captions (legendas geradas pela plataforma, como as automáticas do YouTube) ou speech_recognition (transcrição por IA).

languagestring | nullOpcional

Tag BCP 47 do texto.

textstringOpcional

A transcrição inteira em texto simples.

segmentsarrayOpcional

Trechos do tamanho de legendas: { start, end, text } em segundos.

wordsarray | nullOpcional

{ start, end, text, confidence } por palavra. Somente transcrição por IA.

timing_granularity"word" | "segment" | "none"Opcional

Tempo mais preciso disponível.

duration_secondsnumber | nullOpcional

Duração da mídia.

extraction_versionstringOpcional

Versão do pipeline que produziu o resultado.

recognitionobject | nullOpcional

Somente transcrição por IA: model, profile, quality_status (validated_language: testamos o idioma; provider_supported: o modelo lista o idioma; experimental_language: a qualidade pode variar).

created_atdate-timeOpcional

UTC.

{
  "id": "22222222-2222-4222-8222-222222222222",
  "source": { "platform": "youtube", "media_id": "dQw4w9WgXcQ", "canonical_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "title": "Never Gonna Give You Up" },
  "source_origin": "creator_captions",
  "language": "en",
  "text": "Never gonna give you up. Never gonna let you down.",
  "segments": [
    { "start": 0, "end": 2.4, "text": "Never gonna give you up" },
    { "start": 2.4, "end": 4.9, "text": "Never gonna let you down" }
  ],
  "words": null,
  "timing_granularity": "segment",
  "duration_seconds": 212.0,
  "recognition": null,
  "extraction_version": "worker-0.1.0",
  "created_at": "2026-09-16T10:00:14.000Z"
}

As transcrições são mantidas pelo período de retenção do seu plano (7 dias no teste, 30 no Starter, 90 no Pro e no Scale). DELETE /v1/transcripts/{id} remove uma antes disso.

Exportar uma transcrição#

Grátis e sem limite. srt e vtt precisam de tempos; uma transcrição sem tempos retorna 422 TIMESTAMPS_UNAVAILABLE.

Lotes#

Uma requisição, muitos vídeos. Cada item tem os mesmos campos de Criar uma tarefa; o lote inteiro é aceito ou recusado de uma vez. Itens por lote: 1 no teste, 10 no Starter, 25 no Pro e 50 no Scale.

itemsJobRequest[]Obrigatório

De 1 a 50 requisições de tarefa.

webhook_endpoint_iduuidOpcional

Recebe um batch.completed quando todos os itens estiverem finais.

metadataobjectOpcional

Devolvido no evento batch.completed.

curl -X POST https://www.transcriptdock.com/v1/batches \
  -H "Authorization: Bearer td_live_YOUR_KEY" \
  -H "Idempotency-Key: playlist-2026-09-16" \
  -H "Content-Type: application/json" \
  -d '{ "items": [
        { "source": { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }, "mode": "captions_only" },
        { "source": { "url": "https://www.tiktok.com/@tiktok/video/7680721699171601694" }, "mode": "captions_only" }
      ] }'

O objeto do lote tem status (queued, processing, succeeded, partial_success, failed, cancelled), contagens (total_items, succeeded_items, failed_items, cancelled_items) e items, cada um com o seu job_id. Leia com GET /v1/batches/{id}; cada item é uma tarefa comum.

Envios de arquivo#

Seu próprio áudio ou vídeo (mp3, wav, m4a, ogg, aac, mp4, webm; até 250 MB e 2 horas). Reserve um espaço, envie o arquivo com PUT para a URL assinada, marque como concluído e depois envie-o como tarefa com source.upload_id. Envios sempre usam transcrição por IA.

# 1. Reserve
curl -X POST https://www.transcriptdock.com/v1/uploads \
  -H "Authorization: Bearer td_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "interview.mp3", "content_type": "audio/mpeg", "bytes": 48213920 }'
# -> { "id": "33333333-...", "signed_upload_url": "https://...", "expires_at": "...", "status": "pending" }
 
# 2. Upload the bytes (same Content-Type you declared)
curl -X PUT "SIGNED_UPLOAD_URL" -H "Content-Type: audio/mpeg" --data-binary @interview.mp3
 
# 3. Complete
curl -X POST https://www.transcriptdock.com/v1/uploads/33333333-3333-4333-8333-333333333333/complete \
  -H "Authorization: Bearer td_live_YOUR_KEY"
 
# 4. Transcribe it
curl -X POST https://www.transcriptdock.com/v1/jobs \
  -H "Authorization: Bearer td_live_YOUR_KEY" \
  -H "Idempotency-Key: interview-01" \
  -H "Content-Type: application/json" \
  -d '{ "source": { "upload_id": "33333333-3333-4333-8333-333333333333" }, "mode": "transcribe" }'

filenamestringObrigatório

Até 255 caracteres.

content_typestringObrigatório

O tipo MIME do arquivo, por exemplo audio/mpeg ou video/mp4. Envie o mesmo valor no PUT.

bytesintegerObrigatório

Tamanho exato do arquivo. O PUT precisa corresponder.

A URL assinada vale por 24 horas; depois disso, reserve um novo espaço.

Webhooks#

Registre uma URL https e passe o seu id como webhook_endpoint_id ao enviar. Enviamos um evento por POST quando a tarefa ou o lote termina. A resposta inclui o secret de assinatura, uma única vez. Registrar e desativar endpoints exige uma sessão iniciada, então faça isso na página Webhooks do painel; uma chave de API recebe 403 FORBIDDEN nessas operações, mas pode listar os endpoints.

urlstringObrigatório

URL https, com até 2048 caracteres.

descriptionstringOpcional

Um rótulo para a sua referência.

Eventos#

{
  "event_id": "44444444-4444-4444-8444-444444444444",
  "type": "job.succeeded",
  "created_at": "2026-09-16T10:00:14.000Z",
  "job_id": "11111111-1111-4111-8111-111111111111",
  "batch_id": null,
  "result_id": "22222222-2222-4222-8222-222222222222",
  "metadata": { "order": "8812" },
  "error": null
}

• job.succeeded: busque ou exporte o result_id.
• job.failed: error traz o código.
• batch.completed: todos os itens estão finais; leia o lote para ver o resultado de cada item.

Responda com qualquer código 2xx em poucos segundos. Entregas que falham são reenviadas com intervalos crescentes e podem ser reenviadas pelo painel. Um evento pode chegar mais de uma vez: remova duplicados pelo event_id.

Verificar a assinatura#

Cabeçalhos X-TranscriptDock-Event-Id, X-TranscriptDock-Timestamp e X-TranscriptDock-Signature. A assinatura é o HMAC-SHA256 (hex) de {event_id}.{timestamp}.{raw_body} com o seu secret. Rejeite qualquer evento com mais de cinco minutos.

import crypto from "node:crypto";
 
export function verify(eventId: string, timestamp: string, rawBody: string, signature: string, secret: string): boolean {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${eventId}.${timestamp}.${rawBody}`).digest("hex");
  return expected.length === signature.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Encontrar vídeos#

Pesquise no YouTube ou liste um canal, uma playlist ou um perfil do TikTok, e depois envie as URLs como tarefas. Uma descoberta roda em segundo plano, como uma tarefa: leia-a com GET /v1/video-discoveries/{id} até que status seja succeeded. São 1 crédito por página; os resultados são mantidos por 24 horas.

kindstringObrigatório

youtube_search, youtube_channel_videos, youtube_channel_search, youtube_playlist_videos ou tiktok_user_videos.

querystringOpcional

Texto da pesquisa (youtube_search, youtube_channel_search).

channelstringOpcional

@handle, id do canal ou URL do canal (tipos de canal).

playliststringOpcional

Id ou URL da playlist (youtube_playlist_videos).

userstringOpcional

@user ou URL do perfil (tiktok_user_videos).

limitintegerOpcional

Vídeos por página, de 1 a 50, padrão 20. TikTok: no máximo 10.

cursorstringOpcional

next_cursor da página anterior. Somente YouTube.

include_detailsbooleanOpcional

Somente TikTok: também busca curtidas, comentários, hashtags e idiomas das legendas de cada vídeo.

curl -X POST https://www.transcriptdock.com/v1/video-discoveries \
  -H "Authorization: Bearer td_live_YOUR_KEY" \
  -H "Idempotency-Key: search-async-rust-1" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "youtube_search", "query": "async rust", "limit": 5 }'

O POST responde 202 com status: "queued". Uma resposta de GET /v1/video-discoveries/{id} já concluída tem este formato:

{
  "id": "55555555-5555-4555-8555-555555555555",
  "kind": "youtube_search",
  "status": "succeeded",
  "request": { "kind": "youtube_search", "query": "async rust", "limit": 5 },
  "videos": [
    {
      "platform": "youtube",
      "video_id": "wXtngLBkK4Q",
      "url": "https://www.youtube.com/watch?v=wXtngLBkK4Q",
      "title": "Async Rust explained in 20 minutes",
      "channel_id": "UCSp-OaMpsO8K0KkOqyBl7_w",
      "channel_title": "Let's Get Rusty",
      "duration_s": 1155,
      "published_at": null,
      "published_text": "5 months ago",
      "view_count": 83635,
      "view_count_text": "83,635 views",
      "thumbnail_url": "https://i.ytimg.com/vi/wXtngLBkK4Q/hq720.jpg",
      "tiktok": null
    }
  ],
  "profile": null,
  "next_cursor": "opaque-token",
  "error": null,
  "created_at": "2026-09-16T12:00:00.000Z",
  "updated_at": "2026-09-16T12:00:03.000Z",
  "expires_at": "2026-09-17T12:00:00.000Z"
}

Idiomas de legenda de um vídeo#

Corpo { "source": { "url": "https://www.youtube.com/watch?v=..." } } com um Idempotency-Key (somente YouTube, 1 crédito). Leia GET /v1/language-discoveries/{id} para ver a lista de faixas de legenda, com os códigos, se são do criador ou automáticas e qual é a padrão. Use os códigos em caption_languages.

Uso e recursos#

{
  "plan": "pro",
  "period_end": "2026-10-16T00:00:00.000Z",
  "credits_remaining": 5840,
  "credits_total": 6000,
  "credits_reserved": 4,
  "prepaid_credits": 0,
  "transcribe_credits_per_minute": 2,
  "minimum_billable_seconds": 60,
  "subscription": {
    "status": "active",
    "interval": "yearly",
    "cancel_at_period_end": false,
    "current_period_end": "2027-09-16T00:00:00.000Z"
  }
}

credits_remaining já desconta credits_reserved (reservas de tarefas em execução). prepaid_credits são créditos comprados, que nunca expiram.

subscription é a assinatura da Stripe por trás de um plano pago, e null quando não há uma: o seu status, o interval de cobrança (monthly ou yearly), cancel_at_period_end e current_period_end, que mostram quando o plano é renovado ou termina. period_end é quando os créditos mensais são renovados, todo mês, inclusive nos planos anuais.

O que a sua chave pode fazer agora: por fonte (youtube, tiktok, instagram, upload, direct), quais modos estão disponíveis, além dos limites e preços. Use isso em vez de fixar valores no código; o teste, por exemplo, informa auto e transcribe como false.

{
  "youtube": { "enabled": true, "captions_only": true, "auto": true, "transcribe": true, "social_acquisition_fee": true },
  "tiktok": { "enabled": true, "captions_only": true, "auto": true, "transcribe": true, "social_acquisition_fee": true },
  "instagram": { "enabled": false, "captions_only": false, "auto": false, "transcribe": false, "social_acquisition_fee": true, "native_captions": "unverified_disabled" },
  "upload": { "enabled": true, "captions_only": false, "auto": true, "transcribe": true, "social_acquisition_fee": false },
  "direct": { "enabled": true, "captions_only": false, "auto": true, "transcribe": true, "social_acquisition_fee": false },
  "max_duration_ms": 7200000,
  "max_media_bytes": 262144000,
  "export_formats": ["txt", "json", "srt", "vtt"],
  "recognition_profiles": ["standard"],
  "transcribe_credits_per_minute": 2,
  "minimum_billable_seconds": 60,
  "price_version": "2026-09-14",
  "asr_enabled": true,
  "instagram_enabled": false,
  "free_caption_credits": 50,
  "free_caption_credits_period": "month"
}

Limites de requisições#

Acima de um limite você recebe 429 RATE_LIMITED com um cabeçalho retry-after (em segundos) e details.detail indicando qual limite. Nada é cobrado. Webhooks e ?wait=25 mantêm você bem abaixo do limite de leituras.

Erros#

Todo erro tem o mesmo formato. retryable: true significa que a mesma requisição pode dar certo depois: espere os segundos de retry-after, se houver, ou aguarde alguns segundos, e reutilize o mesmo Idempotency-Key, para não duplicar nada. Qualquer outro erro exige uma mudança do seu lado.

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Not enough credits. Buy credits or upgrade your plan to continue.",
    "retryable": false,
    "details": { "detail": "This job needs more credits than you have left. Buy credits or upgrade your plan." },
    "doc_url": "https://www.transcriptdock.com/docs/api-reference#error-codes"
  },
  "request_id": "66666666-6666-4666-8666-666666666666"
}

Uma tarefa que falha depois de aceita continua com 200 em GET /v1/jobs/{id}, com status: "failed" e o mesmo objeto de erro em error. Nada é cobrado por uma tarefa com falha.

Códigos#