Référence de l'API

Fonctionnement#

Chaque transcription est une tâche. Vous soumettez une source, la tâche s'exécute en arrière-plan et, lorsqu'elle réussit, elle renvoie vers une transcription que vous pouvez lire ou exporter autant de fois que vous le voulez. URL de base : https://www.transcriptdock.com. Toutes les requêtes et réponses sont au format JSON.

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

Authentification#

Créez vos clés sur la page Clés API. Une clé n'est affichée qu'une seule fois, ressemble à td_live_... et va dans l'en-tête Authorization de chaque requête. Les clés ont des autorisations (scopes) choisies à la création : jobs:read, jobs:write, transcripts:read, uploads:write. Créez une clé par intégration afin de pouvoir la révoquer seule.

Authorization: Bearer td_live_YOUR_KEY

Idempotency-Key#

Obligatoire sur POST /v1/jobs, /v1/batches, /v1/jobs/{id}/retry, /v1/video-discoveries et /v1/language-discoveries : toute chaîne de 8 à 128 caractères ASCII imprimables. Envoyer la même clé avec le même corps dans les 48 heures renvoie l'objet d'origine. Une requête relancée ne crée ni ne facture donc jamais deux fois. La même clé avec un corps différent renvoie 409 IDEMPOTENCY_CONFLICT. Une bonne clé est votre propre identifiant de ce que vous transcrivez.

X-Request-Id#

Chaque réponse en contient un. Citez-le lorsque vous contactez l'assistance.

Endpoints#

Créer une tâche#

source.urlstringFacultatif

Une vidéo publique : YouTube (watch?v=, youtu.be, shorts, live) ou TikTok (tiktok.com/@user/video/…, liens de partage vm.tiktok.com). Tout autre lien https vers un fichier audio ou vidéo est traité comme un lien média direct (transcription par IA). L'un des deux, url ou upload_id, est requis.

source.upload_iduuidFacultatif

Un fichier que vous avez envoyé (voir Envoi de fichiers). Toujours traité par transcription par IA.

mode"captions_only" | "auto" | "transcribe"Requis

captions_only : les sous-titres propres à la vidéo, 1 crédit ; échoue avec NO_CAPTIONS s'il n'y en a pas. auto : les sous-titres lorsqu'ils existent (1 crédit), sinon transcription par IA. transcribe : toujours une transcription par IA de l'audio, 2 crédits par minute commencée, avec horodatages par mot. La transcription par IA nécessite un forfait payant.

caption_languagesstring[]Facultatif

Langues de sous-titres préférées, dans l'ordre, par exemple ["en", "es"], jusqu'à 5. Par défaut : la piste par défaut de la vidéo. captions_only et auto uniquement.

caption_preference"prefer_creator" | "creator_only" | "automatic_only"Facultatif

Indique s'il faut accepter les sous-titres ajoutés par le créateur, les sous-titres automatiques de YouTube, ou les deux (par défaut prefer_creator : ceux du créateur d'abord).

languagestringFacultatif

Indication de la langue parlée pour la transcription par IA (BCP 47). Par défaut : détection automatique.

max_creditsintegerFacultatif

Plafond de dépense pour la transcription par IA. Le média est mesuré d'abord. S'il coûterait plus, la tâche échoue avec BUDGET_EXCEEDED et rien n'est débité. Par défaut : de quoi couvrir 2 heures.

webhook_endpoint_iduuidFacultatif

Reçoit job.succeeded ou job.failed sur ce webhook.

metadataobjectFacultatif

Jusqu'à 10 valeurs texte (clés ≤ 64, valeurs ≤ 256 caractères). Renvoyées dans les événements webhook. Sans effet sur la mise en cache.

Renvoie 202 avec la tâche. Si votre espace de travail possède déjà une transcription de la même vidéo avec les mêmes options, renvoie 200 avec une tâche réussie, gratuitement (billing.kind: "cached").

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

L'objet tâche#

iduuidFacultatif

Identifiant de la tâche.

statusstringFacultatif

queued → processing (→ awaiting_provider pendant la transcription par IA) → succeeded, failed ou cancelled. Les trois derniers états sont définitifs.

stagestring | nullFacultatif

Étape en cours d'une tâche : resolve, captions, acquire_audio, submit_asr, wait_asr, finalize. À titre informatif.

result_iduuid | nullFacultatif

La transcription, une fois la tâche réussie.

errorobject | nullFacultatif

En cas d'échec : code, message, retryable et, en option, details.detail. Mêmes codes que dans Erreurs.

billingobjectFacultatif

credits_reserved (bloqués pendant l'exécution, 0 une fois terminé), credits_charged (définitif), kind : captions, ai_transcription ou cached.

sourceobjectFacultatif

platform, media_id, canonical_url, title, upload_id.

optionsobjectFacultatif

mode, language, caption_preference tels qu'acceptés.

created_atdate-timeFacultatif

UTC.

Récupérer une tâche#

Renvoie la tâche. Avec wait (0 à 25 secondes), la requête reste ouverte et répond dès que la tâche est définitive. Un seul appel remplace ainsi une boucle d'interrogation. Les lectures ont leur propre limite, 120 par minute.

Lister les tâches#

Les plus récentes d'abord, limit de 1 à 100. Passez le next_cursor de la réponse comme cursor pour obtenir la page suivante. Ajoutez platform et source_id (le source.media_id d'une tâche) ensemble pour ne voir que les tâches d'une seule vidéo, quel que soit le mode. C'est ainsi qu'un client vérifie qu'une transcription existe déjà dans l'espace de travail avant de soumettre à nouveau.

Annuler une tâche#

Annule une tâche qui n'a pas encore commencé la transcription par IA, et libère le blocage. Au-delà, l'API renvoie 409 CANCELLATION_NOT_ALLOWED et la tâche se termine.

Relancer une tâche#

Crée une nouvelle tâche à partir d'une tâche échouée dont l'erreur était retryable. Il faut une nouvelle Idempotency-Key ; corps facultatif { "max_credits": 40 }. Tarifée comme une nouvelle tâche. Les échecs définitifs (vidéo privée, absence de sous-titres) renvoient 409 JOB_NOT_RETRYABLE : corrigez l'entrée et soumettez à nouveau.

La transcription#

iduuidFacultatif

Identique au result_id de la tâche.

sourceobjectFacultatif

platform, media_id, canonical_url, title.

source_originstringFacultatif

creator_captions, platform_captions (sous-titres générés par la plateforme, comme les sous-titres automatiques de YouTube) ou speech_recognition (transcription par IA).

languagestring | nullFacultatif

Étiquette BCP 47 du texte.

textstringFacultatif

La transcription complète, en texte brut.

segmentsarrayFacultatif

Morceaux de la taille de sous-titres : { start, end, text }, en secondes.

wordsarray | nullFacultatif

{ start, end, text, confidence } par mot. Transcription par IA uniquement.

timing_granularity"word" | "segment" | "none"Facultatif

Précision la plus fine disponible.

duration_secondsnumber | nullFacultatif

Durée du média.

extraction_versionstringFacultatif

Version du pipeline qui a produit le résultat.

recognitionobject | nullFacultatif

Transcription par IA uniquement : model, profile, quality_status (validated_language : nous l'avons évaluée ; provider_supported : le modèle la répertorie ; experimental_language : la qualité peut varier).

created_atdate-timeFacultatif

UTC.

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

Les transcriptions sont conservées pendant la durée de rétention de votre forfait : 7 jours pour l'essai, 30 pour Starter, 90 pour Pro et Scale. DELETE /v1/transcripts/{id} permet d'en supprimer une avant ce délai.

Exporter une transcription#

Gratuit et illimité. srt et vtt nécessitent des horodatages. Une transcription sans horodatages renvoie 422 TIMESTAMPS_UNAVAILABLE.

Lots#

Une seule requête, plusieurs vidéos. Chaque élément a les mêmes champs que Créer une tâche. Le lot entier est accepté ou rejeté d'un bloc. Éléments par lot : 1 avec l'essai, 10 avec Starter, 25 avec Pro, 50 avec Scale.

itemsJobRequest[]Requis

De 1 à 50 demandes de tâche.

webhook_endpoint_iduuidFacultatif

Reçoit un seul batch.completed lorsque tous les éléments sont définitifs.

metadataobjectFacultatif

Renvoyé dans l'événement batch.completed.

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

L'objet lot a un status (queued, processing, succeeded, partial_success, failed, cancelled), des compteurs (total_items, succeeded_items, failed_items, cancelled_items) et des items, chacun avec son job_id. Lisez-le avec GET /v1/batches/{id}. Chaque élément est une tâche normale.

Envoi de fichiers#

Votre propre audio ou vidéo (mp3, wav, m4a, ogg, aac, mp4, webm ; jusqu'à 250 Mo et 2 heures). Réservez un emplacement, envoyez le fichier à l'URL signée par une requête PUT, marquez-le comme terminé, puis soumettez-le comme tâche avec source.upload_id. Les envois utilisent toujours la transcription par IA.

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

filenamestringRequis

Jusqu'à 255 caractères.

content_typestringRequis

Le type MIME du fichier, par exemple audio/mpeg ou video/mp4. Envoyez la même valeur sur le PUT.

bytesintegerRequis

Taille exacte du fichier. Le PUT doit correspondre.

L'URL signée est valable 24 heures. Après ce délai, réservez un nouvel emplacement.

Webhooks#

Enregistrez une URL https et transmettez son id comme webhook_endpoint_id lors de la soumission. Nous envoyons un événement en POST lorsque la tâche ou le lot se termine. La réponse contient le secret de signature, une seule fois. L'enregistrement et la désactivation des endpoints nécessitent une session connectée : faites-le sur la page Webhooks du tableau de bord. Une clé API y reçoit 403 FORBIDDEN, mais elle peut lister les endpoints.

urlstringRequis

URL https, jusqu'à 2048 caractères.

descriptionstringFacultatif

Un libellé pour votre propre référence.

Événements#

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

• job.succeeded : récupérez ou exportez result_id.
• job.failed : error contient le code.
• batch.completed : tous les éléments sont définitifs. Lisez le lot pour les résultats par élément.

Répondez par n'importe quel code 2xx en quelques secondes. Les livraisons en échec sont réessayées avec un délai croissant et peuvent être renvoyées depuis le tableau de bord. Un événement peut arriver plus d'une fois : dédoublonnez-le sur event_id.

Vérifier la signature#

En-têtes X-TranscriptDock-Event-Id, X-TranscriptDock-Timestamp et X-TranscriptDock-Signature. La signature est un HMAC-SHA256 (hexadécimal) de {event_id}.{timestamp}.{raw_body} avec votre secret. Rejetez tout événement datant de plus de cinq minutes.

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

Trouver des vidéos#

Recherchez sur YouTube ou listez une chaîne, une playlist ou un profil TikTok, puis transmettez les URL à des tâches. Une recherche de vidéos s'exécute en arrière-plan, comme une tâche : lisez-la avec GET /v1/video-discoveries/{id} jusqu'à ce que status soit succeeded. 1 crédit par page ; les résultats sont conservés 24 heures.

kindstringRequis

youtube_search, youtube_channel_videos, youtube_channel_search, youtube_playlist_videos ou tiktok_user_videos.

querystringFacultatif

Texte de recherche (youtube_search, youtube_channel_search).

channelstringFacultatif

@handle, identifiant de chaîne ou URL de chaîne (types liés à une chaîne).

playliststringFacultatif

Identifiant ou URL de liste de lecture (youtube_playlist_videos).

userstringFacultatif

@user ou URL de profil (tiktok_user_videos).

limitintegerFacultatif

Vidéos par page, de 1 à 50, 20 par défaut. TikTok : 10 au maximum.

cursorstringFacultatif

next_cursor de la page précédente. YouTube uniquement.

include_detailsbooleanFacultatif

TikTok uniquement : récupère aussi, pour chaque vidéo, le nombre de j'aime, de commentaires, les hashtags et les langues de sous-titres.

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

Le POST répond 202 avec status: "queued". Une fois terminée, GET /v1/video-discoveries/{id} ressemble à ceci :

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

Langues de sous-titres d'une vidéo#

Corps { "source": { "url": "https://www.youtube.com/watch?v=..." } } avec une Idempotency-Key (YouTube uniquement, 1 crédit). Lisez GET /v1/language-discoveries/{id} pour obtenir la liste des pistes de sous-titres avec leurs codes, l'indication « créateur » ou « automatique » et la piste par défaut. Utilisez ces codes dans caption_languages.

Utilisation et capacités#

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

credits_remaining exclut déjà credits_reserved (blocages des tâches en cours). prepaid_credits sont les crédits achetés, qui n'expirent jamais.

subscription est l'abonnement Stripe qui sous-tend un forfait payant, et null sans abonnement. Il indique son status, l'interval de facturation (monthly ou yearly), cancel_at_period_end et current_period_end, c'est-à-dire quand le forfait se renouvelle ou prend fin. period_end correspond au renouvellement des crédits mensuels, chaque mois, y compris sur les forfaits annuels.

Ce que votre clé peut faire maintenant : pour chaque source (youtube, tiktok, instagram, upload, direct), les modes disponibles, ainsi que les limites et les tarifs. Lisez cette réponse au lieu de coder ces valeurs en dur. L'essai, par exemple, indique auto et transcribe à false.

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

Limites de requêtes#

Au-delà d'une limite, vous recevez 429 RATE_LIMITED avec un en-tête retry-after (en secondes) et details.detail qui nomme la limite. Rien n'est débité. Les webhooks et ?wait=25 vous tiennent loin de la limite de lecture.

Erreurs#

Toutes les erreurs ont la même forme. retryable: true signifie que la même requête peut réussir plus tard : attendez le nombre de secondes indiqué par retry-after s'il est présent, sinon patientez quelques secondes. Réutilisez ensuite la même Idempotency-Keypour qu'aucune tâche ne soit dupliquée. Pour toute autre erreur, il faut modifier votre côté de l'appel.

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

Une tâche qui échoue après avoir été acceptée reste en 200 sur GET /v1/jobs/{id}, avec status: "failed" et le même objet d'erreur dans error. Une tâche échouée ne coûte rien.

Codes#