डेवलपर डॉक्यूमेंटेशन

TokCaption API दस्तावेज़ीकरण

सार्वजनिक TikTok वीडियो को ट्रांसक्राइब करने के लिए एक REST API; AI हुक एनालिसिस और स्क्रिप्ट रीराइट चलाएँ; और बड़े पैमाने पर ट्रांसक्रिप्ट एक्सपोर्ट करें। API की से ऑथेंटिकेट करें, एक URL सबमिट करें, और परिणाम के लिए पोल करें। API एक्सेस Pro प्लान पर उपलब्ध है।

REST API · v2.1.0

TokCaption API

सार्वजनिक TikTok वीडियो ट्रांसक्राइब करें; AI हुक एनालिसिस चलाएँ; और बड़े पैमाने पर एक्सपोर्ट करें — यह सब एक साफ़ JSON REST API के माध्यम से। API key से ऑथेंटिकेट करें और दो कॉल में शुरू करें। AI असिस्टेंट पसंद करते हैं? वही टूल Claude और ChatGPT के लिए MCP server के रूप में भी उपलब्ध हैं।

बेस URL

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

ऑथ

X-API-Key

एंडपॉइंट्स

6 समूहों में कुल 27

प्रमाणीकरण

Settings → API Keys (Pro प्लान) से API key बनाएँ। हर अनुरोध में इसे X-API-Key हेडर के ज़रिए भेजें। डैशबोर्ड और मोबाइल क्लाइंट वैकल्पिक रूप से Supabase JWT को Authorization: Bearer <jwt> के रूप में भेज सकते हैं। Keys को सर्वर-साइड पर रखें — इन्हें कभी ब्राउज़र बंडल में न भेजें।

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

क्विकस्टार्ट

एक URL सबमिट करें, फिर जॉब पूरा होने तक उसकी स्थिति जाँचें। एक URL अक्सर तुरंत पूरा हो जाता है — स्थिति जाँचने से पहले रिस्पॉन्स का status देखें।

चरण 1 — सबमिट करें

अपने URL के साथ POST /api/v1/jobs कॉल करें। लौटाए गए job_id को सेव करें।

चरण 2 — स्थिति जाँचें

जब तक स्टेटस टर्मिनल न हो जाए, हर 1–2 सेकंड में GET /api/v1/jobs/{jobId} कॉल करें, फिर items[].transcript_text पढ़ें।

सिर्फ़ एक URL है और पोलिंग नहीं करना चाहते? सिंक्रोनस परिणाम के लिए GET /api/v1/quick का उपयोग करें।

एरर और रेट लिमिट

हर एरर एक ही JSON एनवेलप लौटाता है। निर्णय code के आधार पर लें, HTTP स्टेटस या संदेश के आधार पर नहीं। 429 पर Retry-After हेडर का सम्मान करें।

एरर एनवेलप

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

सभी एरर कोड

कोड	HTTP	अर्थ
AUTH_REQUIRED	401	क्रेडेंशियल्स गायब या अमान्य हैं। वैध X-API-Key भेजें, या Authorization: Bearer <jwt> हेडर भेजें।
VALIDATION_ERROR	400	अमान्य रिक्वेस्ट बॉडी, क्वेरी पैरामीटर या पाथ। संदेश और विवरण बताते हैं कि क्या ठीक करना है।
PLAN_REQUIRED	403	यह फ़ीचर या विकल्प Pro प्लान की आवश्यकता रखता है। अनलॉक करने के लिए अपग्रेड करें।
NOT_FOUND	404	जॉब, ट्रांसक्रिप्ट या रिसोर्स नहीं मिला, या वह आपका नहीं है।
QUOTA_EXCEEDED	429	ट्रांसक्रिप्ट, एजेंट, डाउनलोड या अनुवाद की सीमा पूरी हो गई है। फ्री प्लान में रोज़ाना और Pro में हर बिलिंग चक्र में रीसेट होती है। details.reset_at देखें।
RATE_LIMIT_EXCEEDED	429	कम समय में बहुत सारे submit, poll या एजेंट अनुरोध भेजे गए हैं। Retry-After हेडर / details.retry_after_seconds का पालन करें।
DUPLICATE_REQUEST	409	एक idempotency_key दोबारा इस्तेमाल हुई है। मूल अनुरोध पहले ही चल चुका है।
TRANSLATION_LIMIT_EXCEEDED	429	मासिक अनुवाद कोटा पूरा हो गया। आपके बिलिंग चक्र पर रीसेट होगा।
UPSTREAM_TEMPORARY_ERROR	503	TikTok ने अनुरोध को अस्थायी रूप से ब्लॉक या रेट-लिमिट कर दिया है। बैकऑफ़ के साथ फिर से प्रयास करें।
SEGMENTS_UNAVAILABLE	400	इस एक्सपोर्ट फ़ॉर्मैट (srt/vtt) के लिए टाइमिंग वाले सेगमेंट ज़रूरी हैं, लेकिन ट्रांसक्रिप्ट में कोई नहीं है।
INTERNAL_ERROR	500	सर्वर में अप्रत्याशित त्रुटि हुई। फिर से प्रयास करें, और समस्या बनी रहे तो सपोर्ट से संपर्क करें।

ट्रांसक्रिप्शन

ट्रांसक्रिप्शन के लिए सार्वजनिक TikTok URL सबमिट करें और जॉब की प्रगति ट्रैक करें।

POST/api/v1/jobs

ट्रांसक्रिप्शन जॉब सबमिट करें

submit सीमा

ट्रांसक्रिप्शन के लिए 1..N सार्वजनिक TikTok URL सबमिट करें। बैच का आकार आपके प्लान से सीमित है; एक single URL का परिणाम तुरंत इनलाइन लौट सकता है।

ऑथ: API key या JWTReq: application/jsonRes: 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"}'

जब प्रोसेसिंग इनलाइन पूरी होती है, तो एक ही URL HTTP 200 के साथ टर्मिनल completed या failed पेलोड लौटा सकता है।
बैच HTTP 202 के साथ job_id, एग्रीगेट स्टेटस और items के अंदर हर आइटम का स्टेटस लौटाते हैं।
प्रति वीडियो स्थिति के लिए items ऐरे देखें: queued, processing, completed, या failed।
फ़्री प्लान पर include_download_assets: true सेट करने पर PLAN_REQUIRED (403) लौटता है।

बॉडी फ़ील्ड्स

`urls`आवश्यक string[]	TikTok वीडियो URL। फ्री प्लान में बैच की सीमा 5 है।
`output_language` string	लक्ष्य ट्रांसक्रिप्ट भाषा (ISO कोड)। डिफ़ॉल्ट en है।
`also_translate_to` string[]	ट्रांसक्रिप्ट का अनुवाद करने के लिए अतिरिक्त भाषाएँ।
`allow_asr_fallback` boolean	अगर कोई कैप्शन ट्रैक नहीं है, तो ऑडियो का ट्रांसक्रिप्ट बनाएं। डिफ़ॉल्ट रूप से false।
`include_download_assets` boolean	डाउनलोड के लिए वीडियो/कवर एसेट्स सेव करें। केवल Pro के लिए।
`idempotency_key` string	डेडुप्लीकेशन key; इसे दोबारा इस्तेमाल करने पर मूल जॉब लौटता है।

सफल रिस्पॉन्स · 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"
    }
  ]
}

तुरंत एकल सफलता

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

एकल विफलता (कैप्शन नहीं)

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

एरर

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429DUPLICATE_REQUEST409UPSTREAM_TEMPORARY_ERROR503

GET/api/v1/jobs

जॉब्स की सूची

कर्सर पेजिनेशन के साथ, नवीनतम पहले, अपने ट्रांसक्रिप्शन जॉब्स की सूची देखें।

ऑथ: API key या JWTReq: noneRes: 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"

पैरामीटर

`cursor` string (ISO date) · query	पिछले समय में वापस जाने के लिए पिछला next_cursor पास करें।
`limit` integer · query	पेज साइज़, 1–50। डिफ़ॉल्ट 20।
`status` string · query	जॉब स्थिति के अनुसार फ़िल्टर करें (जैसे completed, processing, failed)।

सफल रिस्पॉन्स

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

एरर

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/jobs/{jobId}

जॉब स्थिति जाँचें

poll सीमा

जॉब के टर्मिनल स्टेट तक पहुँचने तक उसकी स्थिति जाँचें। एग्रीगेट काउंट के साथ हर आइटम का पूरा विवरण लौटाता है।

ऑथ: API key या JWTReq: noneRes: application/json

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

टर्मिनल जॉब स्टेट completed, partial, या failed हैं; किसी जॉब के भीतर अलग-अलग आइटम भिन्न हो सकते हैं।
पूरे हुए आइटम्स में transcript_text, segments, translations, metadata और assets शामिल होते हैं।
उचित अंतराल पर स्थिति जाँचें (हर 1–2 सेकंड)। HTTP 429 आने पर retry_after_seconds का पालन करें।

पैरामीटर

jobIdआवश्यक

string · path

POST /api/v1/jobs से लौटाया गया जॉब ID।

सफल रिस्पॉन्स

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

एरर

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404RATE_LIMIT_EXCEEDED429INTERNAL_ERROR500

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

जॉब रद्द करें

किसी जॉब में queued या processing आइटम रद्द करें। जारी किए गए आइटम अपना कोटा वापस पाते हैं।

ऑथ: API key या JWTReq: noneRes: 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"

पैरामीटर

jobIdआवश्यक

string · path

रद्द करने के लिए जॉब ID।

सफल रिस्पॉन्स

{
  "cancelled_count": 3
}

एरर

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

GET/api/v1/quick

क्विक ट्रांसक्राइब (एक URL)

submit सीमा

एक URL सबमिट करें और अंतिम परिणाम के लिए (लगभग 55 सेकंड तक) प्रतीक्षा करें — जॉब्स का एक सिंक्रोनस शॉर्टकट।

ऑथ: API key या JWTReq: noneRes: 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"

टर्मिनल स्टेट (completed/failed) पर HTTP 200 लौटता है, या यदि प्रतीक्षा अवधि समाप्त होने पर अभी भी प्रोसेस हो रहा हो तो HTTP 202 — फिर /api/v1/jobs/{jobId} की स्थिति जाँचें।

पैरामीटर

urlआवश्यक

string · query

एक एकल TikTok वीडियो URL।

सफल रिस्पॉन्स

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

एरर

AUTH_REQUIRED401VALIDATION_ERROR400QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/import/collection

बल्क इम्पोर्ट

Prosubmit सीमा

URL की सूची या लिंक वाला कच्चा टेक्स्ट सबमिट करें। फ़्री प्लान में 1 URL स्वीकार होता है; बल्क के लिए Pro आवश्यक है।

ऑथ: API key या JWTReq: application/jsonRes: 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"}'

बॉडी फ़ील्ड्स

`urls` string[]	स्पष्ट URL सूची। यह या टेक्स्ट दें।
`text` string	मुक्त टेक्स्ट; TikTok लिंक अपने-आप निकाल लिए जाते हैं।
`output_language` string	लक्ष्य ट्रांसक्रिप्ट भाषा। डिफ़ॉल्ट en है।
`allow_asr_fallback` boolean	अगर कोई कैप्शन नहीं है, तो ऑडियो का ट्रांसक्रिप्ट बनाएं। डिफ़ॉल्ट रूप से false।

सफल रिस्पॉन्स · 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"
  ]
}

एरर

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

ट्रांसक्रिप्ट

पूर्ण ट्रांसक्रिप्ट और उनके एसेट्स पढ़ें, खोजें, एक्सपोर्ट करें और डाउनलोड करें।

GET/api/v1/history

ट्रांसक्रिप्ट सूची / खोजें

poll सीमा

स्थिति, फ़ोल्डर और क्रम फ़िल्टर के साथ पेजिनेटेड, खोज योग्य ट्रांसक्रिप्ट इतिहास।

ऑथ: API key या JWTReq: noneRes: application/json

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

पैरामीटर

`page` integer · query	1-आधारित पेज नंबर। डिफ़ॉल्ट 1 है।
`limit` integer · query	पेज साइज़, 1–100। डिफ़ॉल्ट 15।
`search` string · query	ट्रांसक्रिप्ट टेक्स्ट और स्रोत URL पर पूर्ण-टेक्स्ट मिलान।
`status` string · query	completed \| failed \| all। डिफ़ॉल्ट all।
`order_by` string · query	created_at_desc \| created_at_asc \| completed_at_desc \| completed_at_asc।

सफल रिस्पॉन्स

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

एरर

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/transcripts/{id}

ट्रांसक्रिप्ट प्राप्त करें

poll सीमा

पूरे टेक्स्ट, सेगमेंट, अनुवाद, मेटाडेटा और एसेट्स के साथ ID द्वारा एक ट्रांसक्रिप्ट प्राप्त करें।

ऑथ: API key या JWTReq: noneRes: application/json

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

पैरामीटर

idआवश्यक

string · path

ट्रांसक्रिप्ट ID।

सफल रिस्पॉन्स

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

एरर

AUTH_REQUIRED401NOT_FOUND404VALIDATION_ERROR400

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

ट्रांसक्रिप्ट एक्सपोर्ट करें

किसी ट्रांसक्रिप्ट को txt, srt, vtt, csv, json या pdf में डाउनलोड करें। json और pdf के लिए Pro आवश्यक है।

ऑथ: API key या JWTReq: noneRes: 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"

Content-Disposition: attachment के साथ फ़ाइल लौटाता है। format=json { id, text, segments, metadata } लौटाता है।
srt/vtt के लिए टाइमिंग वाले सेगमेंट ज़रूरी हैं — अन्यथा SEGMENTS_UNAVAILABLE।

पैरामीटर

`id`आवश्यक string · path	ट्रांसक्रिप्ट ID।
`format` string · query	txt \| srt \| vtt \| csv \| json \| pdf। डिफ़ॉल्ट txt।
`language` string · query	स्रोत भाषा के बजाय अनुवाद एक्सपोर्ट करें।

सफल रिस्पॉन्स

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

एरर

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400

POST/api/v1/transcripts/export-batch

बैच एक्सपोर्ट (ZIP)

ID सूची या फ़िल्टर द्वारा कई ट्रांसक्रिप्ट एक साथ ZIP में एक्सपोर्ट करें। json/pdf के लिए Pro आवश्यक है।

ऑथ: API key या JWTReq: application/jsonRes: 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"}}'

बॉडी फ़ील्ड्स

`format` string	txt \| srt \| vtt \| csv \| json \| pdf। डिफ़ॉल्ट txt।
`ids` string[]	स्पष्ट ट्रांसक्रिप्ट IDs। फ़िल्टर उपयोग करने के लिए इसे छोड़ दें।
`filters` object	{ search?, status?, folderId?, orderBy?, view? }। केवल पूरे हो चुके ट्रांसक्रिप्ट एक्सपोर्ट किए जाते हैं।

सफल रिस्पॉन्स

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

एरर

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400INTERNAL_ERROR500

DELETE/api/v1/transcripts/{id}

ट्रांसक्रिप्ट हटाएँ

ट्रांसक्रिप्ट, उसके स्टोर किए गए एसेट्स और फ़ोल्डर लिंक को स्थायी रूप से डिलीट करें।

ऑथ: API key या JWTReq: noneRes: application/json

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

पैरामीटर

idआवश्यक

string · path

ट्रांसक्रिप्ट ID।

सफल रिस्पॉन्स

{
  "deleted": true
}

एरर

AUTH_REQUIRED401NOT_FOUND404INTERNAL_ERROR500

GET/api/v1/transcripts/stats

ट्रांसक्रिप्ट के आंकड़े

poll सीमा

आपके अकाउंट के लिए एग्रीगेट काउंट।

ऑथ: API key या JWTReq: noneRes: application/json

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

सफल रिस्पॉन्स

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

एरर

AUTH_REQUIRED401INTERNAL_ERROR500

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

सोर्स वीडियो डाउनलोड करें

Pro

मूल TikTok वीडियो को MP4 में डाउनलोड करें। केवल Pro के लिए, और आपके मासिक डाउनलोड कोटे में गिना जाता है।

ऑथ: API key या JWTReq: noneRes: 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 को अटैचमेंट के रूप में लौटाता है। कोटा केवल सफल स्ट्रीम पर खर्च होता है।

पैरामीटर

idआवश्यक

string · path

ट्रांसक्रिप्ट ID।

सफल रिस्पॉन्स

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

एरर

AUTH_REQUIRED401PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404VALIDATION_ERROR400

AI एजेंट

ट्रांसक्रिप्ट पर हुक एनालिसिस, स्क्रिप्ट रीराइट और वायरलिटी स्कोरिंग चलाएँ। (Pro)

POST/api/v1/agents/{agentType}

AI एजेंट चलाएँ

Proagent सीमा

किसी पूर्ण ट्रांसक्रिप्ट पर AI एनालिसिस की कतार में डालें। agentType इनमें से एक है: hooks, script_rewrite, virality_explain, hook_score.

ऑथ: API key या JWTReq: application/jsonRes: 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":{}}'

बॉडी फ़ील्ड्स

`transcript_id`आवश्यक string	विश्लेषण के लिए एक पूरा हुआ ट्रांसक्रिप्ट।
`input` object	वैकल्पिक एजेंट-विशिष्ट पैरामीटर।

पैरामीटर

agentTypeआवश्यक

string · path

hooks | script_rewrite | virality_explain | hook_score।

सफल रिस्पॉन्स · HTTP 202

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

एरर

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404RATE_LIMIT_EXCEEDED429

GET/api/v1/agents/runs

एजेंट रन की सूची

कर्सर पेजिनेशन के साथ, नवीनतम पहले, अपने एजेंट रन की सूची देखें।

ऑथ: API key या JWTReq: noneRes: 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"

पैरामीटर

`cursor` string (ISO date) · query	पीछे जाने के लिए next_cursor पास करें।
`limit` integer · query	पेज साइज़, 1–50। डिफ़ॉल्ट 20।

सफल रिस्पॉन्स

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

एरर

AUTH_REQUIRED401INTERNAL_ERROR500

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

एजेंट रन प्राप्त करें

एक एजेंट रन प्राप्त करें, पूरा होने पर उसका संरचित आउटपुट सहित।

ऑथ: API key या JWTReq: noneRes: 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"

पैरामीटर

runIdआवश्यक

string · path

एजेंट रन ID।

सफल रिस्पॉन्स

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

एरर

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404

निकालें और अनुवाद करें

निचले स्तर के प्रिमिटिव: मेटाडेटा स्क्रेप करें, टेक्स्ट का अनुवाद करें, और चिपकाए गए इनपुट को वर्गीकृत करें।

POST/api/v1/extract/metadata

मेटाडेटा स्क्रेप करें

बिना जॉब बनाए TikTok URL को उसकी मेटाडेटा और सबसे अच्छे उपलब्ध सबटाइटल ट्रैक में रिज़ॉल्व करें।

ऑथ: API key या JWTReq: application/jsonRes: 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"}'

बॉडी फ़ील्ड्स

`url`आवश्यक string	एक TikTok वीडियो URL।
`output_language` string	पसंदीदा सबटाइटल भाषा। डिफ़ॉल्ट en है।

सफल रिस्पॉन्स

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

एरर

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/extract/translate

टेक्स्ट का अनुवाद करें

ट्रांसक्रिप्ट के टेक्स्ट और/या टाइमिंग वाले सेगमेंट को एक या अधिक भाषाओं में अनुवाद करें।

ऑथ: API key या JWTReq: application/jsonRes: 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"}'

बॉडी फ़ील्ड्स

`full_text` string	अनुवाद के लिए टेक्स्ट। यह और/या segments दें।
`segments` TranscriptSegment[]	टाइमिंग सुरक्षित रखते हुए अनुवाद किए जाने वाले टाइमिंग वाले सेगमेंट।
`output_language` string	मुख्य लक्ष्य भाषा। डिफ़ॉल्ट en है।
`additional_languages` string[]	अतिरिक्त लक्ष्य भाषाएँ।

सफल रिस्पॉन्स

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

एरर

AUTH_REQUIRED401VALIDATION_ERROR400TRANSLATION_LIMIT_EXCEEDED429INTERNAL_ERROR500

POST/api/v1/workspace/resolve

पेस्ट किया गया इनपुट रिज़ॉल्व करें

चिपकाए गए टेक्स्ट / @handles / URLs को वीडियो URL, कलेक्शन प्रीव्यू या प्रोफ़ाइल प्रीव्यू में वर्गीकृत करें।

ऑथ: API key या JWTReq: application/jsonRes: 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"}'

बॉडी फ़ील्ड्स

`text` string	कच्चा पेस्ट किया गया इनपुट। यह या urls दें।
`urls` string[]	स्पष्ट URL सूची।

सफल रिस्पॉन्स

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

एरर

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

फ़ोल्डर

ट्रांसक्रिप्ट को फ़ोल्डरों में व्यवस्थित करें।

GET/api/v1/folders

फ़ोल्डरों की सूची

आइटम काउंट सहित अपने फ़ोल्डरों की सूची देखें।

ऑथ: API key या JWTReq: noneRes: application/json

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

सफल रिस्पॉन्स

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

एरर

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/folders

फ़ोल्डर बनाएँ

ट्रांसक्रिप्ट को समूहित करने के लिए एक फ़ोल्डर बनाएँ।

ऑथ: API key या JWTReq: application/jsonRes: 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"}'

बॉडी फ़ील्ड्स

nameआवश्यक

string

फ़ोल्डर का नाम।

सफल रिस्पॉन्स · HTTP 201

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

एरर

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

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

फ़ोल्डर में ट्रांसक्रिप्ट जोड़ें

किसी फ़ोल्डर में ट्रांसक्रिप्ट जोड़ें (idempotent)।

ऑथ: API key या JWTReq: application/jsonRes: 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"}'

बॉडी फ़ील्ड्स

transcript_idआवश्यक

string

जोड़ा जाने वाला ट्रांसक्रिप्ट।

पैरामीटर

folderIdआवश्यक

string · path

लक्ष्य फ़ोल्डर ID।

सफल रिस्पॉन्स · HTTP 201

{
  "added": true
}

एरर

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404INTERNAL_ERROR500

अकाउंट, Keys और बिलिंग

API keys प्रबंधित करें, प्लान और कोटा देखें, और फ़ीडबैक भेजें।

POST/api/v1/api-keys

API key बनाएँ

Pro

एक लाइव API key जनरेट करें। पूरी key एक बार दिखाई जाती है — इसे सुरक्षित रखें। केवल Pro के लिए।

ऑथ: API key या JWTReq: application/jsonRes: 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"}'

बॉडी फ़ील्ड्स

nameआवश्यक

string

की को पहचानने के लिए एक लेबल।

सफल रिस्पॉन्स · 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."
}

एरर

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/api-keys

API keys की सूची

Pro

अपनी सक्रिय keys उनके प्रीफ़िक्स द्वारा सूचीबद्ध करें (secret कभी वापस नहीं मिलता)। केवल Pro के लिए।

ऑथ: API key या JWTReq: noneRes: application/json

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

सफल रिस्पॉन्स

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

एरर

AUTH_REQUIRED401PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/plans

प्लान की सूची

सक्रिय प्लान और उनकी सीमाओं की सार्वजनिक सूची। किसी ऑथ की आवश्यकता नहीं।

ऑथ: सार्वजनिक (कोई ऑथ नहीं)Req: noneRes: application/json

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

सफल रिस्पॉन्स

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

एरर

INTERNAL_ERROR500

GET/api/v1/billing/subscription

सब्सक्रिप्शन और कोटा

आपका मौजूदा प्लान, सब्सक्रिप्शन स्थिति, और ट्रांसक्रिप्ट, एजेंट, डाउनलोड और अनुवाद में लाइव उपयोग/कोटा।

ऑथ: API key या JWTReq: noneRes: application/json

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

सफल रिस्पॉन्स

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

एरर

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/feedback

फ़ीडबैक सबमिट करें

प्रोडक्ट फ़ीडबैक, बग रिपोर्ट या फ़ीचर अनुरोध भेजें।

ऑथ: API key या JWTReq: application/jsonRes: 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!"}'

बॉडी फ़ील्ड्स

`category`आवश्यक string	bug \| feature \| improvement \| other।
`message`आवश्यक string	अधिकतम 2000 अक्षर।
`rating` integer \| null	वैकल्पिक 1–5 रेटिंग।

सफल रिस्पॉन्स

{
  "success": true
}

एरर

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

Loading API documentation…