Documentación para desarrolladores

Documentación de la API de TokCaption

Una API REST para transcribir videos públicos de TikTok, ejecutar análisis de ganchos con IA y reescrituras de guiones, y exportar transcripciones a gran escala. Autentícate con una clave de API, envía una URL y consulta el resultado. El acceso a la API está disponible en el plan Pro.

REST API · v2.1.0

TokCaption API

Transcribe videos públicos de TikTok, ejecuta análisis de ganchos con IA y exporta a gran escala, todo a través de una API REST JSON limpia. Autentícate con una clave de API y empieza en dos llamadas. ¿Prefieres asistentes de IA? Las mismas herramientas están disponibles como un servidor MCP para Claude y ChatGPT.

URL base

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

Autenticación

X-API-Key

Endpoints

27 en 6 grupos

Autenticación

Crea una clave de API desde Configuración → Claves de API (plan Pro). Envíala en cada solicitud mediante el encabezado X-API-Key. Los paneles y clientes móviles también pueden enviar un JWT de Supabase como Authorization: Bearer <jwt>. Mantén las claves en el servidor; nunca las incluyas en un bundle del navegador.

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

Inicio rápido

Envía una URL y luego consulta el trabajo hasta que termine. Una sola URL suele terminar en línea; revisa el estado de la respuesta antes de consultar.

Paso 1 — Enviar

POST /api/v1/jobs con tus URL. Guarda el job_id devuelto.

Paso 2 — Consultar

GET /api/v1/jobs/{jobId} cada 1–2 s hasta que el estado sea final y, después, lee items[].transcript_text.

¿Solo una URL y no quieres consultar el estado? Usa GET /api/v1/quick para obtener un resultado síncrono.

Errores y límites de uso

Todos los errores devuelven la misma estructura JSON. Decide según code, no según el código HTTP ni el mensaje. En 429, respeta el encabezado Retry-After.

Estructura de error

{
  "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 los códigos de error

Código	HTTP	Significado
AUTH_REQUIRED	401	Credenciales faltantes o no válidas. Envía un X-API-Key válido o un encabezado Authorization: Bearer <jwt>.
VALIDATION_ERROR	400	Cuerpo de la solicitud, parámetros de consulta o ruta no válidos. El mensaje y los detalles explican qué corregir.
PLAN_REQUIRED	403	Esta función u opción requiere un plan Pro. Actualiza para desbloquearla.
NOT_FOUND	404	Trabajo, transcripción o recurso no encontrado o que no te pertenece.
QUOTA_EXCEEDED	429	Se alcanzó el límite de transcripciones, agentes, descargas o traducciones. Se restablece diariamente (gratuito) o según el ciclo de facturación (Pro). Consulta details.reset_at.
RATE_LIMIT_EXCEEDED	429	Demasiadas solicitudes de envío, sondeo o agentes en poco tiempo. Respeta el encabezado Retry-After o details.retry_after_seconds.
DUPLICATE_REQUEST	409	Se reutilizó un idempotency_key. La solicitud original ya se ejecutó.
TRANSLATION_LIMIT_EXCEEDED	429	Se alcanzó la cuota mensual de traducción. Se restablece en tu ciclo de facturación.
UPSTREAM_TEMPORARY_ERROR	503	TikTok bloqueó temporalmente la solicitud o limitó la frecuencia. Vuelve a intentarlo con espera progresiva.
SEGMENTS_UNAVAILABLE	400	Este formato de exportación (srt/vtt) requiere segmentos con marcas de tiempo, pero la transcripción no tiene ninguno.
INTERNAL_ERROR	500	Error inesperado del servidor. Vuelve a intentarlo y contacta con soporte si persiste.

Transcripción

Envía URL públicas de TikTok para transcribirlas y haz seguimiento del progreso de los trabajos.

POST/api/v1/jobs

Enviar trabajo de transcripción

Límite de submit

Envía de 1 a N URL públicas de TikTok para transcribirlas. El tamaño del lote está limitado por tu plan; una sola URL puede devolver el resultado terminado en la misma respuesta.

Auth: Clave de API o JWTSolicitud: application/jsonRespuesta: 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"}'

Una única URL puede devolver HTTP 200 con una respuesta final de completado o fallido cuando el procesamiento termina en la misma solicitud.
Los lotes devuelven HTTP 202 con job_id, un estado agregado y estados por elemento dentro de items.
Revisa el array items para ver el estado de cada video: queued, processing, completed o failed.
Establecer include_download_assets: true en el plan gratuito devuelve PLAN_REQUIRED (403).

Campos del cuerpo

`urls`obligatorio string[]	URLs de videos de TikTok. El límite de lote del plan gratuito es 5.
`output_language` string	Idioma de la transcripción de destino (código ISO). Por defecto, en.
`also_translate_to` string[]	Idiomas adicionales a los que traducir la transcripción.
`allow_asr_fallback` boolean	Transcribe el audio cuando no existe una pista de subtítulos. Por defecto, false.
`include_download_assets` boolean	Guarda los recursos de video/portada para su descarga. Solo Pro.
`idempotency_key` string	Clave de deduplicación; si la reutilizas, se devuelve el trabajo original.

Respuesta exitosa · 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"
    }
  ]
}

Éxito único inmediato

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"
    }
  ]
}

Error único (sin subtítulos)

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."
    }
  ]
}

Errores

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429DUPLICATE_REQUEST409UPSTREAM_TEMPORARY_ERROR503

GET/api/v1/jobs

Listar trabajos

Lista tus trabajos de transcripción, de la más reciente a la más antigua, con paginación por cursor.

Auth: Clave de API o JWTSolicitud: noneRespuesta: 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	Pasa el next_cursor anterior para retroceder en el tiempo.
`limit` integer · query	Tamaño de página, de 1 a 50. Por defecto 20.
`status` string · query	Filtra por estado del trabajo (p. ej., completed, processing, failed).

Respuesta exitosa

{
  "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"
}

Errores

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/jobs/{jobId}

Consultar estado del trabajo

Límite de poll

Consulta un trabajo hasta que alcance un estado final. Devuelve los recuentos agregados y el detalle completo de cada elemento.

Auth: Clave de API o JWTSolicitud: noneRespuesta: application/json

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

Los estados finales de un trabajo son completed, partial o failed; los elementos individuales dentro de un trabajo pueden diferir.
Los elementos completados incluyen transcript_text, segments, translations, metadata y assets.
Consulta a un intervalo razonable (cada 1–2 s). Ante HTTP 429, respeta retry_after_seconds.

Parámetros

jobIdobligatorio

string · path

ID del trabajo devuelto por POST /api/v1/jobs.

Respuesta exitosa

{
  "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"
    }
  ]
}

Errores

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404RATE_LIMIT_EXCEEDED429INTERNAL_ERROR500

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

Cancelar un trabajo

Cancela los elementos en cola o en proceso de un trabajo. Los elementos liberados devuelven su cuota.

Auth: Clave de API o JWTSolicitud: noneRespuesta: 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

jobIdobligatorio

string · path

ID del trabajo que se va a cancelar.

Respuesta exitosa

{
  "cancelled_count": 3
}

Errores

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

GET/api/v1/quick

Transcripción rápida (una URL)

Límite de submit

Envía una sola URL y espera (hasta ~55 s) un resultado final: un atajo síncrono sobre los trabajos.

Auth: Clave de API o JWTSolicitud: noneRespuesta: 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"

Devuelve HTTP 200 cuando termina (completed/failed), o HTTP 202 si sigue procesándose al agotarse la ventana de espera; en ese caso, consulta /api/v1/jobs/{jobId}.

Parámetros

urlobligatorio

string · query

Una única URL de video de TikTok.

Respuesta exitosa

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

Errores

AUTH_REQUIRED401VALIDATION_ERROR400QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/import/collection

Importación masiva

ProLímite de submit

Envía una lista de URL o texto sin procesar que contenga enlaces. El plan gratuito acepta 1 URL; las importaciones masivas requieren Pro.

Auth: Clave de API o JWTSolicitud: application/jsonRespuesta: 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 del cuerpo

`urls` string[]	Lista explícita de URL. Proporciona esta lista o un texto.
`text` string	Texto libre; los enlaces de TikTok se extraen automáticamente.
`output_language` string	Idioma de la transcripción de destino. Por defecto, en.
`allow_asr_fallback` boolean	Transcribe el audio cuando no existen subtítulos. Por defecto, false.

Respuesta exitosa · 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"
  ]
}

Errores

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

Transcripciones

Lee, busca, exporta y descarga transcripciones terminadas y sus recursos.

GET/api/v1/history

Listar / buscar transcripciones

Límite de poll

Historial de transcripciones paginado y con búsqueda, con filtros de estado, carpeta y orden.

Auth: Clave de API o JWTSolicitud: noneRespuesta: 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 de página basado en 1. Por defecto, 1.
`limit` integer · query	Tamaño de página, de 1 a 100. Por defecto 15.
`search` string · query	Coincidencia de texto completo en el texto de la transcripción y la URL de origen.
`status` string · query	completed \| failed \| all. Por defecto, all.
`order_by` string · query	created_at_desc \| created_at_asc \| completed_at_desc \| completed_at_asc.

Respuesta exitosa

{
  "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
}

Errores

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/transcripts/{id}

Obtener una transcripción

Límite de poll

Obtén una sola transcripción por ID con texto completo, segmentos, traducciones, metadatos y recursos.

Auth: Clave de API o JWTSolicitud: noneRespuesta: 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

idobligatorio

string · path

ID de la transcripción.

Respuesta exitosa

{
  "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"
}

Errores

AUTH_REQUIRED401NOT_FOUND404VALIDATION_ERROR400

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

Exportar una transcripción

Descarga una transcripción en txt, srt, vtt, csv, json o pdf. json y pdf requieren Pro.

Auth: Clave de API o JWTSolicitud: noneRespuesta: 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"

Devuelve el archivo con Content-Disposition: attachment. format=json devuelve { id, text, segments, metadata }.
srt/vtt requieren segmentos con marcas de tiempo; de lo contrario, SEGMENTS_UNAVAILABLE.

Parámetros

`id`obligatorio string · path	ID de la transcripción.
`format` string · query	txt \| srt \| vtt \| csv \| json \| pdf. Por defecto, txt.
`language` string · query	Exporta una traducción en lugar del idioma de origen.

Respuesta exitosa

{
  "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"
  }
}

Errores

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400

POST/api/v1/transcripts/export-batch

Exportación por lotes (ZIP)

Exporta muchas transcripciones a la vez como ZIP, por lista de IDs o por filtros. json/pdf requieren Pro.

Auth: Clave de API o JWTSolicitud: application/jsonRespuesta: 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 del cuerpo

`format` string	txt \| srt \| vtt \| csv \| json \| pdf. Por defecto, txt.
`ids` string[]	IDs explícitos de transcripciones. Omítelo para usar filtros.
`filters` object	{ search?, status?, folderId?, orderBy?, view? }. Solo se exportan las transcripciones completadas.

Respuesta exitosa

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

Errores

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400INTERNAL_ERROR500

DELETE/api/v1/transcripts/{id}

Eliminar una transcripción

Elimina de forma permanente una transcripción, sus recursos almacenados y los enlaces de carpeta.

Auth: Clave de API o JWTSolicitud: noneRespuesta: 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

idobligatorio

string · path

ID de la transcripción.

Respuesta exitosa

{
  "deleted": true
}

Errores

AUTH_REQUIRED401NOT_FOUND404INTERNAL_ERROR500

GET/api/v1/transcripts/stats

Estadísticas de la transcripción

Límite de poll

Recuentos agregados de tu cuenta.

Auth: Clave de API o JWTSolicitud: noneRespuesta: application/json

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

Respuesta exitosa

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

Errores

AUTH_REQUIRED401INTERNAL_ERROR500

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

Descargar video original

Pro

Descarga el video original de TikTok en MP4. Solo Pro, y cuenta para tu cuota mensual de descargas.

Auth: Clave de API o JWTSolicitud: noneRespuesta: 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"

Devuelve video/mp4 como adjunto. La cuota solo se consume si la transmisión se completa correctamente.

Parámetros

idobligatorio

string · path

ID de la transcripción.

Respuesta exitosa

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

Errores

AUTH_REQUIRED401PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404VALIDATION_ERROR400

Agentes de IA

Ejecuta análisis de ganchos, reescrituras de guiones y evaluación de viralidad sobre una transcripción. (Pro)

POST/api/v1/agents/{agentType}

Ejecutar un agente de IA

ProLímite de agent

Pone en cola un análisis de IA sobre una transcripción completada. agentType puede ser hooks, script_rewrite, virality_explain o hook_score.

Auth: Clave de API o JWTSolicitud: application/jsonRespuesta: 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 del cuerpo

`transcript_id`obligatorio string	Una transcripción completada para analizar.
`input` object	Parámetros opcionales específicos del agente.

Parámetros

agentTypeobligatorio

string · path

hooks | script_rewrite | virality_explain | hook_score.

Respuesta exitosa · HTTP 202

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

Errores

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404RATE_LIMIT_EXCEEDED429

GET/api/v1/agents/runs

Listar ejecuciones del agente

Lista tus ejecuciones del agente, de la más reciente a la más antigua, con paginación por cursor.

Auth: Clave de API o JWTSolicitud: noneRespuesta: 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	Pasa next_cursor para volver a la página anterior.
`limit` integer · query	Tamaño de página, de 1 a 50. Por defecto 20.

Respuesta exitosa

{
  "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
}

Errores

AUTH_REQUIRED401INTERNAL_ERROR500

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

Obtener una ejecución del agente

Obtén una ejecución del agente, incluida su salida estructurada una vez completada.

Auth: Clave de API o JWTSolicitud: noneRespuesta: 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

runIdobligatorio

string · path

ID de ejecución del agente.

Respuesta exitosa

{
  "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"
}

Errores

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404

Extraer y traducir

Primitivas de bajo nivel: extraer metadatos, traducir texto y clasificar la entrada pegada.

POST/api/v1/extract/metadata

Extraer metadatos

Resuelve una URL de TikTok en sus metadatos y en la mejor pista de subtítulos disponible, sin crear un trabajo.

Auth: Clave de API o JWTSolicitud: application/jsonRespuesta: 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 del cuerpo

`url`obligatorio string	Una URL de video de TikTok.
`output_language` string	Idioma preferido de los subtítulos. Por defecto, en.

Respuesta exitosa

{
  "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
  }
}

Errores

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/extract/translate

Traducir texto

Traduce el texto de la transcripción y/o los segmentos con marcas de tiempo a uno o varios idiomas.

Auth: Clave de API o JWTSolicitud: application/jsonRespuesta: 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 del cuerpo

`full_text` string	Texto a traducir. Proporciona esto y/o segments.
`segments` TranscriptSegment[]	Segmentos con marcas de tiempo para traducir conservando los tiempos.
`output_language` string	Idioma principal de destino. Por defecto, en.
`additional_languages` string[]	Idiomas de destino adicionales.

Respuesta exitosa

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

Errores

AUTH_REQUIRED401VALIDATION_ERROR400TRANSLATION_LIMIT_EXCEEDED429INTERNAL_ERROR500

POST/api/v1/workspace/resolve

Resolver la entrada pegada

Clasifica el texto pegado, los @handles o las URL en URL de video, una vista previa de colección o una vista previa de perfil.

Auth: Clave de API o JWTSolicitud: application/jsonRespuesta: 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 del cuerpo

`text` string	Entrada pegada sin procesar. Proporciona esto o urls.
`urls` string[]	Lista explícita de URL.

Respuesta exitosa

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

Errores

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

Carpetas

Organiza las transcripciones en carpetas.

GET/api/v1/folders

Listar carpetas

Lista tus carpetas con el recuento de elementos.

Auth: Clave de API o JWTSolicitud: noneRespuesta: application/json

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

Respuesta exitosa

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

Errores

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/folders

Crear una carpeta

Crea una carpeta para agrupar transcripciones.

Auth: Clave de API o JWTSolicitud: application/jsonRespuesta: 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 del cuerpo

nameobligatorio

string

Nombre de la carpeta.

Respuesta exitosa · HTTP 201

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

Errores

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

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

Añadir transcripción a carpeta

Añade una transcripción a una carpeta (idempotente).

Auth: Clave de API o JWTSolicitud: application/jsonRespuesta: 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 del cuerpo

transcript_idobligatorio

string

Transcripción que se va a añadir.

Parámetros

folderIdobligatorio

string · path

ID de la carpeta de destino.

Respuesta exitosa · HTTP 201

{
  "added": true
}

Errores

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404INTERNAL_ERROR500

Cuenta, claves y facturación

Gestiona las claves de API, consulta los planes y la cuota, y envía comentarios.

POST/api/v1/api-keys

Crear una clave de API

Pro

Genera una clave de API activa. La clave completa se muestra una sola vez; guárdala de forma segura. Solo Pro.

Auth: Clave de API o JWTSolicitud: application/jsonRespuesta: 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 del cuerpo

nameobligatorio

string

Una etiqueta para identificar la clave.

Respuesta exitosa · 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."
}

Errores

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/api-keys

Listar claves de API

Pro

Lista tus claves activas por prefijo (el secreto nunca se devuelve). Solo Pro.

Auth: Clave de API o JWTSolicitud: noneRespuesta: application/json

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

Respuesta exitosa

{
  "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
    }
  ]
}

Errores

AUTH_REQUIRED401PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/plans

Listar planes

Lista pública de los planes activos y sus límites. No requiere autenticación.

Auth: Público (sin autenticación)Solicitud: noneRespuesta: application/json

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

Respuesta exitosa

{
  "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"
      ]
    }
  ]
}

Errores

INTERNAL_ERROR500

GET/api/v1/billing/subscription

Suscripción y cuota

Tu plan actual, estado de la suscripción y uso/cuota en tiempo real de transcripciones, agentes, descargas y traducciones.

Auth: Clave de API o JWTSolicitud: noneRespuesta: application/json

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

Respuesta exitosa

{
  "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
    }
  }
}

Errores

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/feedback

Enviar comentarios

Envía comentarios sobre el producto, un informe de error o una solicitud de función.

Auth: Clave de API o JWTSolicitud: application/jsonRespuesta: 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 del cuerpo

`category`obligatorio string	bug \| feature \| improvement \| other.
`message`obligatorio string	Hasta 2000 caracteres.
`rating` integer \| null	Calificación opcional de 1 a 5.

Respuesta exitosa

{
  "success": true
}

Errores

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

Loading API documentation…

POST/api/v1/jobs

Enviar trabajo de transcripción

Límite de submit

Envía de 1 a N URL públicas de TikTok para transcribirlas. El tamaño del lote está limitado por tu plan; una sola URL puede devolver el resultado terminado en la misma respuesta.

Auth: Clave de API o JWTSolicitud: application/jsonRespuesta: 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"}'

Una única URL puede devolver HTTP 200 con una respuesta final de completado o fallido cuando el procesamiento termina en la misma solicitud.
Los lotes devuelven HTTP 202 con job_id, un estado agregado y estados por elemento dentro de items.
Revisa el array items para ver el estado de cada video: queued, processing, completed o failed.
Establecer include_download_assets: true en el plan gratuito devuelve PLAN_REQUIRED (403).

Campos del cuerpo

`urls`obligatorio string[]	URLs de videos de TikTok. El límite de lote del plan gratuito es 5.
`output_language` string	Idioma de la transcripción de destino (código ISO). Por defecto, en.
`also_translate_to` string[]	Idiomas adicionales a los que traducir la transcripción.
`allow_asr_fallback` boolean	Transcribe el audio cuando no existe una pista de subtítulos. Por defecto, false.
`include_download_assets` boolean	Guarda los recursos de video/portada para su descarga. Solo Pro.
`idempotency_key` string	Clave de deduplicación; si la reutilizas, se devuelve el trabajo original.

Respuesta exitosa · 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"
    }
  ]
}

Éxito único inmediato

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"
    }
  ]
}

Error único (sin subtítulos)

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."
    }
  ]
}

Errores

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429DUPLICATE_REQUEST409UPSTREAM_TEMPORARY_ERROR503