Geliştirici Dokümantasyonu

TokCaption API Dokümantasyonu

Herkese açık TikTok videolarını transkript etmek; yapay zeka hook analizi ve senaryo yeniden yazımları çalıştırmak ve transkriptleri ölçekli olarak dışa aktarmak için bir REST API. API anahtarınızla kimlik doğrulayın, bir URL gönderin ve sonuç için sorgulama yapın. API erişimi Pro planda mevcuttur.

REST API · v2.1.0

TokCaption API

Herkese açık TikTok videolarını transkript edin; yapay zeka hook analizi çalıştırın ve ölçekli olarak dışa aktarın — hepsi temiz bir JSON REST API üzerinden. API anahtarınızla kimlik doğrulayın ve iki çağrıyla başlayın. Yapay zeka asistanlarını mı tercih edersiniz? Aynı araçlar Claude ve ChatGPT için bir MCP sunucusu olarak da kullanılabilir.

Temel URL

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

Kimlik doğrulama

X-API-Key

Uç noktalar

6 grup genelinde 27

Kimlik doğrulama

Ayarlar → API Anahtarları bölümünden bir API anahtarı oluşturun (Pro plan). Her istekte X-API-Key başlığıyla gönderin. Panel ve mobil istemciler alternatif olarak Supabase JWT'yi Authorization: Bearer <jwt> olarak gönderebilir. Anahtarları sunucu tarafında tutun; asla bir tarayıcı paketine dahil etmeyin.

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

Hızlı başlangıç

Bir URL gönderin, ardından iş tamamlanana kadar sorgulayın. Tek bir URL genellikle satır içinde tamamlanır — sorgulamadan önce yanıt durumunu kontrol edin.

Adım 1 — Gönder

URL'lerinizle POST /api/v1/jobs çağrısı yapın. Dönen job_id değerini saklayın.

Adım 2 — Sorgula

Durum son duruma ulaşana kadar her 1–2 saniyede bir GET /api/v1/jobs/{jobId} çağırın, ardından items[].transcript_text alanını okuyun.

Yalnızca bir URL mi var ve sorgulama yapmak istemiyor musunuz? Eşzamanlı sonuç için GET /api/v1/quick kullanın.

Hatalar ve hız sınırları

Her hata aynı JSON zarfını döndürür. HTTP durumuna veya mesaja değil, code alanına göre dallanın. 429 durumunda Retry-After başlığına uyun.

Hata zarfı

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

Tüm hata kodları

Kod	HTTP	Anlam
AUTH_REQUIRED	401	Eksik veya geçersiz kimlik bilgileri. Geçerli bir X-API-Key veya Authorization: Bearer <jwt> başlığı gönderin.
VALIDATION_ERROR	400	Geçersiz istek gövdesi, sorgu parametreleri veya yol. Mesaj ve ayrıntılar neyin düzeltilmesi gerektiğini açıklar.
PLAN_REQUIRED	403	Bu özellik veya seçenek Pro plan gerektirir. Kilidi açmak için yükseltin.
NOT_FOUND	404	İş, transkript veya kaynak bulunamadı ya da size ait değil.
QUOTA_EXCEEDED	429	Transkript, ajan, indirme veya çeviri kotasına ulaşıldı. Ücretsiz planda günlük, Pro planda fatura döngüsü başına sıfırlanır. Ayrıntılar için details.reset_at alanına bakın.
RATE_LIMIT_EXCEEDED	429	Kısa sürede çok fazla gönderme, sorgulama veya ajan isteği yapıldı. Retry-After başlığına / details.retry_after_seconds alanına uyun.
DUPLICATE_REQUEST	409	Bir idempotency_key yeniden kullanıldı. Orijinal istek zaten çalıştırıldı.
TRANSLATION_LIMIT_EXCEEDED	429	Aylık çeviri kotasına ulaşıldı. Fatura döneminizde sıfırlanır.
UPSTREAM_TEMPORARY_ERROR	503	TikTok isteği geçici olarak engelledi veya hız sınırına takıldı. Bekleyip tekrar deneyin.
SEGMENTS_UNAVAILABLE	400	Bu dışa aktarma formatı (srt/vtt) için zamanlı segmentler gerekli, ancak transkriptte zamanlı segment yok.
INTERNAL_ERROR	500	Beklenmeyen sunucu hatası. Tekrar deneyin; sorun devam ederse destekle iletişime geçin.

Transkript oluşturma

Transkripsiyon için herkese açık TikTok URL'leri gönderin ve iş ilerlemesini takip edin.

POST/api/v1/jobs

Transkripsiyon işi gönder

submit limiti

Transkripsiyon için 1..N herkese açık TikTok URL'si gönderin. Toplu boyut planınızla sınırlıdır; tek bir URL, tamamlanmış sonucu satır içinde döndürebilir.

Kimlik doğrulama: API anahtarı veya JWTİstek: application/jsonYanıt: 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"}'

İşlem satır içinde tamamlandığında, tek bir URL tamamlanmış veya başarısız bir yükle HTTP 200 döndürebilir.
Toplu işlemler HTTP 202 ile job_id, toplam durum ve items içinde öğe bazında durumlar döndürür.
Video başına durumu görmek için items dizisini inceleyin: queued, processing, completed veya failed.
Ücretsiz planda include_download_assets: true ayarı PLAN_REQUIRED (403) yanıtı döndürür.

Gövde alanları

`urls`zorunlu string[]	TikTok video URL'leri. Ücretsiz planın toplu işlem sınırı 5'tir.
`output_language` string	Hedef transkript dili (ISO kodu). Varsayılan olarak en.
`also_translate_to` string[]	Transkriptin çevrileceği ek diller.
`allow_asr_fallback` boolean	Altyazı parçası yoksa sesi transkript edin. Varsayılan değer false.
`include_download_assets` boolean	İndirme için video/kapak varlıklarını kalıcı olarak saklayın. Yalnızca Pro.
`idempotency_key` string	Tekilleştirme anahtarı; yeniden kullanılması orijinal işi döndürür.

Başarılı yanıt · 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"
    }
  ]
}

Anında tek başarılı yanıt

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

Tek hata (altyazı yok)

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

Hatalar

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429DUPLICATE_REQUEST409UPSTREAM_TEMPORARY_ERROR503

GET/api/v1/jobs

İşleri listele

Transkripsiyon işlerinizi en yeniden eskiye, imleç sayfalandırmasıyla listeleyin.

Kimlik doğrulama: API anahtarı veya JWTİstek: noneYanıt: 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"

Parametreler

`cursor` string (ISO date) · query	Önceki sayfaya dönmek için önceki next_cursor değerini geçirin.
`limit` integer · query	Sayfa boyutu, 1–50. Varsayılan 20.
`status` string · query	İş durumuna göre filtreleyin (ör. completed, processing, failed).

Başarılı yanıt

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

Hatalar

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/jobs/{jobId}

İş durumunu sorgula

poll limiti

Bir işin son duruma ulaşana kadar durumunu sorgulayın. Toplu sayıları ve her öğenin tam ayrıntılarını döndürür.

Kimlik doğrulama: API anahtarı veya JWTİstek: noneYanıt: application/json

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

Son iş durumları completed, partial veya failed'dır; bir iş içindeki öğeler farklılık gösterebilir.
Tamamlanan öğeler transcript_text, segments, translations, metadata ve assets içerir.
Makul bir aralıkla sorgulayın (her 1–2 saniyede bir). HTTP 429 yanıtında retry_after_seconds değerine uyun.

Parametreler

jobIdzorunlu

string · path

POST /api/v1/jobs tarafından döndürülen iş kimliği.

Başarılı yanıt

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

Hatalar

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404RATE_LIMIT_EXCEEDED429INTERNAL_ERROR500

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

Bir işi iptal et

Bir işteki kuyruktaki veya işlenmekte olan öğeleri iptal eder. Serbest bırakılan öğeler kotalarını geri alır.

Kimlik doğrulama: API anahtarı veya JWTİstek: noneYanıt: 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"

Parametreler

jobIdzorunlu

string · path

İptal edilecek iş kimliği.

Başarılı yanıt

{
  "cancelled_count": 3
}

Hatalar

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

GET/api/v1/quick

Hızlı transkripsiyon (tek URL)

submit limiti

Tek bir URL gönderin ve son sonuç için (yaklaşık 55 saniyeye kadar) bekleyin — işler üzerinde eşzamanlı bir kısayol.

Kimlik doğrulama: API anahtarı veya JWTİstek: noneYanıt: 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"

Son duruma ulaşıldığında (completed/failed) HTTP 200 döner; bekleme süresi dolduğunda hâlâ işleniyorsa HTTP 202 döner — bu durumda /api/v1/jobs/{jobId} adresini sorgulayın.

Parametreler

urlzorunlu

string · query

Tek bir TikTok video URL'si.

Başarılı yanıt

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

Hatalar

AUTH_REQUIRED401VALIDATION_ERROR400QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/import/collection

Toplu içe aktarma

Prosubmit limiti

URL listesi veya bağlantı içeren ham metin gönderin. Ücretsiz plan 1 URL kabul eder; toplu işlem için Pro gerekir.

Kimlik doğrulama: API anahtarı veya JWTİstek: application/jsonYanıt: 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"}'

Gövde alanları

`urls` string[]	Açıkça belirtilen URL listesi. Bunu veya metni sağlayın.
`text` string	Serbest metin; TikTok bağlantıları otomatik olarak ayıklanır.
`output_language` string	Hedef transkript dili. Varsayılan olarak en.
`allow_asr_fallback` boolean	Altyazı yoksa sesi transkript edin. Varsayılan değer false.

Başarılı yanıt · 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"
  ]
}

Hatalar

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

Transkriptler

Tamamlanmış transkriptleri ve varlıklarını okuyun, arayın, dışa aktarın ve indirin.

GET/api/v1/history

Transkriptleri listele / ara

poll limiti

Durum, klasör ve sıralama filtreleriyle sayfalandırılmış, aranabilir transkript geçmişi.

Kimlik doğrulama: API anahtarı veya JWTİstek: noneYanıt: application/json

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

Parametreler

`page` integer · query	1 tabanlı sayfa numarası. Varsayılan 1.
`limit` integer · query	Sayfa boyutu, 1–100. Varsayılan 15.
`search` string · query	Transkript metninde ve kaynak URL'de tam metin eşleşmesi.
`status` string · query	completed \| failed \| all. Varsayılan değer all.
`order_by` string · query	created_at_desc \| created_at_asc \| completed_at_desc \| completed_at_asc.

Başarılı yanıt

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

Hatalar

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/transcripts/{id}

Bir transkript getir

poll limiti

Tam metin, segmentler, çeviriler, meta veriler ve varlıklarla birlikte tek bir transkripti kimliğiyle getirin.

Kimlik doğrulama: API anahtarı veya JWTİstek: noneYanıt: application/json

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

Parametreler

idzorunlu

string · path

Transkript ID'si.

Başarılı yanıt

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

Hatalar

AUTH_REQUIRED401NOT_FOUND404VALIDATION_ERROR400

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

Bir transkripti dışa aktar

Bir transkripti txt, srt, vtt, csv, json veya pdf olarak indirin. json ve pdf için Pro gerekir.

Kimlik doğrulama: API anahtarı veya JWTİstek: noneYanıt: 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"

Dosya, Content-Disposition: attachment başlığıyla döndürülür. format=json, { id, text, segments, metadata } döndürür.
srt/vtt için zamanlı segmentler gerekir; aksi halde SEGMENTS_UNAVAILABLE hatası döner.

Parametreler

`id`zorunlu string · path	Transkript ID'si.
`format` string · query	txt \| srt \| vtt \| csv \| json \| pdf. Varsayılan değer txt.
`language` string · query	Kaynak dil yerine bir çeviriyi dışa aktarın.

Başarılı yanıt

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

Hatalar

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400

POST/api/v1/transcripts/export-batch

Toplu dışa aktarma (ZIP)

Birçok transkripti kimlik listesi veya filtrelerle tek seferde ZIP olarak dışa aktarın. json/pdf için Pro gerekir.

Kimlik doğrulama: API anahtarı veya JWTİstek: application/jsonYanıt: 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"}}'

Gövde alanları

`format` string	txt \| srt \| vtt \| csv \| json \| pdf. Varsayılan değer txt.
`ids` string[]	Açık transkript kimlikleri. Filtre kullanmak için atlayın.
`filters` object	{ search?, status?, folderId?, orderBy?, view? }. Yalnızca tamamlanmış transkriptler dışa aktarılır.

Başarılı yanıt

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

Hatalar

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400INTERNAL_ERROR500

DELETE/api/v1/transcripts/{id}

Bir transkripti sil

Bir transkripti, depolanan varlıklarını ve klasör bağlantılarını kalıcı olarak silin.

Kimlik doğrulama: API anahtarı veya JWTİstek: noneYanıt: application/json

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

Parametreler

idzorunlu

string · path

Transkript ID'si.

Başarılı yanıt

{
  "deleted": true
}

Hatalar

AUTH_REQUIRED401NOT_FOUND404INTERNAL_ERROR500

GET/api/v1/transcripts/stats

Transkript istatistikleri

poll limiti

Hesabınıza ait toplam sayılar.

Kimlik doğrulama: API anahtarı veya JWTİstek: noneYanıt: application/json

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

Başarılı yanıt

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

Hatalar

AUTH_REQUIRED401INTERNAL_ERROR500

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

Kaynak videoyu indir

Pro

Orijinal TikTok videosunu MP4 olarak indirin. Yalnızca Pro, aylık indirme kotanızdan düşer.

Kimlik doğrulama: API anahtarı veya JWTİstek: noneYanıt: 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"

video/mp4 dosyasını ek olarak döndürür. Kota yalnızca akış başarıyla tamamlandığında kullanılır.

Parametreler

idzorunlu

string · path

Transkript ID'si.

Başarılı yanıt

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

Hatalar

AUTH_REQUIRED401PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404VALIDATION_ERROR400

AI Ajanları

Bir transkript üzerinde hook analizi, senaryo yeniden yazımları ve viralite puanlaması çalıştırın. (Pro)

POST/api/v1/agents/{agentType}

Yapay zeka ajanı çalıştır

Proagent limiti

Tamamlanmış bir transkript üzerinde yapay zeka analizi kuyruğa alın. agentType şunlardan biridir: hooks, script_rewrite, virality_explain, hook_score.

Kimlik doğrulama: API anahtarı veya JWTİstek: application/jsonYanıt: 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":{}}'

Gövde alanları

`transcript_id`zorunlu string	Analiz edilecek tamamlanmış bir transkript.
`input` object	İsteğe bağlı ajana özgü parametreler.

Parametreler

agentTypezorunlu

string · path

hooks | script_rewrite | virality_explain | hook_score.

Başarılı yanıt · HTTP 202

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

Hatalar

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404RATE_LIMIT_EXCEEDED429

GET/api/v1/agents/runs

Ajan çalıştırmalarını listele

Ajan çalıştırmalarınızı en yeniden eskiye, imleç sayfalandırmasıyla listeleyin.

Kimlik doğrulama: API anahtarı veya JWTİstek: noneYanıt: 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"

Parametreler

`cursor` string (ISO date) · query	Geri gitmek için next_cursor değerini iletin.
`limit` integer · query	Sayfa boyutu, 1–50. Varsayılan 20.

Başarılı yanıt

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

Hatalar

AUTH_REQUIRED401INTERNAL_ERROR500

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

Bir ajan çalıştırması getir

Tamamlandığında yapılandırılmış çıktısı dahil, tek bir yapay zeka ajanı çalıştırmasını getirin.

Kimlik doğrulama: API anahtarı veya JWTİstek: noneYanıt: 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"

Parametreler

runIdzorunlu

string · path

Ajan çalıştırma kimliği.

Başarılı yanıt

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

Hatalar

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404

Çıkar ve Çevir

Düşük seviyeli temel işlemler: meta veri kazıma, metin çevirisi ve yapıştırılan girdinin sınıflandırılması.

POST/api/v1/extract/metadata

Meta verileri kazı

Bir TikTok URL'sini iş oluşturmadan meta verilerine ve mevcut en iyi altyazı parçasına çözümleyin.

Kimlik doğrulama: API anahtarı veya JWTİstek: application/jsonYanıt: 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"}'

Gövde alanları

`url`zorunlu string	Bir TikTok video URL'si.
`output_language` string	Tercih edilen altyazı dili. Varsayılan olarak en.

Başarılı yanıt

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

Hatalar

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/extract/translate

Metni çevir

Transkript metnini ve/veya zamanlı segmentleri bir veya daha fazla dile çevirin.

Kimlik doğrulama: API anahtarı veya JWTİstek: application/jsonYanıt: 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"}'

Gövde alanları

`full_text` string	Çevrilecek metin. Bunu ve/veya segments alanını sağlayın.
`segments` TranscriptSegment[]	Zamanlamayı koruyarak çevrilecek zamanlı segmentler.
`output_language` string	Birincil hedef dil. Varsayılan olarak en.
`additional_languages` string[]	Ek hedef diller.

Başarılı yanıt

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

Hatalar

AUTH_REQUIRED401VALIDATION_ERROR400TRANSLATION_LIMIT_EXCEEDED429INTERNAL_ERROR500

POST/api/v1/workspace/resolve

Yapıştırılan girdiyi çöz

Yapıştırılan metni, @kullanıcı adlarını ve URL'leri video URL'lerine, bir koleksiyon önizlemesine veya profil önizlemesine ayırır.

Kimlik doğrulama: API anahtarı veya JWTİstek: application/jsonYanıt: 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"}'

Gövde alanları

`text` string	Yapıştırılan ham girdi. Bunu veya urls alanını sağlayın.
`urls` string[]	Açıkça belirtilen URL listesi.

Başarılı yanıt

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

Hatalar

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

Klasörler

Transkriptleri klasörlere düzenleyin.

GET/api/v1/folders

Klasörleri listele

Klasörlerinizi öğe sayılarıyla listeleyin.

Kimlik doğrulama: API anahtarı veya JWTİstek: noneYanıt: application/json

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

Başarılı yanıt

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

Hatalar

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/folders

Klasör oluştur

Transkriptleri gruplandırmak için bir klasör oluşturun.

Kimlik doğrulama: API anahtarı veya JWTİstek: application/jsonYanıt: 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"}'

Gövde alanları

namezorunlu

string

Klasör adı.

Başarılı yanıt · HTTP 201

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

Hatalar

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

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

Transkripti klasöre ekle

Bir transkripti klasöre ekle (idempotent).

Kimlik doğrulama: API anahtarı veya JWTİstek: application/jsonYanıt: 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"}'

Gövde alanları

transcript_idzorunlu

string

Eklenecek transkript.

Parametreler

folderIdzorunlu

string · path

Hedef klasör kimliği.

Başarılı yanıt · HTTP 201

{
  "added": true
}

Hatalar

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404INTERNAL_ERROR500

Hesap, Anahtarlar ve Faturalandırma

API anahtarlarını yönetin, planları ve kotayı inceleyin ve geri bildirim gönderin.

POST/api/v1/api-keys

API anahtarı oluştur

Pro

Canlı bir API anahtarı oluşturun. Tam anahtar yalnızca bir kez gösterilir — güvenli bir yerde saklayın. Yalnızca Pro.

Kimlik doğrulama: API anahtarı veya JWTİstek: application/jsonYanıt: 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"}'

Gövde alanları

namezorunlu

string

Anahtarı tanımlamak için bir etiket.

Başarılı yanıt · 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."
}

Hatalar

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/api-keys

API anahtarlarını listele

Pro

Etkin anahtarlarınızı önekle listeleyin (gizli anahtar asla döndürülmez). Yalnızca Pro.

Kimlik doğrulama: API anahtarı veya JWTİstek: noneYanıt: application/json

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

Başarılı yanıt

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

Hatalar

AUTH_REQUIRED401PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/plans

Planları listele

Aktif planların ve limitlerinin herkese açık listesi. Kimlik doğrulama gerekmez.

Kimlik doğrulama: Herkese açık (kimlik doğrulama yok)İstek: noneYanıt: application/json

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

Başarılı yanıt

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

Hatalar

INTERNAL_ERROR500

GET/api/v1/billing/subscription

Abonelik ve kota

Mevcut planınız, abonelik durumunuz ve transkriptler, ajanlar, indirmeler ve çeviriler genelinde anlık kullanım/kota bilgileriniz.

Kimlik doğrulama: API anahtarı veya JWTİstek: noneYanıt: application/json

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

Başarılı yanıt

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

Hatalar

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/feedback

Geri bildirim gönder

Ürün geri bildirimi, hata raporu veya özellik isteği gönderin.

Kimlik doğrulama: API anahtarı veya JWTİstek: application/jsonYanıt: 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!"}'

Gövde alanları

`category`zorunlu string	bug \| feature \| improvement \| other.
`message`zorunlu string	En fazla 2000 karakter.
`rating` integer \| null	İsteğe bağlı 1–5 puan.

Başarılı yanıt

{
  "success": true
}

Hatalar

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

Loading API documentation…

POST/api/v1/jobs

Transkripsiyon işi gönder

submit limiti

Transkripsiyon için 1..N herkese açık TikTok URL'si gönderin. Toplu boyut planınızla sınırlıdır; tek bir URL, tamamlanmış sonucu satır içinde döndürebilir.

Kimlik doğrulama: API anahtarı veya JWTİstek: application/jsonYanıt: 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"}'

İşlem satır içinde tamamlandığında, tek bir URL tamamlanmış veya başarısız bir yükle HTTP 200 döndürebilir.
Toplu işlemler HTTP 202 ile job_id, toplam durum ve items içinde öğe bazında durumlar döndürür.
Video başına durumu görmek için items dizisini inceleyin: queued, processing, completed veya failed.
Ücretsiz planda include_download_assets: true ayarı PLAN_REQUIRED (403) yanıtı döndürür.

Gövde alanları

`urls`zorunlu string[]	TikTok video URL'leri. Ücretsiz planın toplu işlem sınırı 5'tir.
`output_language` string	Hedef transkript dili (ISO kodu). Varsayılan olarak en.
`also_translate_to` string[]	Transkriptin çevrileceği ek diller.
`allow_asr_fallback` boolean	Altyazı parçası yoksa sesi transkript edin. Varsayılan değer false.
`include_download_assets` boolean	İndirme için video/kapak varlıklarını kalıcı olarak saklayın. Yalnızca Pro.
`idempotency_key` string	Tekilleştirme anahtarı; yeniden kullanılması orijinal işi döndürür.

Başarılı yanıt · 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"
    }
  ]
}

Anında tek başarılı yanıt

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

Tek hata (altyazı yok)

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

Hatalar

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429DUPLICATE_REQUEST409UPSTREAM_TEMPORARY_ERROR503