Entwicklerdokumentation

TokCaption API-Dokumentation

Eine REST-API, um öffentliche TikTok-Videos zu transkribieren; KI-Hook-Analysen und Skript-Umschreibungen auszuführen und Transkripte in großem Umfang zu exportieren. Authentifiziere dich mit einem API-Schlüssel, sende eine URL und frage das Ergebnis ab. API-Zugriff ist im Pro-Plan verfügbar.

REST API · v2.1.0

TokCaption API

Transkribiere öffentliche TikTok-Videos, führe KI-Hook-Analysen durch und exportiere in großem Umfang – alles über eine saubere JSON-REST-API. Authentifiziere dich mit einem API-Schlüssel und starte in zwei Aufrufen. Bevorzugst du KI-Assistenten? Dieselben Tools stehen als MCP-Server für Claude und ChatGPT zur Verfügung.

Basis-URL

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

Authentifizierung

X-API-Key

Endpunkte

27 in 6 Gruppen

Authentifizierung

Erstelle einen API-Schlüssel unter Einstellungen → API-Schlüssel (Pro-Plan). Sende ihn bei jeder Anfrage über den Header X-API-Key. Dashboard- und Mobile-Clients können alternativ ein Supabase-JWT als Authorization: Bearer <jwt> senden. Bewahre Schlüssel nur serverseitig auf – niemals in einem Browser-Bundle ausliefern.

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

Schnellstart

Sende eine URL und frage den Job anschließend ab, bis er fertig ist. Eine einzelne URL ist oft direkt abgeschlossen – prüfe vor dem Abfragen den Antwortstatus.

Schritt 1 — Absenden

POST /api/v1/jobs mit deinen URLs aufrufen. Den zurückgegebenen job_id speichern.

Schritt 2 — Abfragen

GET /api/v1/jobs/{jobId} alle 1–2 Sekunden abfragen, bis der Status ein Endstatus ist, und dann items[].transcript_text auslesen.

Nur eine URL und keine Abfrage gewünscht? Nutze GET /api/v1/quick für ein synchrones Ergebnis.

Fehler & Ratenlimits

Jeder Fehler liefert dieselbe JSON-Hülle zurück. Verzweige anhand von code, nicht anhand des HTTP-Status oder der Meldung. Bei 429 beachte den Header Retry-After.

Fehler-Envelope

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

Alle Fehlercodes

Code	HTTP	Bedeutung
AUTH_REQUIRED	401	Fehlende oder ungültige Anmeldedaten. Sende einen gültigen X-API-Key oder einen Authorization: Bearer <jwt>-Header.
VALIDATION_ERROR	400	Ungültiger Anfragetext, ungültige Abfrageparameter oder ungültiger Pfad. Die Meldung und die Details erklären, was korrigiert werden muss.
PLAN_REQUIRED	403	Diese Funktion oder Option erfordert einen Pro-Plan. Jetzt upgraden, um sie freizuschalten.
NOT_FOUND	404	Auftrag, Transkript oder Ressource nicht gefunden oder nicht in deinem Besitz.
QUOTA_EXCEEDED	429	Kontingent für Transkripte, Agenten, Downloads oder Übersetzungen erreicht. Es wird täglich (kostenlos) bzw. pro Abrechnungszyklus (Pro) zurückgesetzt. Siehe details.reset_at.
RATE_LIMIT_EXCEEDED	429	Zu viele Übermittlungs-, Abfrage- oder Agent-Anfragen in kurzer Zeit. Beachte den Retry-After-Header bzw. details.retry_after_seconds.
DUPLICATE_REQUEST	409	Ein idempotency_key wurde erneut verwendet. Die ursprüngliche Anfrage wurde bereits ausgeführt.
TRANSLATION_LIMIT_EXCEEDED	429	Monatliches Übersetzungskontingent erreicht. Wird im Abrechnungszyklus zurückgesetzt.
UPSTREAM_TEMPORARY_ERROR	503	TikTok hat die Anfrage vorübergehend blockiert oder gedrosselt. Mit Backoff erneut versuchen.
SEGMENTS_UNAVAILABLE	400	Für dieses Exportformat (srt/vtt) werden zeitgestempelte Segmente benötigt, das Transkript enthält jedoch keine.
INTERNAL_ERROR	500	Unerwarteter Serverfehler. Bitte erneut versuchen und den Support kontaktieren, falls das Problem bestehen bleibt.

Transkription

Sende öffentliche TikTok-URLs zur Transkription und verfolge den Fortschritt der Aufträge.

POST/api/v1/jobs

Transkriptionsjob absenden

Limit submit

Sende 1..N öffentliche TikTok-URLs zur Transkription. Die Batch-Größe ist durch deinen Plan begrenzt; eine einzelne URL kann ein fertiges Ergebnis direkt in der Antwort liefern.

Auth: API-Schlüssel oder JWTAnfrage: application/jsonAntwort: 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"}'

Eine einzelne URL kann HTTP 200 mit einer Endstatus-Antwort (completed oder failed) zurückgeben, wenn die Verarbeitung direkt abgeschlossen wird.
Batches geben HTTP 202 mit job_id, einem Gesamtstatus und den Einzelstatus der Elemente in items zurück.
Prüfe das Array items auf den Status der einzelnen Videos: queued, processing, completed oder failed.
Wird include_download_assets: true im kostenlosen Plan gesetzt, wird PLAN_REQUIRED (403) zurückgegeben.

Body-Felder

`urls`erforderlich string[]	TikTok-Video-URLs. Die Batch-Obergrenze im kostenlosen Plan liegt bei 5.
`output_language` string	Zielsprache des Transkripts (ISO-Code). Standard ist en.
`also_translate_to` string[]	Zusätzliche Sprachen, in die das Transkript übersetzt werden soll.
`allow_asr_fallback` boolean	Audio transkribieren, wenn keine Untertitelspur vorhanden ist. Standardmäßig false.
`include_download_assets` boolean	Speichert Video-/Cover-Assets zum Download. Nur für Pro.
`idempotency_key` string	Deduplizierungsschlüssel; bei erneuter Verwendung wird der ursprüngliche Job zurückgegeben.

Erfolgreiche Antwort · 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"
    }
  ]
}

Sofortiger Einzelerfolg

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

Einzelner Fehlschlag (keine Untertitel)

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

Fehler

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429DUPLICATE_REQUEST409UPSTREAM_TEMPORARY_ERROR503

GET/api/v1/jobs

Aufträge auflisten

Liste deine Transkriptionsaufträge, neueste zuerst, mit Cursor-Paginierung.

Auth: API-Schlüssel oder JWTAnfrage: noneAntwort: 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"

Parameter

`cursor` string (ISO date) · query	Übergib den vorherigen next_cursor, um zurück in der Zeit zu blättern.
`limit` integer · query	Seitengröße, 1–50. Standard ist 20.
`status` string · query	Nach Auftragsstatus filtern (z. B. completed, processing, failed).

Erfolgreiche Antwort

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

Fehler

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/jobs/{jobId}

Job-Status abfragen

Limit poll

Fragt einen Job ab, bis er einen Endzustand erreicht. Gibt aggregierte Zahlen sowie alle Details pro Element zurück.

Auth: API-Schlüssel oder JWTAnfrage: noneAntwort: application/json

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

Endzustände eines Jobs sind completed, partial oder failed; einzelne Elemente innerhalb eines Jobs können abweichen.
Abgeschlossene Elemente enthalten transcript_text, segments, translations, metadata und assets.
Frage in einem sinnvollen Intervall ab (alle 1–2 Sekunden). Bei HTTP 429 die Angabe retry_after_seconds beachten.

Parameter

jobIderforderlich

string · path

Auftrags-ID, die von POST /api/v1/jobs zurückgegeben wurde.

Erfolgreiche Antwort

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

Fehler

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404RATE_LIMIT_EXCEEDED429INTERNAL_ERROR500

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

Einen Job abbrechen

Wartende oder laufende Elemente eines Jobs abbrechen. Freigegebene Elemente geben ihr Kontingent zurück.

Auth: API-Schlüssel oder JWTAnfrage: noneAntwort: 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"

Parameter

jobIderforderlich

string · path

Auftrags-ID, die abgebrochen werden soll.

Erfolgreiche Antwort

{
  "cancelled_count": 3
}

Fehler

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

GET/api/v1/quick

Schnelltranskription (eine URL)

Limit submit

Sende eine einzelne URL und warte (bis zu ca. 55 s) auf ein Endergebnis – ein synchroner Shortcut für Jobs.

Auth: API-Schlüssel oder JWTAnfrage: noneAntwort: 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"

Gibt HTTP 200 zurück, sobald der Endzustand (abgeschlossen/fehlgeschlagen) erreicht ist, oder HTTP 202, wenn die Verarbeitung nach Ablauf des Wartefensters noch läuft – frage dann /api/v1/jobs/{jobId} ab.

Parameter

urlerforderlich

string · query

Eine einzelne TikTok-Video-URL.

Erfolgreiche Antwort

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

Fehler

AUTH_REQUIRED401VALIDATION_ERROR400QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/import/collection

Massenimport

ProLimit submit

Sende eine Liste von URLs oder Rohtext mit Links. Der kostenlose Plan akzeptiert 1 URL; Massenimporte erfordern Pro.

Auth: API-Schlüssel oder JWTAnfrage: application/jsonAntwort: 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"}'

Body-Felder

`urls` string[]	Explizite URL-Liste. Entweder diese oder Text angeben.
`text` string	Freier Text; TikTok-Links werden automatisch erkannt.
`output_language` string	Zielsprache des Transkripts. Standard ist en.
`allow_asr_fallback` boolean	Audio transkribieren, wenn keine Untertitel vorhanden sind. Standardmäßig false.

Erfolgreiche Antwort · 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"
  ]
}

Fehler

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

Transkripte

Fertige Transkripte und ihre Assets lesen, durchsuchen, exportieren und herunterladen.

GET/api/v1/history

Transkripte auflisten / durchsuchen

Limit poll

Paginierte, durchsuchbare Transkriptliste mit Filtern nach Status, Ordner und Sortierung.

Auth: API-Schlüssel oder JWTAnfrage: noneAntwort: application/json

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

Parameter

`page` integer · query	1-basierte Seitenzahl. Standardwert ist 1.
`limit` integer · query	Seitengröße, 1–100. Standard ist 15.
`search` string · query	Volltextsuche in Transkripttext und Quell-URL.
`status` string · query	completed \| failed \| all. Standardmäßig all.
`order_by` string · query	created_at_desc \| created_at_asc \| completed_at_desc \| completed_at_asc.

Erfolgreiche Antwort

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

Fehler

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/transcripts/{id}

Ein Transkript abrufen

Limit poll

Ein einzelnes Transkript per ID abrufen, mit vollständigem Text, Segmenten, Übersetzungen, Metadaten und Assets.

Auth: API-Schlüssel oder JWTAnfrage: noneAntwort: application/json

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

Parameter

iderforderlich

string · path

Transkript-ID.

Erfolgreiche Antwort

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

Fehler

AUTH_REQUIRED401NOT_FOUND404VALIDATION_ERROR400

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

Ein Transkript exportieren

Lade ein Transkript als txt, srt, vtt, csv, json oder pdf herunter. json und pdf erfordern Pro.

Auth: API-Schlüssel oder JWTAnfrage: noneAntwort: 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"

Gibt die Datei mit Content-Disposition: attachment zurück. format=json liefert { id, text, segments, metadata }.
srt/vtt erfordern zeitgestempelte Segmente – andernfalls SEGMENTS_UNAVAILABLE.

Parameter

`id`erforderlich string · path	Transkript-ID.
`format` string · query	txt \| srt \| vtt \| csv \| json \| pdf. Standardmäßig txt.
`language` string · query	Eine Übersetzung statt der Quellsprache exportieren.

Erfolgreiche Antwort

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

Fehler

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400

POST/api/v1/transcripts/export-batch

Batch-Export (ZIP)

Viele Transkripte auf einmal als ZIP exportieren, per ID-Liste oder nach Filtern. json/pdf erfordern Pro.

Auth: API-Schlüssel oder JWTAnfrage: application/jsonAntwort: 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"}}'

Body-Felder

`format` string	txt \| srt \| vtt \| csv \| json \| pdf. Standardmäßig txt.
`ids` string[]	Explizite Transkript-IDs. Weglassen, um Filter zu verwenden.
`filters` object	{ search?, status?, folderId?, orderBy?, view? }. Es werden nur abgeschlossene Transkripte exportiert.

Erfolgreiche Antwort

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

Fehler

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400INTERNAL_ERROR500

DELETE/api/v1/transcripts/{id}

Ein Transkript löschen

Löscht ein Transkript, seine gespeicherten Assets und Ordnerverknüpfungen dauerhaft.

Auth: API-Schlüssel oder JWTAnfrage: noneAntwort: application/json

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

Parameter

iderforderlich

string · path

Transkript-ID.

Erfolgreiche Antwort

{
  "deleted": true
}

Fehler

AUTH_REQUIRED401NOT_FOUND404INTERNAL_ERROR500

GET/api/v1/transcripts/stats

Transkript-Statistiken

Limit poll

Aggregierte Zählwerte für dein Konto.

Auth: API-Schlüssel oder JWTAnfrage: noneAntwort: application/json

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

Erfolgreiche Antwort

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

Fehler

AUTH_REQUIRED401INTERNAL_ERROR500

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

Quellvideo herunterladen

Pro

Lade das Original-TikTok-Video als MP4 herunter. Nur für Pro, zählt auf dein monatliches Download-Kontingent.

Auth: API-Schlüssel oder JWTAnfrage: noneAntwort: 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"

Gibt video/mp4 als Anhang zurück. Das Kontingent wird nur bei erfolgreichem Stream verbraucht.

Parameter

iderforderlich

string · path

Transkript-ID.

Erfolgreiche Antwort

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

Fehler

AUTH_REQUIRED401PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404VALIDATION_ERROR400

KI-Agenten

Führt Hook-Analyse, Skript-Umschreibungen und Viralitätsbewertung für ein Transkript aus. (Pro)

POST/api/v1/agents/{agentType}

KI-Agent ausführen

ProLimit agent

Stellt eine KI-Analyse für ein abgeschlossenes Transkript in die Warteschlange. agentType ist einer von hooks, script_rewrite, virality_explain, hook_score.

Auth: API-Schlüssel oder JWTAnfrage: application/jsonAntwort: 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":{}}'

Body-Felder

`transcript_id`erforderlich string	Ein fertiges Transkript zur Analyse.
`input` object	Optionale agentenspezifische Parameter.

Parameter

agentTypeerforderlich

string · path

hooks | script_rewrite | virality_explain | hook_score.

Erfolgreiche Antwort · HTTP 202

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

Fehler

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404RATE_LIMIT_EXCEEDED429

GET/api/v1/agents/runs

Agentenläufe auflisten

Liste deine Agentenläufe, neueste zuerst, mit Cursor-Paginierung.

Auth: API-Schlüssel oder JWTAnfrage: noneAntwort: 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"

Parameter

`cursor` string (ISO date) · query	Übergib next_cursor, um zurückzublättern.
`limit` integer · query	Seitengröße, 1–50. Standard ist 20.

Erfolgreiche Antwort

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

Fehler

AUTH_REQUIRED401INTERNAL_ERROR500

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

Einen Agentenlauf abrufen

Einen Agentenlauf abrufen, einschließlich seiner strukturierten Ausgabe, sobald er abgeschlossen ist.

Auth: API-Schlüssel oder JWTAnfrage: noneAntwort: 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"

Parameter

runIderforderlich

string · path

Agent-Lauf-ID.

Erfolgreiche Antwort

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

Fehler

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404

Extrahieren & übersetzen

Grundlegende Bausteine: Metadaten abrufen, Text übersetzen und eingefügte Eingaben klassifizieren.

POST/api/v1/extract/metadata

Metadaten auslesen

Löst eine TikTok-URL in ihre Metadaten und die bestverfügbare Untertitelspur auf, ohne einen Job zu erstellen.

Auth: API-Schlüssel oder JWTAnfrage: application/jsonAntwort: 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"}'

Body-Felder

`url`erforderlich string	Eine TikTok-Video-URL.
`output_language` string	Bevorzugte Untertitelsprache. Standard ist en.

Erfolgreiche Antwort

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

Fehler

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/extract/translate

Text übersetzen

Übersetze Transkripttext und/oder zeitgestempelte Segmente in eine oder mehrere Sprachen.

Auth: API-Schlüssel oder JWTAnfrage: application/jsonAntwort: 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"}'

Body-Felder

`full_text` string	Zu übersetzender Text. Angeben und/oder segments verwenden.
`segments` TranscriptSegment[]	Zeitgestempelte Segmente, die unter Beibehaltung des Timings übersetzt werden sollen.
`output_language` string	Primäre Zielsprache. Standard ist en.
`additional_languages` string[]	Zusätzliche Zielsprachen.

Erfolgreiche Antwort

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

Fehler

AUTH_REQUIRED401VALIDATION_ERROR400TRANSLATION_LIMIT_EXCEEDED429INTERNAL_ERROR500

POST/api/v1/workspace/resolve

Eingefügte Eingabe auflösen

Klassifiziert eingefügten Text / @Handles / URLs in Video-URLs, eine Sammlungsvorschau oder eine Profilvorschau.

Auth: API-Schlüssel oder JWTAnfrage: application/jsonAntwort: 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"}'

Body-Felder

`text` string	Eingefügter Rohtext. Entweder dies oder urls angeben.
`urls` string[]	Explizite URL-Liste.

Erfolgreiche Antwort

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

Fehler

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

Ordner

Transkripte in Ordnern organisieren.

GET/api/v1/folders

Ordner auflisten

Liste deine Ordner mit Anzahl der Einträge auf.

Auth: API-Schlüssel oder JWTAnfrage: noneAntwort: application/json

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

Erfolgreiche Antwort

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

Fehler

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/folders

Ordner erstellen

Erstelle einen Ordner, um Transkripte zu gruppieren.

Auth: API-Schlüssel oder JWTAnfrage: application/jsonAntwort: 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"}'

Body-Felder

nameerforderlich

string

Ordnername.

Erfolgreiche Antwort · HTTP 201

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

Fehler

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

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

Transkript zum Ordner hinzufügen

Ein Transkript zu einem Ordner hinzufügen (idempotent).

Auth: API-Schlüssel oder JWTAnfrage: application/jsonAntwort: 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"}'

Body-Felder

transcript_iderforderlich

string

Hinzuzufügendes Transkript.

Parameter

folderIderforderlich

string · path

Zielordner-ID.

Erfolgreiche Antwort · HTTP 201

{
  "added": true
}

Fehler

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404INTERNAL_ERROR500

Konto, Schlüssel & Abrechnung

API-Schlüssel verwalten, Pläne und Kontingent einsehen und Feedback senden.

POST/api/v1/api-keys

API-Schlüssel erstellen

Pro

Einen aktiven API-Schlüssel erstellen. Der vollständige Schlüssel wird nur einmal angezeigt – bitte sicher speichern. Nur für Pro.

Auth: API-Schlüssel oder JWTAnfrage: application/jsonAntwort: 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"}'

Body-Felder

nameerforderlich

string

Eine Bezeichnung zur Identifizierung des Schlüssels.

Erfolgreiche Antwort · 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."
}

Fehler

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/api-keys

API-Schlüssel auflisten

Pro

Liste deine aktiven Schlüssel nach Präfix auf (der Schlüssel selbst wird nie zurückgegeben). Nur für Pro.

Auth: API-Schlüssel oder JWTAnfrage: noneAntwort: application/json

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

Erfolgreiche Antwort

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

Fehler

AUTH_REQUIRED401PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/plans

Pläne auflisten

Öffentliche Liste der aktiven Pläne und ihrer Limits. Keine Authentifizierung erforderlich.

Auth: Öffentlich (keine Authentifizierung)Anfrage: noneAntwort: application/json

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

Erfolgreiche Antwort

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

Fehler

INTERNAL_ERROR500

GET/api/v1/billing/subscription

Abo & Kontingent

Dein aktueller Plan, Abonnementstatus sowie die aktuelle Nutzung und Kontingente für Transkripte, Agenten, Downloads und Übersetzungen.

Auth: API-Schlüssel oder JWTAnfrage: noneAntwort: application/json

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

Erfolgreiche Antwort

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

Fehler

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/feedback

Feedback senden

Sende Produktfeedback, einen Fehlerbericht oder eine Funktionsanfrage.

Auth: API-Schlüssel oder JWTAnfrage: application/jsonAntwort: 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!"}'

Body-Felder

`category`erforderlich string	bug \| feature \| improvement \| other.
`message`erforderlich string	Bis zu 2000 Zeichen.
`rating` integer \| null	Optionale Bewertung von 1–5.

Erfolgreiche Antwort

{
  "success": true
}

Fehler

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

Loading API documentation…

POST/api/v1/jobs

Transkriptionsjob absenden

Limit submit

Sende 1..N öffentliche TikTok-URLs zur Transkription. Die Batch-Größe ist durch deinen Plan begrenzt; eine einzelne URL kann ein fertiges Ergebnis direkt in der Antwort liefern.

Auth: API-Schlüssel oder JWTAnfrage: application/jsonAntwort: 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"}'

Eine einzelne URL kann HTTP 200 mit einer Endstatus-Antwort (completed oder failed) zurückgeben, wenn die Verarbeitung direkt abgeschlossen wird.
Batches geben HTTP 202 mit job_id, einem Gesamtstatus und den Einzelstatus der Elemente in items zurück.
Prüfe das Array items auf den Status der einzelnen Videos: queued, processing, completed oder failed.
Wird include_download_assets: true im kostenlosen Plan gesetzt, wird PLAN_REQUIRED (403) zurückgegeben.

Body-Felder

`urls`erforderlich string[]	TikTok-Video-URLs. Die Batch-Obergrenze im kostenlosen Plan liegt bei 5.
`output_language` string	Zielsprache des Transkripts (ISO-Code). Standard ist en.
`also_translate_to` string[]	Zusätzliche Sprachen, in die das Transkript übersetzt werden soll.
`allow_asr_fallback` boolean	Audio transkribieren, wenn keine Untertitelspur vorhanden ist. Standardmäßig false.
`include_download_assets` boolean	Speichert Video-/Cover-Assets zum Download. Nur für Pro.
`idempotency_key` string	Deduplizierungsschlüssel; bei erneuter Verwendung wird der ursprüngliche Job zurückgegeben.

Erfolgreiche Antwort · 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"
    }
  ]
}

Sofortiger Einzelerfolg

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

Einzelner Fehlschlag (keine Untertitel)

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

Fehler

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429DUPLICATE_REQUEST409UPSTREAM_TEMPORARY_ERROR503