Documentation développeur

Documentation de l'API TokCaption

Une API REST pour transcrire des vidéos TikTok publiques, lancer l'analyse d'accroches par IA et la réécriture de scripts, et exporter les transcriptions à grande échelle. Authentifiez-vous avec une clé API, soumettez une URL et interrogez le résultat. L'accès à l'API est disponible avec l'offre Pro.

REST API · v2.1.0

TokCaption API

Transcrivez des vidéos TikTok publiques, lancez l'analyse d'accroches par IA et exportez à grande échelle — le tout via une API REST JSON claire. Authentifiez-vous avec une clé API et démarrez en deux appels. Vous préférez les assistants IA ? Les mêmes outils sont disponibles sous forme de serveur MCP pour Claude et ChatGPT.

URL de base

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

Authentification

X-API-Key

Points de terminaison

27 sur 6 groupes

Authentification

Créez une clé API depuis Paramètres → Clés API (offre Pro). Envoyez-la à chaque requête via l'en-tête X-API-Key. Les tableaux de bord et clients mobiles peuvent aussi envoyer un JWT Supabase sous la forme Authorization: Bearer <jwt>. Gardez les clés côté serveur, ne les intégrez jamais dans un bundle navigateur.

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

Démarrage rapide

Soumettez une URL, puis interrogez la tâche jusqu'à ce qu'elle soit terminée. Une URL unique se termine souvent directement — vérifiez le statut de la réponse avant d'interroger.

Étape 1 — Soumettre

Appelez POST /api/v1/jobs avec vos URL. Stockez le job_id renvoyé.

Étape 2 — Interroger

Appelez GET /api/v1/jobs/{jobId} toutes les 1 à 2 secondes jusqu'à ce que le statut soit final, puis lisez items[].transcript_text.

Une seule URL et vous ne voulez pas interroger le statut ? Utilisez GET /api/v1/quick pour obtenir un résultat synchrone.

Erreurs et limites de débit

Chaque erreur renvoie la même enveloppe JSON. Basez votre logique sur code, et non sur le code HTTP ou le message. Pour 429, respectez l'en-tête Retry-After.

Enveloppe d'erreur

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

Tous les codes d'erreur

Code	HTTP	Signification
AUTH_REQUIRED	401	Identifiants manquants ou invalides. Envoyez un en-tête X-API-Key valide, ou un en-tête Authorization: Bearer <jwt>.
VALIDATION_ERROR	400	Corps de requête, paramètres de requête ou chemin invalide. Le message et les détails indiquent quoi corriger.
PLAN_REQUIRED	403	Cette fonctionnalité ou option nécessite une offre Pro. Passez à la version supérieure pour la débloquer.
NOT_FOUND	404	Tâche, transcription ou ressource introuvable ou ne vous appartenant pas.
QUOTA_EXCEEDED	429	Quota de transcriptions, d'agents, de téléchargements ou de traductions atteint. Réinitialisé chaque jour (offre gratuite) ou à chaque cycle de facturation (Pro). Voir details.reset_at.
RATE_LIMIT_EXCEEDED	429	Trop de requêtes d'envoi, d'interrogation ou d'agent en peu de temps. Respectez l'en-tête Retry-After / details.retry_after_seconds.
DUPLICATE_REQUEST	409	Une idempotency_key a été réutilisée. La requête d'origine a déjà été exécutée.
TRANSLATION_LIMIT_EXCEEDED	429	Quota mensuel de traduction atteint. Il se réinitialise à chaque cycle de facturation.
UPSTREAM_TEMPORARY_ERROR	503	TikTok a temporairement bloqué la requête ou limité le débit. Réessayez avec un délai progressif.
SEGMENTS_UNAVAILABLE	400	Des segments horodatés sont requis pour ce format d'export (srt/vtt), mais la transcription n'en contient pas.
INTERNAL_ERROR	500	Erreur serveur inattendue. Réessayez et contactez le support si le problème persiste.

Transcription

Soumettez des URL TikTok publiques pour transcription et suivez la progression des tâches.

POST/api/v1/jobs

Soumettre une tâche de transcription

Limite submit

Soumettez de 1 à N URL TikTok publiques pour transcription. La taille des lots est limitée par votre offre ; une seule URL peut renvoyer un résultat terminé directement dans la réponse.

Authentification : Clé API ou JWTReq : application/jsonRép : 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"}'

Une seule URL peut renvoyer HTTP 200 avec une charge utile finale completed ou failed lorsque le traitement se termine en ligne.
Les lots renvoient HTTP 202 avec un job_id, un statut global et les statuts de chaque élément dans items.
Consultez le tableau items pour le statut de chaque vidéo : queued, processing, completed ou failed.
Définir include_download_assets: true sur l'offre gratuite renvoie PLAN_REQUIRED (403).

Champs du corps

`urls`requis string[]	URL de vidéos TikTok. La limite par lot de l'offre gratuite est de 5.
`output_language` string	Langue cible de la transcription (code ISO). Par défaut : en.
`also_translate_to` string[]	Langues supplémentaires dans lesquelles traduire la transcription.
`allow_asr_fallback` boolean	Transcrire l'audio lorsqu'aucune piste de sous-titres n'existe. Valeur par défaut : false.
`include_download_assets` boolean	Conservez les fichiers vidéo/miniature pour le téléchargement. Pro uniquement.
`idempotency_key` string	Clé de déduplication ; la réutiliser renvoie la tâche d'origine.

Réponse en cas de succès · 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"
    }
  ]
}

Succès immédiat et unique

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

Échec unique (pas de sous-titres)

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

Erreurs

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429DUPLICATE_REQUEST409UPSTREAM_TEMPORARY_ERROR503

GET/api/v1/jobs

Lister les tâches

Listez vos tâches de transcription, les plus récentes d'abord, avec pagination par curseur.

Authentification : Clé API ou JWTReq : noneRép : 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"

Paramètres

`cursor` string (ISO date) · query	Transmettez le next_cursor précédent pour revenir en arrière dans le temps.
`limit` integer · query	Taille de page, de 1 à 50. Valeur par défaut : 20.
`status` string · query	Filtrer par statut de tâche (ex. completed, processing, failed).

Réponse en cas de succès

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

Erreurs

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/jobs/{jobId}

Interroger le statut de la tâche

Limite poll

Interrogez une tâche jusqu'à ce qu'elle atteigne un état final. Renvoie les totaux agrégés ainsi que le détail complet de chaque élément.

Authentification : Clé API ou JWTReq : noneRép : application/json

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

Les états finaux d'une tâche sont completed, partial ou failed ; les éléments individuels d'une tâche peuvent différer.
Les éléments terminés incluent transcript_text, segments, translations, metadata et assets.
Interrogez à intervalle raisonnable (toutes les 1 à 2 s). En cas de HTTP 429, respectez retry_after_seconds.

Paramètres

jobIdrequis

string · path

ID de tâche renvoyé par POST /api/v1/jobs.

Réponse en cas de succès

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

Erreurs

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404RATE_LIMIT_EXCEEDED429INTERNAL_ERROR500

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

Annuler une tâche

Annule les éléments en file d'attente ou en cours de traitement dans une tâche. Les éléments annulés restituent leur quota.

Authentification : Clé API ou JWTReq : noneRép : 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"

Paramètres

jobIdrequis

string · path

ID de la tâche à annuler.

Réponse en cas de succès

{
  "cancelled_count": 3
}

Erreurs

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

GET/api/v1/quick

Transcription rapide (une URL)

Limite submit

Soumettez une URL unique et attendez (jusqu'à environ 55 s) un résultat final — un raccourci synchrone des tâches.

Authentification : Clé API ou JWTReq : noneRép : 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"

Renvoie HTTP 200 une fois l'état final atteint (terminé/échoué), ou HTTP 202 si le traitement est toujours en cours à l'expiration de la fenêtre d'attente — interrogez ensuite /api/v1/jobs/{jobId}.

Paramètres

urlrequis

string · query

Une seule URL de vidéo TikTok.

Réponse en cas de succès

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

Erreurs

AUTH_REQUIRED401VALIDATION_ERROR400QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/import/collection

Import en masse

ProLimite submit

Soumettez une liste d'URL ou un texte brut contenant des liens. L'offre gratuite accepte 1 URL ; l'import en masse nécessite Pro.

Authentification : Clé API ou JWTReq : application/jsonRép : 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"}'

Champs du corps

`urls` string[]	Liste d'URL explicite. Fournissez-la ou du texte.
`text` string	Texte libre ; les liens TikTok sont extraits automatiquement.
`output_language` string	Langue cible de la transcription. Par défaut : en.
`allow_asr_fallback` boolean	Transcrire l'audio lorsqu'aucun sous-titre n'existe. Valeur par défaut : false.

Réponse en cas de succès · 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"
  ]
}

Erreurs

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

Transcriptions

Lisez, recherchez, exportez et téléchargez les transcriptions terminées ainsi que leurs fichiers.

GET/api/v1/history

Lister / rechercher des transcriptions

Limite poll

Historique des transcriptions paginé, avec recherche et filtres par statut, dossier et ordre de tri.

Authentification : Clé API ou JWTReq : noneRép : application/json

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

Paramètres

`page` integer · query	Numéro de page à partir de 1. Valeur par défaut : 1.
`limit` integer · query	Taille de page, de 1 à 100. Valeur par défaut : 15.
`search` string · query	Recherche plein texte sur le texte de la transcription et l'URL source.
`status` string · query	completed \| failed \| all. Valeur par défaut : all.
`order_by` string · query	created_at_desc \| created_at_asc \| completed_at_desc \| completed_at_asc.

Réponse en cas de succès

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

Erreurs

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/transcripts/{id}

Obtenir une transcription

Limite poll

Récupérez une seule transcription par ID avec le texte intégral, les segments, les traductions, les métadonnées et les ressources.

Authentification : Clé API ou JWTReq : noneRép : application/json

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

Paramètres

idrequis

string · path

ID de la transcription.

Réponse en cas de succès

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

Erreurs

AUTH_REQUIRED401NOT_FOUND404VALIDATION_ERROR400

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

Exporter une transcription

Téléchargez une transcription au format txt, srt, vtt, csv, json ou pdf. Les formats json et pdf nécessitent l'offre Pro.

Authentification : Clé API ou JWTReq : noneRép : 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"

Renvoie le fichier avec Content-Disposition: attachment. format=json renvoie { id, text, segments, metadata }.
srt/vtt nécessitent des segments horodatés — sinon SEGMENTS_UNAVAILABLE.

Paramètres

`id`requis string · path	ID de la transcription.
`format` string · query	txt \| srt \| vtt \| csv \| json \| pdf. Valeur par défaut : txt.
`language` string · query	Exporter une traduction au lieu de la langue source.

Réponse en cas de succès

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

Erreurs

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400

POST/api/v1/transcripts/export-batch

Export par lot (ZIP)

Exportez plusieurs transcriptions d'un coup au format ZIP, par liste d'IDs ou par filtres. json/pdf nécessitent Pro.

Authentification : Clé API ou JWTReq : application/jsonRép : 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"}}'

Champs du corps

`format` string	txt \| srt \| vtt \| csv \| json \| pdf. Valeur par défaut : txt.
`ids` string[]	IDs de transcription explicites. Omettez pour utiliser les filtres.
`filters` object	{ search?, status?, folderId?, orderBy?, view? }. Seules les transcriptions terminées sont exportées.

Réponse en cas de succès

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

Erreurs

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400INTERNAL_ERROR500

DELETE/api/v1/transcripts/{id}

Supprimer une transcription

Supprimez définitivement une transcription, ses fichiers stockés et ses liens de dossier.

Authentification : Clé API ou JWTReq : noneRép : application/json

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

Paramètres

idrequis

string · path

ID de la transcription.

Réponse en cas de succès

{
  "deleted": true
}

Erreurs

AUTH_REQUIRED401NOT_FOUND404INTERNAL_ERROR500

GET/api/v1/transcripts/stats

Statistiques de la transcription

Limite poll

Totaux agrégés pour votre compte.

Authentification : Clé API ou JWTReq : noneRép : application/json

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

Réponse en cas de succès

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

Erreurs

AUTH_REQUIRED401INTERNAL_ERROR500

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

Télécharger la vidéo source

Pro

Téléchargez la vidéo TikTok originale au format MP4. Réservé à l'offre Pro et décompté de votre quota mensuel de téléchargements.

Authentification : Clé API ou JWTReq : noneRép : 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"

Renvoie video/mp4 en pièce jointe. Le quota n'est consommé qu'en cas de flux réussi.

Paramètres

idrequis

string · path

ID de la transcription.

Réponse en cas de succès

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

Erreurs

AUTH_REQUIRED401PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404VALIDATION_ERROR400

Agents IA

Lancez une analyse d'accroches, des réécritures de scripts et un scoring de viralité sur une transcription. (Pro)

POST/api/v1/agents/{agentType}

Lancer un agent IA

ProLimite agent

Mettez en file d'attente une analyse IA sur une transcription terminée. agentType correspond à hooks, script_rewrite, virality_explain ou hook_score.

Authentification : Clé API ou JWTReq : application/jsonRép : 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":{}}'

Champs du corps

`transcript_id`requis string	Une transcription terminée à analyser.
`input` object	Paramètres facultatifs propres à l'agent.

Paramètres

agentTyperequis

string · path

hooks | script_rewrite | virality_explain | hook_score.

Réponse en cas de succès · HTTP 202

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

Erreurs

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404RATE_LIMIT_EXCEEDED429

GET/api/v1/agents/runs

Lister les exécutions d'agents

Listez vos exécutions d'agents, les plus récentes d'abord, avec pagination par curseur.

Authentification : Clé API ou JWTReq : noneRép : 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"

Paramètres

`cursor` string (ISO date) · query	Transmettez next_cursor pour revenir à la page précédente.
`limit` integer · query	Taille de page, de 1 à 50. Valeur par défaut : 20.

Réponse en cas de succès

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

Erreurs

AUTH_REQUIRED401INTERNAL_ERROR500

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

Obtenir une exécution d'agent

Récupérez une exécution d'agent, y compris sa sortie structurée une fois terminée.

Authentification : Clé API ou JWTReq : noneRép : 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"

Paramètres

runIdrequis

string · path

ID de l'exécution de l'agent.

Réponse en cas de succès

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

Erreurs

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404

Extraire et traduire

Primitives de bas niveau : récupérer les métadonnées, traduire du texte et classer les entrées collées.

POST/api/v1/extract/metadata

Extraire les métadonnées

Résolvez une URL TikTok pour obtenir ses métadonnées et la meilleure piste de sous-titres disponible, sans créer de tâche.

Authentification : Clé API ou JWTReq : application/jsonRép : 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"}'

Champs du corps

`url`requis string	Une URL de vidéo TikTok.
`output_language` string	Langue de sous-titres préférée. Par défaut : en.

Réponse en cas de succès

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

Erreurs

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/extract/translate

Traduire le texte

Traduisez le texte de la transcription et/ou les segments horodatés dans une ou plusieurs langues.

Authentification : Clé API ou JWTReq : application/jsonRép : 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"}'

Champs du corps

`full_text` string	Texte à traduire. Fournissez-le et/ou segments.
`segments` TranscriptSegment[]	Segments horodatés à traduire en conservant la synchronisation.
`output_language` string	Langue cible principale. Par défaut : en.
`additional_languages` string[]	Langues cibles supplémentaires.

Réponse en cas de succès

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

Erreurs

AUTH_REQUIRED401VALIDATION_ERROR400TRANSLATION_LIMIT_EXCEEDED429INTERNAL_ERROR500

POST/api/v1/workspace/resolve

Résoudre la saisie collée

Classe le texte collé, les @pseudos ou les URL en URL de vidéos, aperçu de collection ou aperçu de profil.

Authentification : Clé API ou JWTReq : application/jsonRép : 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"}'

Champs du corps

`text` string	Saisie brute collée. Fournissez-la ou urls.
`urls` string[]	Liste d'URL explicite.

Réponse en cas de succès

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

Erreurs

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

Dossiers

Organisez vos transcriptions en dossiers.

GET/api/v1/folders

Lister les dossiers

Listez vos dossiers avec le nombre d'éléments.

Authentification : Clé API ou JWTReq : noneRép : application/json

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

Réponse en cas de succès

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

Erreurs

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/folders

Créer un dossier

Créez un dossier pour regrouper vos transcriptions.

Authentification : Clé API ou JWTReq : application/jsonRép : 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"}'

Champs du corps

namerequis

string

Nom du dossier.

Réponse en cas de succès · HTTP 201

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

Erreurs

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

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

Ajouter la transcription au dossier

Ajouter une transcription à un dossier (idempotent).

Authentification : Clé API ou JWTReq : application/jsonRép : 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"}'

Champs du corps

transcript_idrequis

string

Transcription à ajouter.

Paramètres

folderIdrequis

string · path

ID du dossier cible.

Réponse en cas de succès · HTTP 201

{
  "added": true
}

Erreurs

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404INTERNAL_ERROR500

Compte, clés et facturation

Gérez les clés API, consultez les offres et le quota, et envoyez vos commentaires.

POST/api/v1/api-keys

Créer une clé API

Pro

Générez une clé API active. La clé complète n'est affichée qu'une fois : conservez-la en lieu sûr. Pro uniquement.

Authentification : Clé API ou JWTReq : application/jsonRép : 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"}'

Champs du corps

namerequis

string

Un libellé pour identifier la clé.

Réponse en cas de succès · 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."
}

Erreurs

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/api-keys

Lister les clés API

Pro

Listez vos clés actives par préfixe (le secret n'est jamais renvoyé). Pro uniquement.

Authentification : Clé API ou JWTReq : noneRép : application/json

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

Réponse en cas de succès

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

Erreurs

AUTH_REQUIRED401PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/plans

Lister les offres

Liste publique des offres actives et de leurs limites. Aucune authentification requise.

Authentification : Public (sans authentification)Req : noneRép : application/json

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

Réponse en cas de succès

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

Erreurs

INTERNAL_ERROR500

GET/api/v1/billing/subscription

Abonnement et quota

Votre offre actuelle, le statut de votre abonnement et votre utilisation et quota en temps réel pour les transcriptions, agents, téléchargements et traductions.

Authentification : Clé API ou JWTReq : noneRép : application/json

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

Réponse en cas de succès

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

Erreurs

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/feedback

Envoyer les retours

Envoyez vos retours sur le produit, un rapport de bug ou une demande de fonctionnalité.

Authentification : Clé API ou JWTReq : application/jsonRép : 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!"}'

Champs du corps

`category`requis string	bug \| feature \| improvement \| other.
`message`requis string	Jusqu'à 2000 caractères.
`rating` integer \| null	Note facultative de 1 à 5.

Réponse en cas de succès

{
  "success": true
}

Erreurs

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

Loading API documentation…

POST/api/v1/jobs

Soumettre une tâche de transcription

Limite submit

Soumettez de 1 à N URL TikTok publiques pour transcription. La taille des lots est limitée par votre offre ; une seule URL peut renvoyer un résultat terminé directement dans la réponse.

Authentification : Clé API ou JWTReq : application/jsonRép : 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"}'

Une seule URL peut renvoyer HTTP 200 avec une charge utile finale completed ou failed lorsque le traitement se termine en ligne.
Les lots renvoient HTTP 202 avec un job_id, un statut global et les statuts de chaque élément dans items.
Consultez le tableau items pour le statut de chaque vidéo : queued, processing, completed ou failed.
Définir include_download_assets: true sur l'offre gratuite renvoie PLAN_REQUIRED (403).

Champs du corps

`urls`requis string[]	URL de vidéos TikTok. La limite par lot de l'offre gratuite est de 5.
`output_language` string	Langue cible de la transcription (code ISO). Par défaut : en.
`also_translate_to` string[]	Langues supplémentaires dans lesquelles traduire la transcription.
`allow_asr_fallback` boolean	Transcrire l'audio lorsqu'aucune piste de sous-titres n'existe. Valeur par défaut : false.
`include_download_assets` boolean	Conservez les fichiers vidéo/miniature pour le téléchargement. Pro uniquement.
`idempotency_key` string	Clé de déduplication ; la réutiliser renvoie la tâche d'origine.

Réponse en cas de succès · 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"
    }
  ]
}

Succès immédiat et unique

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

Échec unique (pas de sous-titres)

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

Erreurs

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429DUPLICATE_REQUEST409UPSTREAM_TEMPORARY_ERROR503