Documentação para desenvolvedores

Documentação da API do TokCaption

Uma API REST para transcrever vídeos públicos do TikTok, executar análises de ganchos com IA e reescritas de roteiros, e exportar transcrições em escala. Autentique-se com uma chave de API, envie uma URL e consulte o resultado. O acesso à API está disponível no plano Pro.

REST API · v2.1.0

TokCaption API

Transcreva vídeos públicos do TikTok; execute análises de ganchos com IA; e exporte em escala — tudo por meio de uma API REST JSON limpa. Autentique-se com uma chave de API e comece em duas chamadas. Prefere assistentes de IA? As mesmas ferramentas estão disponíveis como um servidor MCP para Claude e ChatGPT.

URL base

https://www.tokcaption.com/api/v1

Autenticação

X-API-Key

Endpoints

27 em 6 grupos

Autenticação

Crie uma chave de API em Configurações → Chaves de API (plano Pro). Envie-a em cada requisição pelo cabeçalho X-API-Key. Painel e clientes móveis também podem enviar um JWT do Supabase como Authorization: Bearer <jwt>. Mantenha as chaves no servidor — nunca as inclua em um bundle de navegador.

curl "https://www.tokcaption.com/api/v1/billing/subscription" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Início rápido

Envie uma URL e, em seguida, consulte o job até que ele seja concluído. Uma única URL costuma terminar na própria resposta — verifique o status da resposta antes de consultar.

Etapa 1 — Enviar

POST /api/v1/jobs com suas URLs. Armazene o job_id retornado.

Etapa 2 — Consultar

GET /api/v1/jobs/{jobId} a cada 1–2s até que o status seja final e, então, leia items[].transcript_text.

Apenas uma URL e não quer aguardar? Use GET /api/v1/quick para um resultado síncrono.

Erros e limites de taxa

Todo erro retorna o mesmo envelope JSON. Trate a lógica com base em code, não no status HTTP nem na mensagem. Em 429, respeite o cabeçalho Retry-After.

Envelope de erro

{
  "success": false,
  "error": "Free plan allows 5 transcripts per day.",
  "code": "QUOTA_EXCEEDED",
  "message": "Free plan allows 5 transcripts per day.",
  "error_info": {
    "code": "QUOTA_EXCEEDED",
    "message": "Free plan allows 5 transcripts per day.",
    "details": {
      "limit_type": "daily",
      "daily_limit": 5,
      "retry_after_seconds": 43200
    }
  },
  "details": {
    "limit_type": "daily",
    "daily_limit": 5,
    "retry_after_seconds": 43200
  }
}

Todos os códigos de erro

Código	HTTP	Significado
AUTH_REQUIRED	401	Credenciais ausentes ou inválidas. Envie um X-API-Key válido ou um cabeçalho Authorization: Bearer <jwt>.
VALIDATION_ERROR	400	Corpo da requisição, parâmetros de consulta ou caminho inválidos. A mensagem e os detalhes explicam o que corrigir.
PLAN_REQUIRED	403	Este recurso ou opção requer um plano Pro. Faça o upgrade para desbloquear.
NOT_FOUND	404	Trabalho, transcrição ou recurso não encontrado ou não pertence a você.
QUOTA_EXCEEDED	429	Limite de transcrições, agentes, downloads ou traduções atingido. Ele é redefinido diariamente (gratuito) ou a cada ciclo de cobrança (Pro). Veja details.reset_at.
RATE_LIMIT_EXCEEDED	429	Muitas solicitações de envio, consulta ou agente em um curto período. Respeite o cabeçalho Retry-After / details.retry_after_seconds.
DUPLICATE_REQUEST	409	Uma idempotency_key foi reutilizada. A solicitação original já foi executada.
TRANSLATION_LIMIT_EXCEEDED	429	Cota mensal de tradução atingida. Ela é redefinida no ciclo de cobrança.
UPSTREAM_TEMPORARY_ERROR	503	O TikTok bloqueou temporariamente a solicitação ou limitou a taxa de requisições. Tente novamente com espera progressiva.
SEGMENTS_UNAVAILABLE	400	Segmentos com marcação de tempo são necessários para este formato de exportação (srt/vtt), mas a transcrição não tem nenhum.
INTERNAL_ERROR	500	Erro inesperado no servidor. Tente novamente e entre em contato com o suporte se persistir.

Transcrição

Envie URLs públicas do TikTok para transcrição e acompanhe o andamento dos trabalhos.

POST/api/v1/jobs

Enviar job de transcrição

Limite de submit

Envie de 1 a N URLs públicas do TikTok para transcrição. O tamanho do lote é limitado pelo seu plano; uma única URL pode retornar um resultado pronto na própria resposta.

Autenticação: Chave de API ou JWTReq: application/jsonRes: application/json

curl -X POST "https://www.tokcaption.com/api/v1/jobs" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@creator/video/1234567890","https://www.tiktok.com/@creator/video/0987654321"],"output_language":"en","also_translate_to":["es"],"allow_asr_fallback":false,"include_download_assets":false,"idempotency_key":"client-req-001"}'

Uma única URL pode retornar HTTP 200 com um payload final de concluído ou com falha quando o processamento termina em linha.
Os lotes retornam HTTP 202 com job_id, um status agregado e status por item dentro de items.
Inspecione o array items para ver o status de cada vídeo: queued, processing, completed ou failed.
Definir include_download_assets: true no plano gratuito retorna PLAN_REQUIRED (403).

Campos do corpo

`urls`obrigatório string[]	URLs de vídeos do TikTok. O limite de lote do plano gratuito é 5.
`output_language` string	Idioma de destino da transcrição (código ISO). O padrão é en.
`also_translate_to` string[]	Idiomas adicionais para traduzir a transcrição.
`allow_asr_fallback` boolean	Transcreva o áudio quando não houver faixa de legendas. O padrão é false.
`include_download_assets` boolean	Mantenha os arquivos de vídeo/capa disponíveis para download. Somente Pro.
`idempotency_key` string	Chave de deduplicação; reutilizá-la retorna o job original.

Resposta de sucesso · HTTP 202

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "queued",
  "total_items": 2,
  "items": [
    {
      "id": "tx_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "input_url": "https://www.tiktok.com/@creator/video/1234567890",
      "status": "queued"
    }
  ]
}

Sucesso único imediato

HTTP 200

{
  "job_id": "51f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "completed",
  "total_items": 1,
  "completed": 1,
  "failed": 0,
  "items": [
    {
      "id": "tx_single_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "status": "completed",
      "output_language": "en",
      "source_language": "en",
      "selected_track_type": "creator",
      "transcript_text": "Whenever I'm asked to teach a beginner how to cook...",
      "metadata": {
        "author_username": "foodnetwork",
        "duration_seconds": 29
      },
      "completed_at": "2026-03-14T08:33:14.000Z"
    }
  ]
}

Falha única (sem legendas)

HTTP 200

{
  "job_id": "8a0d6d7a-78f0-4ab0-8a8c-72f8f5184de8",
  "status": "failed",
  "total_items": 1,
  "completed": 0,
  "failed": 1,
  "items": [
    {
      "id": "tx_single_2",
      "transcript_id": "d40b2545-7c62-4bbb-a7e3-020c663f18a0",
      "item_index": 0,
      "status": "failed",
      "error_code": "NO_CAPTIONS_AVAILABLE",
      "error_message": "Captions are not available for this TikTok video."
    }
  ]
}

Erros

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429DUPLICATE_REQUEST409UPSTREAM_TEMPORARY_ERROR503

GET/api/v1/jobs

Listar trabalhos

Liste seus trabalhos de transcrição, do mais recente para o mais antigo, com paginação por cursor.

Autenticação: Chave de API ou JWTReq: noneRes: application/json

curl -X GET "https://www.tokcaption.com/api/v1/jobs?cursor=2026-06-23T10%3A00%3A00.000Z" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Parâmetros

`cursor` string (ISO date) · query	Passe o next_cursor anterior para voltar a uma página anterior.
`limit` integer · query	Tamanho da página, de 1 a 50. Padrão: 20.
`status` string · query	Filtre pelo status do trabalho (ex.: completed, processing, failed).

Resposta de sucesso

{
  "jobs": [
    {
      "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
      "created_at": "2026-06-23T10:02:11.000Z",
      "updated_at": "2026-06-23T10:02:48.000Z",
      "origin": "api",
      "status": "completed",
      "collection_name": null
    }
  ],
  "next_cursor": "2026-06-23T10:02:11.000Z"
}

Erros

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/jobs/{jobId}

Consultar status do job

Limite de poll

Consulte um job até que ele chegue a um estado final. Retorna contagens agregadas e os detalhes completos de cada item.

Autenticação: Chave de API ou JWTReq: noneRes: application/json

curl -X GET "https://www.tokcaption.com/api/v1/jobs/b86f89f2-34f6-4b76-88f6-03c13c51b7a6" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Os estados finais do job são completed, partial ou failed; itens individuais dentro de um job podem ser diferentes.
Os itens concluídos incluem transcript_text, segments, translations, metadata e assets.
Consulte em um intervalo razoável (a cada 1–2s). Em HTTP 429, respeite retry_after_seconds.

Parâmetros

jobIdobrigatório

string · path

ID do trabalho retornado por POST /api/v1/jobs.

Resposta de sucesso

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "processing",
  "total_items": 2,
  "completed": 1,
  "failed": 0,
  "items": [
    {
      "id": "tx_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "status": "completed",
      "output_language": "en",
      "transcript_text": "Whenever I'm asked to teach a beginner...",
      "completed_at": "2026-03-14T08:33:14.000Z"
    },
    {
      "id": "tx_2",
      "transcript_id": "2448b6b8-7e07-46ef-96be-1f339abdb71f",
      "item_index": 1,
      "status": "processing"
    }
  ]
}

Erros

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404RATE_LIMIT_EXCEEDED429INTERNAL_ERROR500

POST/api/v1/jobs/{jobId}/cancel

Cancelar um job

Cancela itens em fila ou em processamento de um job. Os itens liberados devolvem a sua cota.

Autenticação: Chave de API ou JWTReq: noneRes: application/json

curl -X POST "https://www.tokcaption.com/api/v1/jobs/b86f89f2-34f6-4b76-88f6-03c13c51b7a6/cancel" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Parâmetros

jobIdobrigatório

string · path

ID do trabalho a cancelar.

Resposta de sucesso

{
  "cancelled_count": 3
}

Erros

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

GET/api/v1/quick

Transcrição rápida (uma URL)

Limite de submit

Envie uma única URL e aguarde (até cerca de 55s) por um resultado final — um atalho síncrono sobre os jobs.

Autenticação: Chave de API ou JWTReq: noneRes: application/json

curl -X GET "https://www.tokcaption.com/api/v1/quick?url=https%3A%2F%2Fwww.tiktok.com%2F%40creator%2Fvideo%2F1234567890" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Retorna HTTP 200 quando estiver em estado final (completed/failed), ou HTTP 202 se ainda estiver processando quando o período de espera terminar — então consulte /api/v1/jobs/{jobId}.

Parâmetros

urlobrigatório

string · query

Uma única URL de vídeo do TikTok.

Resposta de sucesso

{
  "job_id": "51f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "status": "completed"
}

Erros

AUTH_REQUIRED401VALIDATION_ERROR400QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/import/collection

Importação em massa

ProLimite de submit

Envie uma lista de URLs ou texto bruto contendo links. O plano gratuito aceita 1 URL; o envio em massa exige Pro.

Autenticação: Chave de API ou JWTReq: application/jsonRes: application/json

curl -X POST "https://www.tokcaption.com/api/v1/import/collection" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@creator/video/1234567890","https://www.tiktok.com/@creator/video/0987654321"],"output_language":"en"}'

Campos do corpo

`urls` string[]	Lista explícita de URLs. Forneça esta opção ou texto.
`text` string	Texto livre; links do TikTok são extraídos automaticamente.
`output_language` string	Idioma de destino da transcrição. O padrão é en.
`allow_asr_fallback` boolean	Transcreva o áudio quando não houver legendas. O padrão é false.

Resposta de sucesso · HTTP 202

{
  "total_urls_found": 5,
  "valid_urls": 4,
  "jobs_created": 1,
  "job_ids": [
    "b86f89f2-34f6-4b76-88f6-03c13c51b7a6"
  ],
  "invalid_urls": [
    "https://example.com/not-a-video"
  ]
}

Erros

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

Transcrições

Leia, pesquise, exporte e baixe transcrições finalizadas e seus arquivos.

GET/api/v1/history

Listar / pesquisar transcrições

Limite de poll

Histórico de transcrições paginado e pesquisável, com filtros de status, pasta e ordenação.

Autenticação: Chave de API ou JWTReq: noneRes: application/json

curl -X GET "https://www.tokcaption.com/api/v1/history?page=1" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Parâmetros

`page` integer · query	Número da página com base 1. O padrão é 1.
`limit` integer · query	Tamanho da página, de 1 a 100. Padrão: 15.
`search` string · query	Correspondência de texto completo no texto da transcrição e na URL de origem.
`status` string · query	completed \| failed \| all. O padrão é all.
`order_by` string · query	created_at_desc \| created_at_asc \| completed_at_desc \| completed_at_asc.

Resposta de sucesso

{
  "transcripts": [
    {
      "id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "input_url": "https://www.tiktok.com/@creator/video/1234567890",
      "tiktok_video_id": "1234567890",
      "status": "completed",
      "output_language": "en",
      "source_language": "en",
      "transcript_text": "Whenever I'm asked to teach a beginner...",
      "created_at": "2026-06-23T10:02:11.000Z",
      "completed_at": "2026-06-23T10:02:48.000Z",
      "folder": null
    }
  ],
  "page": 1,
  "limit": 15,
  "has_more": true,
  "total_count": 42,
  "total_pages": 3
}

Erros

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/transcripts/{id}

Obter uma transcrição

Limite de poll

Busque uma única transcrição pelo ID, com texto completo, segmentos, traduções, metadados e recursos.

Autenticação: Chave de API ou JWTReq: noneRes: application/json

curl -X GET "https://www.tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Parâmetros

idobrigatório

string · path

ID da transcrição.

Resposta de sucesso

{
  "id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "status": "completed",
  "input_url": "https://www.tiktok.com/@creator/video/1234567890",
  "output_language": "en",
  "source_language": "en",
  "selected_track_type": "creator",
  "transcript_text": "Whenever I'm asked to teach a beginner how to cook...",
  "segments": [
    {
      "start": 0,
      "end": 2.4,
      "text": "Whenever I'm asked to teach"
    }
  ],
  "translations": {
    "es": {
      "full_text": "Cada vez que me piden..."
    }
  },
  "metadata": {
    "author_username": "foodnetwork",
    "duration_seconds": 29
  },
  "completed_at": "2026-06-23T10:02:48.000Z"
}

Erros

AUTH_REQUIRED401NOT_FOUND404VALIDATION_ERROR400

GET/api/v1/transcripts/{id}/export

Exportar uma transcrição

Baixe uma transcrição como txt, srt, vtt, csv, json ou pdf. json e pdf exigem o plano Pro.

Autenticação: Chave de API ou JWTReq: noneRes: file download

curl -X GET "https://www.tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2/export?format=srt" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Retorna o arquivo com Content-Disposition: attachment. format=json retorna { id, text, segments, metadata }.
srt/vtt exigem segmentos com marcação de tempo — caso contrário, SEGMENTS_UNAVAILABLE.

Parâmetros

`id`obrigatório string · path	ID da transcrição.
`format` string · query	txt \| srt \| vtt \| csv \| json \| pdf. O padrão é txt.
`language` string · query	Exporte uma tradução em vez do idioma original.

Resposta de sucesso

{
  "note": "Binary/text download. Example shows the format=json body.",
  "id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "text": "Whenever I'm asked to teach a beginner how to cook...",
  "segments": [
    {
      "start": 0,
      "end": 2.4,
      "text": "Whenever I'm asked to teach"
    }
  ],
  "metadata": {
    "author_username": "foodnetwork"
  }
}

Erros

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400

POST/api/v1/transcripts/export-batch

Exportação em lote (ZIP)

Exporte várias transcrições de uma vez como ZIP, por lista de IDs ou por filtros. json/pdf exigem o Pro.

Autenticação: Chave de API ou JWTReq: application/jsonRes: application/zip

curl -X POST "https://www.tokcaption.com/api/v1/transcripts/export-batch" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format":"srt","filters":{"status":"completed","orderBy":"created_at_desc"}}'

Campos do corpo

`format` string	txt \| srt \| vtt \| csv \| json \| pdf. O padrão é txt.
`ids` string[]	IDs explícitos de transcrições. Omita para usar filtros.
`filters` object	{ search?, status?, folderId?, orderBy?, view? }. Somente transcrições concluídas são exportadas.

Resposta de sucesso

{
  "note": "Returns a ZIP attachment named tokcaption-srt-export-<date>.zip."
}

Erros

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400INTERNAL_ERROR500

DELETE/api/v1/transcripts/{id}

Excluir uma transcrição

Exclua permanentemente uma transcrição, seus arquivos armazenados e os links de pasta.

Autenticação: Chave de API ou JWTReq: noneRes: application/json

curl -X DELETE "https://www.tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Parâmetros

idobrigatório

string · path

ID da transcrição.

Resposta de sucesso

{
  "deleted": true
}

Erros

AUTH_REQUIRED401NOT_FOUND404INTERNAL_ERROR500

GET/api/v1/transcripts/stats

Estatísticas da transcrição

Limite de poll

Contagens agregadas da sua conta.

Autenticação: Chave de API ou JWTReq: noneRes: application/json

curl -X GET "https://www.tokcaption.com/api/v1/transcripts/stats" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Resposta de sucesso

{
  "total": 944,
  "completed": 702,
  "failed": 212,
  "folders": 5
}

Erros

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/transcripts/{id}/download/video

Baixar vídeo original

Pro

Baixe o vídeo original do TikTok em MP4. Apenas Pro, e conta na sua cota mensal de downloads.

Autenticação: Chave de API ou JWTReq: noneRes: video/mp4

curl -X GET "https://www.tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2/download/video" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Retorna video/mp4 como anexo. A cota só é consumida quando o streaming for concluído com sucesso.

Parâmetros

idobrigatório

string · path

ID da transcrição.

Resposta de sucesso

{
  "note": "Binary video/mp4 attachment."
}

Erros

AUTH_REQUIRED401PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404VALIDATION_ERROR400

Agentes de IA

Execute análise de ganchos, reescritas de roteiro e pontuação de viralização em uma transcrição. (Pro)

POST/api/v1/agents/{agentType}

Executar um agente de IA

ProLimite de agent

Enfileira uma análise de IA em uma transcrição concluída. agentType pode ser hooks, script_rewrite, virality_explain ou hook_score.

Autenticação: Chave de API ou JWTReq: application/jsonRes: application/json

curl -X POST "https://www.tokcaption.com/api/v1/agents/hooks" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transcript_id":"85f4dd35-3bc5-413f-81a6-63e0b61722d2","input":{}}'

Campos do corpo

`transcript_id`obrigatório string	Uma transcrição concluída para analisar.
`input` object	Parâmetros opcionais específicos do agente.

Parâmetros

agentTypeobrigatório

string · path

hooks | script_rewrite | virality_explain | hook_score.

Resposta de sucesso · HTTP 202

{
  "run_id": "a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "queued"
}

Erros

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404RATE_LIMIT_EXCEEDED429

GET/api/v1/agents/runs

Listar execuções de agentes

Liste suas execuções de agentes, da mais recente para a mais antiga, com paginação por cursor.

Autenticação: Chave de API ou JWTReq: noneRes: application/json

curl -X GET "https://www.tokcaption.com/api/v1/agents/runs?cursor=2026-06-23T10%3A00%3A00.000Z" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Parâmetros

`cursor` string (ISO date) · query	Passe next_cursor para voltar à página anterior.
`limit` integer · query	Tamanho da página, de 1 a 50. Padrão: 20.

Resposta de sucesso

{
  "runs": [
    {
      "id": "a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
      "status": "completed",
      "agent_type": "hooks",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "created_at": "2026-06-23T10:05:00.000Z"
    }
  ],
  "next_cursor": null
}

Erros

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/agents/runs/{runId}

Obter uma execução de agente

Busque uma execução de agente, incluindo sua saída estruturada após a conclusão.

Autenticação: Chave de API ou JWTReq: noneRes: application/json

curl -X GET "https://www.tokcaption.com/api/v1/agents/runs/a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Parâmetros

runIdobrigatório

string · path

ID da execução do agente.

Resposta de sucesso

{
  "id": "a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "completed",
  "agent_type": "hooks",
  "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "output": {
    "hooks": [
      "The first 3 seconds promise a payoff..."
    ]
  },
  "output_text": "The first 3 seconds promise a payoff...",
  "model": "claude-...",
  "completed_at": "2026-06-23T10:05:09.000Z"
}

Erros

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404

Extrair e traduzir

Primitivos de nível mais baixo: extrair metadados, traduzir texto e classificar a entrada colada.

POST/api/v1/extract/metadata

Extrair metadados

Resolve uma URL do TikTok para seus metadados e a melhor faixa de legendas disponível, sem criar um job.

Autenticação: Chave de API ou JWTReq: application/jsonRes: application/json

curl -X POST "https://www.tokcaption.com/api/v1/extract/metadata" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.tiktok.com/@creator/video/1234567890"}'

Campos do corpo

`url`obrigatório string	Uma URL de vídeo do TikTok.
`output_language` string	Idioma de legenda preferido. O padrão é en.

Resposta de sucesso

{
  "normalized_url": "https://www.tiktok.com/@creator/video/1234567890",
  "source_language": "en",
  "selected_track_type": "creator",
  "subtitle_format": "webvtt",
  "metadata": {
    "author_username": "creator",
    "duration_seconds": 29
  }
}

Erros

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/extract/translate

Traduzir texto

Traduza o texto da transcrição e/ou os segmentos com marcação de tempo para um ou mais idiomas.

Autenticação: Chave de API ou JWTReq: application/jsonRes: application/json

curl -X POST "https://www.tokcaption.com/api/v1/extract/translate" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"full_text":"Whenever I'm asked to teach a beginner how to cook...","output_language":"es"}'

Campos do corpo

`full_text` string	Texto a traduzir. Forneça este e/ou segments.
`segments` TranscriptSegment[]	Segmentos com marcação de tempo a serem traduzidos, preservando o tempo.
`output_language` string	Idioma de destino principal. O padrão é en.
`additional_languages` string[]	Idiomas de destino adicionais.

Resposta de sucesso

{
  "fullText": "Cada vez que me piden que enseñe a un principiante a cocinar...",
  "segments": [],
  "translations": {
    "es": {
      "full_text": "Cada vez que me piden..."
    }
  }
}

Erros

AUTH_REQUIRED401VALIDATION_ERROR400TRANSLATION_LIMIT_EXCEEDED429INTERNAL_ERROR500

POST/api/v1/workspace/resolve

Resolver entrada colada

Classifica texto colado / @perfis / URLs em URLs de vídeo, uma prévia de coleção ou uma prévia de perfil.

Autenticação: Chave de API ou JWTReq: application/jsonRes: application/json

curl -X POST "https://www.tokcaption.com/api/v1/workspace/resolve" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"@foodnetwork"}'

Campos do corpo

`text` string	Entrada bruta colada. Forneça esta ou urls.
`urls` string[]	Lista explícita de URLs.

Resposta de sucesso

{
  "kind": "profile",
  "profile": {
    "username": "foodnetwork",
    "video_count": 1200
  }
}

Erros

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

Pastas

Organize as transcrições em pastas.

GET/api/v1/folders

Listar pastas

Liste suas pastas com a contagem de itens.

Autenticação: Chave de API ou JWTReq: noneRes: application/json

curl -X GET "https://www.tokcaption.com/api/v1/folders" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Resposta de sucesso

{
  "folders": [
    {
      "id": "f1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
      "name": "Cooking hooks",
      "created_at": "2026-06-23T10:00:00.000Z",
      "item_count": 12
    }
  ]
}

Erros

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/folders

Criar uma pasta

Crie uma pasta para agrupar transcrições.

Autenticação: Chave de API ou JWTReq: application/jsonRes: application/json

curl -X POST "https://www.tokcaption.com/api/v1/folders" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Cooking hooks"}'

Campos do corpo

nameobrigatório

string

Nome da pasta.

Resposta de sucesso · HTTP 201

{
  "id": "f1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "name": "Cooking hooks",
  "created_at": "2026-06-23T10:00:00.000Z"
}

Erros

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

POST/api/v1/folders/{folderId}/items

Adicionar transcrição à pasta

Adiciona uma transcrição a uma pasta (idempotente).

Autenticação: Chave de API ou JWTReq: application/jsonRes: application/json

curl -X POST "https://www.tokcaption.com/api/v1/folders/f1f0ab70-7b6f-4f3b-9116-4135a6d8f53d/items" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transcript_id":"85f4dd35-3bc5-413f-81a6-63e0b61722d2"}'

Campos do corpo

transcript_idobrigatório

string

Transcrição a ser adicionada.

Parâmetros

folderIdobrigatório

string · path

ID da pasta de destino.

Resposta de sucesso · HTTP 201

{
  "added": true
}

Erros

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404INTERNAL_ERROR500

Conta, chaves e cobrança

Gerencie chaves de API, consulte planos e cota, e envie feedback.

POST/api/v1/api-keys

Criar uma chave de API

Pro

Gere uma chave de API ativa. A chave completa é exibida apenas uma vez — guarde-a com segurança. Somente Pro.

Autenticação: Chave de API ou JWTReq: application/jsonRes: application/json

curl -X POST "https://www.tokcaption.com/api/v1/api-keys" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production server"}'

Campos do corpo

nameobrigatório

string

Um rótulo para identificar a chave.

Resposta de sucesso · HTTP 201

{
  "id": "k1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "name": "Production server",
  "key_prefix": "tok_live_a1b2c3",
  "key": "tok_live_a1b2c3_d4e5f6g7h8i9j0k1l2m3n4o5",
  "created_at": "2026-06-23T10:00:00.000Z",
  "warning": "Save this key now — it will not be shown again."
}

Erros

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/api-keys

Listar chaves de API

Pro

Liste suas chaves ativas pelo prefixo (o segredo nunca é retornado). Somente Pro.

Autenticação: Chave de API ou JWTReq: noneRes: application/json

curl -X GET "https://www.tokcaption.com/api/v1/api-keys" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Resposta de sucesso

{
  "keys": [
    {
      "id": "k1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
      "name": "Production server",
      "key_prefix": "tok_live_a1b2c3",
      "last_used_at": "2026-06-23T10:30:00.000Z",
      "created_at": "2026-06-23T10:00:00.000Z",
      "revoked_at": null
    }
  ]
}

Erros

AUTH_REQUIRED401PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/plans

Listar planos

Lista pública dos planos ativos e seus limites. Não requer autenticação.

Autenticação: Público (sem autenticação)Req: noneRes: application/json

curl -X GET "https://www.tokcaption.com/api/v1/plans"

Resposta de sucesso

{
  "plans": [
    {
      "id": "free",
      "price_cents": 0,
      "billing_interval": "none",
      "free_daily_limit": 5,
      "agents_enabled": false,
      "downloads_enabled": false,
      "features": [
        "5 transcripts per day",
        "TXT & SRT export"
      ]
    },
    {
      "id": "pro_monthly",
      "price_cents": 900,
      "billing_interval": "month",
      "agents_enabled": true,
      "downloads_enabled": true,
      "features": [
        "Unlimited transcripts",
        "30 AI agent runs / month",
        "API access"
      ]
    }
  ]
}

Erros

INTERNAL_ERROR500

GET/api/v1/billing/subscription

Assinatura e cota

Seu plano atual, status da assinatura e uso/cota em tempo real de transcrições, agentes, downloads e traduções.

Autenticação: Chave de API ou JWTReq: noneRes: application/json

curl -X GET "https://www.tokcaption.com/api/v1/billing/subscription" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Resposta de sucesso

{
  "plan": {
    "id": "free",
    "price_cents": 0,
    "billing_interval": "none"
  },
  "subscription_status": null,
  "quota": {
    "transcripts": {
      "window": "daily",
      "limit": 5,
      "used": 2,
      "remaining": 3,
      "is_unlimited": false,
      "reset_at": "2026-06-24T00:00:00.000Z"
    },
    "agents": {
      "enabled": false,
      "limit": 0,
      "used": 0,
      "remaining": 0
    }
  }
}

Erros

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/feedback

Enviar feedback

Envie feedback sobre o produto, um relatório de bug ou uma sugestão de recurso.

Autenticação: Chave de API ou JWTReq: application/jsonRes: application/json

curl -X POST "https://www.tokcaption.com/api/v1/feedback" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"feature","rating":5,"message":"Add a Zapier integration please!"}'

Campos do corpo

`category`obrigatório string	bug \| feature \| improvement \| other.
`message`obrigatório string	Até 2000 caracteres.
`rating` integer \| null	Avaliação opcional de 1 a 5.

Resposta de sucesso

{
  "success": true
}

Erros

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

Loading API documentation…

POST/api/v1/jobs

Enviar job de transcrição

Limite de submit

Envie de 1 a N URLs públicas do TikTok para transcrição. O tamanho do lote é limitado pelo seu plano; uma única URL pode retornar um resultado pronto na própria resposta.

Autenticação: Chave de API ou JWTReq: application/jsonRes: application/json

curl -X POST "https://www.tokcaption.com/api/v1/jobs" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@creator/video/1234567890","https://www.tiktok.com/@creator/video/0987654321"],"output_language":"en","also_translate_to":["es"],"allow_asr_fallback":false,"include_download_assets":false,"idempotency_key":"client-req-001"}'

Uma única URL pode retornar HTTP 200 com um payload final de concluído ou com falha quando o processamento termina em linha.
Os lotes retornam HTTP 202 com job_id, um status agregado e status por item dentro de items.
Inspecione o array items para ver o status de cada vídeo: queued, processing, completed ou failed.
Definir include_download_assets: true no plano gratuito retorna PLAN_REQUIRED (403).

Campos do corpo

`urls`obrigatório string[]	URLs de vídeos do TikTok. O limite de lote do plano gratuito é 5.
`output_language` string	Idioma de destino da transcrição (código ISO). O padrão é en.
`also_translate_to` string[]	Idiomas adicionais para traduzir a transcrição.
`allow_asr_fallback` boolean	Transcreva o áudio quando não houver faixa de legendas. O padrão é false.
`include_download_assets` boolean	Mantenha os arquivos de vídeo/capa disponíveis para download. Somente Pro.
`idempotency_key` string	Chave de deduplicação; reutilizá-la retorna o job original.

Resposta de sucesso · HTTP 202

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "queued",
  "total_items": 2,
  "items": [
    {
      "id": "tx_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "input_url": "https://www.tiktok.com/@creator/video/1234567890",
      "status": "queued"
    }
  ]
}

Sucesso único imediato

HTTP 200

{
  "job_id": "51f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "completed",
  "total_items": 1,
  "completed": 1,
  "failed": 0,
  "items": [
    {
      "id": "tx_single_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "status": "completed",
      "output_language": "en",
      "source_language": "en",
      "selected_track_type": "creator",
      "transcript_text": "Whenever I'm asked to teach a beginner how to cook...",
      "metadata": {
        "author_username": "foodnetwork",
        "duration_seconds": 29
      },
      "completed_at": "2026-03-14T08:33:14.000Z"
    }
  ]
}

Falha única (sem legendas)

HTTP 200

{
  "job_id": "8a0d6d7a-78f0-4ab0-8a8c-72f8f5184de8",
  "status": "failed",
  "total_items": 1,
  "completed": 0,
  "failed": 1,
  "items": [
    {
      "id": "tx_single_2",
      "transcript_id": "d40b2545-7c62-4bbb-a7e3-020c663f18a0",
      "item_index": 0,
      "status": "failed",
      "error_code": "NO_CAPTIONS_AVAILABLE",
      "error_message": "Captions are not available for this TikTok video."
    }
  ]
}

Erros

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429DUPLICATE_REQUEST409UPSTREAM_TEMPORARY_ERROR503