API

API ریفرنس

اینڈ پوائنٹس، فیلڈز، جوابات، کریڈٹس، حدیں اور خرابیاں۔

اپ ڈیٹ ہوا 9 اکتوبر، 2026

یہ کیسے کام کرتا ہے#

ہر ٹرانسکرپٹ ایک کام کے ذریعے بنتا ہے۔ آپ ایک ماخذ جمع کراتے ہیں، کام پس منظر میں چلتا ہے، اور کامیاب ہونے پر وہ ایک ٹرانسکرپٹ کی طرف اشارہ کرتا ہے، جسے آپ جتنی بار چاہیں پڑھ یا ایکسپورٹ کر سکتے ہیں۔ بنیادی URL: https://www.transcriptdock.com۔ تمام درخواستیں اور جواب JSON میں ہوتے ہیں۔

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

API کو کبھی براؤزر سے کال نہ کریں: آپ کی کی ہر کسی کو نظر آ جائے گی۔ اسے اپنے سرور سے کال کریں اور کی کو ماحولیاتی متغیر (environment variable) میں رکھیں۔

توثیق#

API کیز صفحے پر کیز بنائیں۔ کی ایک بار دکھائی جاتی ہے، td_live_... جیسی نظر آتی ہے، اور ہر درخواست کے Authorization ہیڈر میں جاتی ہے۔ کیز کے ساتھ تخلیق کے وقت منتخب کیے گئے اسکوپس ہوتے ہیں: jobs:read، jobs:write، transcripts:read، uploads:write۔ ہر انضمام (integration) کے لیے الگ کی بنائیں تاکہ اسے تنہا منسوخ کر سکیں۔

ہیڈر

Authorization: Bearer td_live_YOUR_KEY

Idempotency-Key#

POST /v1/jobs، /v1/batches، /v1/jobs/{id}/retry، /v1/video-discoveries اور /v1/language-discoveries پر لازمی: 8 سے 128 قابلِ چھپائی ASCII حروف۔ 48 گھنٹوں کے اندر وہی کی اور وہی باڈی بھیجنے پر اصل آبجیکٹ واپس آتا ہے، اس لیے دوبارہ کی گئی درخواست کبھی دو بار نہ بنتی ہے اور نہ وصول ہوتی ہے۔ وہی کی مختلف باڈی کے ساتھ 409 IDEMPOTENCY_CONFLICT واپس کرتی ہے۔ اچھی کی وہ ہے جو آپ کے اپنے ID ہو اس چیز کے لیے جس کا آپ ٹرانسکرپشن کر رہے ہیں۔

X-Request-Id#

ہر جواب میں ایک ہوتا ہے۔ سپورٹ سے رابطہ کرتے وقت اسے حوالے کے طور پر لکھیں۔

اینڈ پوائنٹس#

طریقہ	راستہ	کیا کرتا ہے	کریڈٹس
POST	`/v1/jobs`	ایک ویڈیو، فائل یا لنک کا ٹرانسکرپشن	کیپشن ٹرانسکرپٹ کا 1، AI ٹرانسکرپشن کے ہر منٹ کے 2
GET	`/v1/jobs/{id}`	کام کا اسٹیٹس، زیادہ سے زیادہ 25 سیکنڈ انتظار	مفت
GET	`/v1/jobs`	کاموں کی تاریخ	مفت
POST	`/v1/jobs/{id}/cancel`	قطار میں لگے کام کو منسوخ کریں	مفت
POST	`/v1/jobs/{id}/retry`	ناکام کام کو دوبارہ چلائیں	نئے کام کے طور پر
POST	`/v1/batches`	کئی ویڈیوز کا ٹرانسکرپشن (پلان کے بیچ سائز کے مطابق)	ہر آئٹم کے حساب سے، اوپر کے مطابق
GET	`/v1/batches/{id}`	بیچ کا اسٹیٹس	مفت
GET	`/v1/transcripts/{id}`	ٹرانسکرپٹ JSON	مفت
GET	`/v1/transcripts/{id}/export`	txt، srt، vtt یا json فائل	مفت
DELETE	`/v1/transcripts/{id}`	ٹرانسکرپٹ حذف کریں	مفت
POST	`/v1/uploads`	فائل اپلوڈ کرنے کے لیے URL حاصل کریں	مفت
POST	`/v1/uploads/{id}/complete`	اپلوڈ کے مکمل ہونے کا نشان لگائیں	مفت
POST	`/v1/video-discoveries`	YouTube پر تلاش کریں، چینل، پلے لسٹ یا TikTok پروفائل کی فہرست بنائیں	ہر صفحے کا 1
GET	`/v1/video-discoveries/{id}`	دریافت کا نتیجہ	مفت
POST	`/v1/language-discoveries`	YouTube ویڈیو کی کیپشن زبانوں کی فہرست بنائیں	1
GET	`/v1/language-discoveries/{id}`	زبانوں کی فہرست	مفت
POST	`/v1/webhook-endpoints`	ویب ہک URL رجسٹر کریں (سائن اِن سیشن میں)	مفت
GET	`/v1/webhook-endpoints`	ویب ہک URLs کی فہرست	مفت
DELETE	`/v1/webhook-endpoints/{id}`	ویب ہک URL غیر فعال کریں (سائن اِن سیشن میں)	مفت
GET	`/v1/usage`	کریڈٹس اور پلان	مفت
GET	`/v1/capabilities`	آپ کی کی کیا کر سکتی ہے	مفت

کام بنائیں#

POST/v1/jobs

source.urlstringاختیاری: ایک عوامی ویڈیو: YouTube (watch?v=، youtu.be، shorts، live) یا TikTok (tiktok.com/@user/video/…، vm.tiktok.com شیئر لنکس)۔ کسی آڈیو یا ویڈیو فائل کا کوئی بھی دوسرا https لنک براہِ راست میڈیا لنک سمجھا جاتا ہے (AI ٹرانسکرپشن)۔url یا upload_id میں سے ایک لازمی ہے۔
source.upload_iduuidاختیاری: آپ کی اپلوڈ کی ہوئی فائل (دیکھیں اپلوڈز)۔ ہمیشہ AI ٹرانسکرپشن۔
mode"captions_only" | "auto" | "transcribe"لازمی: captions_only: ویڈیو کے اپنے کیپشن، 1 کریڈٹ؛ اگر کیپشن نہ ہوں تو NO_CAPTIONS کے ساتھ ناکام ہوتا ہے۔ auto: کیپشن موجود ہوں تو وہ (1 کریڈٹ)، ورنہ AI ٹرانسکرپشن۔ transcribe: ہمیشہ آڈیو کا AI ٹرانسکرپشن، شروع ہونے والے ہر منٹ کے 2 کریڈٹس، ہر لفظ کا وقت۔ AI ٹرانسکرپشن کے لیے پیڈ پلان درکار ہے۔
caption_languagesstring[]اختیاری: ترجیحی کیپشن زبانیں ترتیب کے ساتھ، مثلاً ["en", "es"]، زیادہ سے زیادہ 5۔ ڈیفالٹ: ویڈیو کا ڈیفالٹ ٹریک۔ صرف captions_only اور auto کے لیے۔
caption_preference"prefer_creator" | "creator_only" | "automatic_only"اختیاری: آیا تخلیق کار کے اپلوڈ کیے ہوئے کیپشن قبول کیے جائیں، YouTube کے خودکار کیپشن، یا دونوں (ڈیفالٹ prefer_creator: پہلے تخلیق کار)۔
languagestringاختیاری: AI ٹرانسکرپشن کے لیے بولی جانے والی زبان کا اشارہ (BCP 47)۔ ڈیفالٹ: خود پہچاننا۔
max_creditsintegerاختیاری: AI ٹرانسکرپشن کی خرچ کی حد۔ پہلے میڈیا کی پیمائش ہوتی ہے؛ اگر لاگت اس سے زیادہ ہو تو کام BUDGET_EXCEEDED کے ساتھ ناکام ہوتا ہے اور کوئی کریڈٹ وصول نہیں ہوتا۔ ڈیفالٹ: 2 گھنٹے کے لیے کافی۔
webhook_endpoint_iduuidاختیاری: job.succeeded / job.failed اس ویب ہک پر وصول کریں۔
metadataobjectاختیاری: زیادہ سے زیادہ 10 متنی قدریں (کیز ≤ 64، قدریں ≤ 256 حروف)۔ ویب ہک ایونٹس میں واپس بھیجی جاتی ہیں۔ کیشنگ پر اثر نہیں ڈالتیں۔

202 کے ساتھ کام واپس کرتا ہے۔ اگر آپ کے ورک اسپیس میں اسی ویڈیو اور انہی آپشنز کا ٹرانسکرپٹ پہلے سے موجود ہو تو 200 کے ساتھ ایک کامیاب کام مفت واپس آتا ہے (billing.kind: "cached")۔

202 جواب

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

کام کا آبجیکٹ#

iduuidاختیاری: کام کی ID۔
statusstringاختیاری: queued → processing (AI ٹرانسکرپشن کے دوران → awaiting_provider) → succeeded، failed یا cancelled۔ آخری تین حتمی ہیں۔
stagestring | nullاختیاری: چلتا ہوا کام کس مرحلے میں ہے: resolve، captions، acquire_audio، submit_asr، wait_asr، finalize۔ صرف معلوماتی۔
result_iduuid | nullاختیاری: کامیاب ہونے پر ٹرانسکرپٹ۔
errorobject | nullاختیاری: ناکامی پر: code، message، retryable، اور اختیاری details.detail۔ وہی کوڈ جو خرابیوں میں ہیں۔
billingobjectاختیاری: credits_reserved (چلنے کے دوران ہولڈ، ختم ہونے پر 0)، credits_charged (حتمی)، kind: captions، ai_transcription یا cached۔
sourceobjectاختیاری: platform، media_id، canonical_url، title، upload_id۔
optionsobjectاختیاری: mode، language، caption_preference جیسے قبول کیے گئے۔
created_atdate-timeاختیاری: UTC۔

کام حاصل کریں#

GET/v1/jobs/{id}?wait=25

کام واپس کرتا ہے۔ wait (0 سے 25 سیکنڈ) کے ساتھ درخواست کھلی رہتی ہے اور کام حتمی ہوتے ہی جواب دیتی ہے، اس لیے ایک کال بار بار پوچھنے والے لوپ کی جگہ لے لیتی ہے۔ ریڈز کی اپنی حد ہے: فی منٹ 120۔

کاموں کی فہرست#

GET/v1/jobs?limit=20&cursor=

تازہ ترین پہلے، limit 1 سے 100۔ اگلے صفحے کے لیے جواب کا next_cursor بطور cursor واپس بھیجیں۔ platform اور source_id (کسی کام کا source.media_id) ایک ساتھ شامل کریں تاکہ کسی ایک ویڈیو کے کام دکھائی دیں، کسی بھی موڈ میں۔ کلائنٹ دوبارہ جمع کرانے سے پہلے اسی طرح چیک کرتا ہے کہ ورک اسپیس کے پاس اس ویڈیو کا ٹرانسکرپٹ پہلے سے موجود ہے یا نہیں۔

کام منسوخ کریں#

POST/v1/jobs/{id}/cancel

صرف وہ کام منسوخ ہوتا ہے جس کی AI ٹرانسکرپشن ابھی شروع نہ ہوئی ہو؛ ہولڈ ختم ہو جاتا ہے۔ اس کے بعد 409 CANCELLATION_NOT_ALLOWED واپس آتا ہے اور کام مکمل ہو جاتا ہے۔

کام دوبارہ چلائیں#

POST/v1/jobs/{id}/retry

ناکام کام سے، جس کی خرابی retryable تھی، ایک نیا کام بنایا جاتا ہے۔ اس کے لیے نئی Idempotency-Key درکار ہے؛ اختیاری باڈی { "max_credits": 40 }۔ قیمت نئے کام جیسی ہوتی ہے۔ حتمی ناکامیاں (نجی ویڈیو، کیپشن نہ ہونا) 409 JOB_NOT_RETRYABLE واپس کرتی ہیں: ان پٹ درست کریں اور دوبارہ جمع کرائیں۔

ٹرانسکرپٹ#

GET/v1/transcripts/{id}

iduuidاختیاری: کام کے result_id جیسا ہی۔
sourceobjectاختیاری: platform، media_id، canonical_url، title۔
source_originstringاختیاری: creator_captions، platform_captions (پلیٹ فارم کے بنائے ہوئے کیپشن، جیسے YouTube کے خودکار کیپشن) یا speech_recognition (AI ٹرانسکرپشن)۔
languagestring | nullاختیاری: متن کا BCP 47 ٹیگ۔
textstringاختیاری: پورا ٹرانسکرپٹ سادہ متن میں۔
segmentsarrayاختیاری: کیپشن کے سائز کے حصے: { start, end, text } سیکنڈوں میں۔
wordsarray | nullاختیاری: ہر لفظ کے لیے { start, end, text, confidence }۔ صرف AI ٹرانسکرپشن۔
timing_granularity"word" | "segment" | "none"اختیاری: دستیاب سب سے باریک وقت۔
duration_secondsnumber | nullاختیاری: میڈیا کی لمبائی۔
extraction_versionstringاختیاری: اس نتیجے کو بنانے والی پائپ لائن کا ورژن۔
recognitionobject | nullاختیاری: صرف AI ٹرانسکرپشن: model، profile، quality_status (validated_language: ہم نے اس کا معیار جانچا ہے؛ provider_supported: ماڈل اسے درج کرتا ہے؛ experimental_language: معیار مختلف ہو سکتا ہے)۔
created_atdate-timeاختیاری: UTC۔

200 جواب

{
  "id": "22222222-2222-4222-8222-222222222222",
  "source": { "platform": "youtube", "media_id": "dQw4w9WgXcQ", "canonical_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "title": "مثال کی ویڈیو" },
  "source_origin": "creator_captions",
  "language": "ur",
  "text": "یہ ایک مثال ہے۔ اس میں دو لائنیں ہیں۔",
  "segments": [
    { "start": 0, "end": 2.4, "text": "یہ ایک مثال ہے" },
    { "start": 2.4, "end": 4.9, "text": "اس میں دو لائنیں ہیں" }
  ],
  "words": null,
  "timing_granularity": "segment",
  "duration_seconds": 212.0,
  "recognition": null,
  "extraction_version": "worker-0.1.0",
  "created_at": "2026-09-16T10:00:14.000Z"
}

ٹرانسکرپٹ آپ کے پلان کی محفوظ رکھنے کی مدت تک رکھے جاتے ہیں (ٹرائل پر 7 دن، Starter پر 30، Pro اور Scale پر 90)۔ DELETE /v1/transcripts/{id} کسی ٹرانسکرپٹ کو پہلے بھی ہٹا سکتا ہے۔

ٹرانسکرپٹ ایکسپورٹ کریں#

GET/v1/transcripts/{id}/export?format=srt

format	آپ کو ملتا ہے
txt	سادہ متن، ہر لائن میں ایک حصہ۔
srt	SubRip سب ٹائٹلز۔
vtt	WebVTT سب ٹائٹلز۔
json	اوپر والا ٹرانسکرپٹ آبجیکٹ۔

مفت، بلا حد۔ srt اور vtt کو وقت درکار ہے؛ جس ٹرانسکرپٹ میں وقت نہ ہو وہ 422 TIMESTAMPS_UNAVAILABLE واپس کرتا ہے۔

بیچز#

POST/v1/batches

ایک درخواست، کئی ویڈیوز۔ ہر آئٹم کے وہی فیلڈز ہیں جو کام بنائیں میں ہیں؛ پورا بیچ ایک ساتھ قبول یا مسترد ہوتا ہے۔ فی بیچ آئٹمز: ٹرائل پر 1، Starter پر 10، Pro پر 25، Scale پر 50۔

itemsJobRequest[]لازمی: 1 سے 50 کام کی درخواستیں۔
webhook_endpoint_iduuidاختیاری: ہر آئٹم حتمی ہونے پر ایک batch.completed وصول کرتا ہے۔
metadataobjectاختیاری: batch.completed ایونٹ میں واپس بھیجا جاتا ہے۔

POST /v1/batches

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

بیچ آبجیکٹ میں status (queued، processing، succeeded، partial_success، failed، cancelled)، گنتیاں (total_items، succeeded_items، failed_items، cancelled_items) اور items ہوتے ہیں، ہر ایک کے ساتھ اس کا job_id۔ اسے GET /v1/batches/{id} سے پڑھیں؛ ہر آئٹم ایک عام کام ہے۔

اپلوڈز#

آپ کی اپنی آڈیو یا ویڈیو (mp3، wav، m4a، ogg، aac، mp4، webm؛ 250 MB اور 2 گھنٹے تک)۔ ایک اپلوڈ کی جگہ مختص کریں، فائل کو سائن شدہ URL پر PUT کریں، اسے مکمل نشان زد کریں، پھر source.upload_id کے ساتھ بطور کام جمع کرائیں۔ اپلوڈز ہمیشہ AI ٹرانسکرپشن استعمال کرتے ہیں۔

اپلوڈ اور ٹرانسکرائب

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

filenamestringلازمی: 255 حروف تک۔
content_typestringلازمی: فائل کا MIME ٹائپ، مثلاً audio/mpeg یا video/mp4۔ PUT پر وہی قدر بھیجیں۔
bytesintegerلازمی: فائل کا درست سائز۔ PUT کا سائز اس سے مطابقت رکھنا چاہیے۔

سائن شدہ URL 24 گھنٹے تک کارآمد ہے؛ اس کے بعد نئی جگہ مختص کریں۔

ویب ہکس#

POST/v1/webhook-endpoints

ایک https URL رجسٹر کریں اور جمع کراتے وقت اس کی id کو webhook_endpoint_id کے طور پر دیں۔ کام یا بیچ ختم ہونے پر ہم ایک ایونٹ POST کرتے ہیں۔ جواب میں دستخط کرنے والا secret ایک بار شامل ہوتا ہے۔ اینڈ پوائنٹس رجسٹر کرنے اور غیر فعال کرنے کے لیے سائن اِن سیشن درکار ہے، اس لیے یہ کام ڈیش بورڈ کے ویب ہکس صفحے پر کریں؛ وہاں API کی کو 403 FORBIDDEN ملتا ہے مگر وہ اینڈ پوائنٹس کی فہرست دیکھ سکتی ہے۔

urlstringلازمی: https URL، 2048 حروف تک۔
descriptionstringاختیاری: آپ کے اپنے حوالے کے لیے ایک لیبل۔

ایونٹس#

job.succeeded

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

job.succeeded: result_id حاصل کریں یا ایکسپورٹ کریں۔
job.failed: error میں کوڈ ہوتا ہے۔
batch.completed: ہر آئٹم حتمی ہے؛ آئٹم کے مطابق نتائج کے لیے بیچ پڑھیں۔

چند سیکنڈ میں کوئی بھی 2xx جواب دیں۔ ناکام ڈیلیوریز وقفے وقفے سے دوبارہ کی جاتی ہیں اور ڈیش بورڈ سے دوبارہ بھیجی جا سکتی ہیں۔ ایک ایونٹ ایک سے زیادہ بار بھی پہنچ سکتا ہے: event_id سے ڈپلیکیٹ ختم کریں۔

دستخط کی تصدیق کریں#

ہیڈرز X-TranscriptDock-Event-Id، X-TranscriptDock-Timestamp اور X-TranscriptDock-Signature۔ دستخط آپ کے secret کے ساتھ {event_id}.{timestamp}.{raw_body} کا HMAC-SHA256 (hex) ہے۔ پانچ منٹ سے پرانی ہر چیز رد کریں۔

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

ویڈیوز تلاش کریں#

POST/v1/video-discoveries

YouTube پر تلاش کریں یا کوئی چینل، پلے لسٹ یا TikTok پروفائل کی فہرست بنائیں، پھر URLs کو کاموں میں ڈالیں۔ دریافت کام کی طرح پس منظر میں چلتی ہے: status succeeded ہونے تک GET /v1/video-discoveries/{id} سے پڑھیں۔ ہر صفحے کا 1 کریڈٹ؛ نتائج 24 گھنٹے تک محفوظ رہتے ہیں۔

kindstringلازمی: youtube_search، youtube_channel_videos، youtube_channel_search، youtube_playlist_videos یا tiktok_user_videos۔
querystringاختیاری: تلاش کا متن (youtube_search، youtube_channel_search)۔
channelstringاختیاری: @handle، چینل ID یا چینل URL (چینل کی اقسام کے لیے)۔
playliststringاختیاری: پلے لسٹ ID یا URL (youtube_playlist_videos)۔
userstringاختیاری: @user یا پروفائل URL (tiktok_user_videos)۔
limitintegerاختیاری: فی صفحہ ویڈیوز، 1 سے 50، ڈیفالٹ 20۔ TikTok: زیادہ سے زیادہ 10۔
cursorstringاختیاری: پچھلے صفحے کا next_cursor۔ صرف YouTube۔
include_detailsbooleanاختیاری: صرف TikTok: ہر ویڈیو کے لائکس، تبصرے، ہیش ٹیگز اور کیپشن کی زبانیں بھی حاصل کریں۔

YouTube پر تلاش

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

POST 202 کے ساتھ status: "queued" واپس کرتا ہے۔ مکمل ہونے کے بعد GET /v1/video-discoveries/{id} کچھ یوں دکھتا ہے:

200 جواب

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

ویڈیو کی کیپشن زبانیں#

POST/v1/language-discoveries

باڈی { "source": { "url": "https://www.youtube.com/watch?v=..." } } کے ساتھ اور ایک Idempotency-Key (صرف YouTube، 1 کریڈٹ)۔ کیپشن ٹریکس کی فہرست، ان کے کوڈز، اور یہ کہ وہ تخلیق کار کے ہیں یا خودکار، اور ڈیفالٹ کون سا ہے، جاننے کے لیے GET /v1/language-discoveries/{id} پڑھیں۔ کوڈز کو caption_languages میں استعمال کریں۔

استعمال اور صلاحیتیں#

GET/v1/usage

200 جواب

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

credits_remaining میں پہلے ہی credits_reserved شامل نہیں ہوتے (چلنے والے کاموں کے ہولڈ)۔ prepaid_credits خریدے ہوئے کریڈٹس ہیں، جن کی میعاد ختم نہیں ہوتی۔

subscription پیڈ پلان کے پیچھے موجود Stripe سبسکرپشن ہے، اور اس کے بغیر null ہوتا ہے: اس کا status، بلنگ کا interval (monthly یا yearly)، cancel_at_period_end، اور current_period_end جب پلان رینیو ہوگا یا ختم ہوگا۔ period_end وہ وقت ہے جب ماہانہ کریڈٹس ریفریش ہوتے ہیں، سالانہ پلانز پر بھی ہر مہینے۔

GET/v1/capabilities

آپ کی کی ابھی کیا کر سکتی ہے: ہر ماخذ (youtube، tiktok، instagram، upload، direct) کے لیے کون سے موڈ دستیاب ہیں، ساتھ میں حدیں اور قیمتیں۔ کوڈ میں قدریں لکھنے کے بجائے یہی پڑھیں؛ مثلاً ٹرائل auto اور transcribe کو false دکھاتا ہے۔

200 جواب

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

ریٹ لمٹس#

پلان	جمع / منٹ	جاری کام	ریڈز / منٹ
ٹرائل	10	10	120
Starter	60	100	120
Pro	120	500	120
Scale	300	2,000	120

حد سے تجاوز کرنے پر 429 RATE_LIMITED ملتا ہے، جس کے ساتھ retry-after ہیڈر (سیکنڈ میں) اور details.detail میں حد کا نام ہوتا ہے۔ کوئی کریڈٹ وصول نہیں ہوتا۔ ویب ہکس اور ?wait=25 آپ کو ریڈ کی حد سے کافی دور رکھتے ہیں۔

خرابیاں#

ہر خرابی کی ساخت ایک جیسی ہے۔ retryable: true کا مطلب ہے کہ وہی درخواست بعد میں کامیاب ہو سکتی ہے: اگر retry-after موجود ہو تو اتنے سیکنڈ انتظار کریں، ورنہ چند سیکنڈ رکیں، اور وہی Idempotency-Key دوبارہ استعمال کریں تاکہ کچھ دو بار نہ ہو۔ باقی ہر خرابی کے لیے آپ کی طرف سے تبدیلی درکار ہے۔

402 جواب

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

جو کام قبول ہونے کے بعد ناکام ہو، وہ GET /v1/jobs/{id} پر اب بھی 200 ہے، جس میں status: "failed" اور error میں وہی خرابی کا آبجیکٹ ہوتا ہے۔ ناکام کام کا کوئی کریڈٹ وصول نہیں ہوتا۔

کوڈز#

کوڈ	HTTP	دوبارہ کوشش	مطلب اور کیا کرنا ہے
`INVALID_REQUEST`	422	نہیں	کوئی فیلڈ غائب ہے یا اس کی ساخت غلط ہے۔ details.detail اس کا نام بتاتا ہے۔
`INVALID_URL`	422	نہیں	URL درست https لنک نہیں ہے (زیادہ سے زیادہ 2048 حروف)۔
`UNSUPPORTED_SOURCE`	422	نہیں	یہ لنک YouTube یا TikTok ویڈیو کا URL نہیں ہے۔
`UNSAFE_URL`	422	نہیں	براہِ راست میڈیا لنک کسی نجی یا مسدود نیٹ ورک ایڈریس کی طرف اشارہ کرتا ہے۔
`INVALID_CURSOR`	422	نہیں	ویڈیو دریافت کا کرسر ختم ہو گیا ہے یا اس کی ساخت خراب ہے۔ پہلے صفحے سے دوبارہ شروع کریں۔ کاموں کی فہرست کا خراب کرسر INVALID_REQUEST واپس کرتا ہے۔
`CAPABILITY_UNAVAILABLE`	422	نہیں	یہ موڈ اس ماخذ کے لیے دستیاب نہیں ہے۔ GET /v1/capabilities بتاتا ہے کہ کیا دستیاب ہے۔
`IDEMPOTENCY_CONFLICT`	409	نہیں	یہ Idempotency-Key پہلے ایک مختلف باڈی کے ساتھ استعمال ہو چکی ہے۔ نئی کی استعمال کریں۔
`UNAUTHENTICATED`	401	نہیں	Authorization ہیڈر میں کوئی درست API کی یا OAuth ٹوکن نہیں ہے۔
`FORBIDDEN`	403	نہیں	کی کے پاس اس اینڈ پوائنٹ کا اسکوپ نہیں ہے، یا ورک اسپیس غیر فعال ہے۔
`EMAIL_UNVERIFIED`	403	نہیں	API استعمال کرنے سے پہلے اکاؤنٹ کی ای میل کی تصدیق کریں۔
`NOT_FOUND`	404	نہیں	اس ورک اسپیس میں ایسی کوئی چیز موجود نہیں۔
`INSUFFICIENT_BALANCE`	402	نہیں	اس کام کے لیے کافی کریڈٹس نہیں ہیں۔ کریڈٹس خریدیں یا اپ گریڈ کریں۔
`PLAN_REQUIRED`	402	نہیں	اس کے لیے پیڈ پلان درکار ہے (AI ٹرانسکرپشن، بڑے بیچز) یا ٹرائل کے کریڈٹس ختم ہو چکے ہیں۔
`BUDGET_EXCEEDED`	402	نہیں	ناپی گئی لاگت max_credits سے زیادہ ہے۔ کوئی کریڈٹ وصول نہیں ہوا؛ حد بڑھائیں یا یہ میڈیا چھوڑ دیں۔
`JOB_NOT_RETRYABLE`	409	نہیں	ناکامی حتمی تھی (نجی ویڈیو، کیپشن نہیں)۔ ان پٹ درست کریں اور نیا کام جمع کرائیں۔
`CANCELLATION_NOT_ALLOWED`	409	نہیں	AI ٹرانسکرپشن پہلے ہی شروع ہو چکی ہے؛ کام مکمل ہو جائے گا۔
`RATE_LIMITED`	429	ہاں	ریٹ یا قطار کی حد سے تجاوز ہو گیا۔ retry-after سیکنڈ انتظار کریں؛ details.detail بتاتا ہے کہ کون سی حد لاگو ہوئی۔
`SOURCE_NOT_FOUND`	422	نہیں	ویڈیو موجود نہیں ہے یا ہٹا دی گئی ہے۔
`SOURCE_PRIVATE`	422	نہیں	ویڈیو نجی ہے۔ صرف عوامی ویڈیوز کام کرتی ہیں۔
`SOURCE_AUTH_REQUIRED`	422	نہیں	ویڈیو کے لیے لاگ اِن، عمر کی تصدیق یا ممبرشپ درکار ہے۔
`SOURCE_REGION_RESTRICTED`	422	نہیں	ویڈیو ان علاقوں میں مسدود ہے جہاں سے ہم اسے حاصل کرتے ہیں۔
`NO_CAPTIONS`	422	نہیں	اس ویڈیو پر کیپشن نہیں ہیں اور موڈ captions_only تھا۔ auto یا transcribe استعمال کریں۔
`LANGUAGE_UNAVAILABLE`	422	نہیں	caption_languages میں سے کوئی بھی زبان اس ویڈیو پر موجود نہیں۔ ڈیفالٹ ٹریک لینے کے لیے فہرست ہٹا دیں۔
`LANGUAGE_UNSUPPORTED`	422	نہیں	AI ٹرانسکرپشن مطلوبہ زبان کو سپورٹ نہیں کرتی۔
`NO_SPEECH`	422	نہیں	AI ٹرانسکرپشن کو آڈیو میں کوئی بولی نہیں ملی۔
`NO_AUDIO`	422	نہیں	میڈیا میں کوئی آڈیو ٹریک نہیں ہے۔
`INVALID_MEDIA`	422	نہیں	فائل کو آڈیو یا ویڈیو کے طور پر نہیں پڑھا جا سکا۔
`UNSUPPORTED_MEDIA`	422	نہیں	یہ آڈیو یا ویڈیو فائل کی قسم نہیں ہے۔
`DURATION_LIMIT_EXCEEDED`	413	نہیں	2 گھنٹے سے زیادہ۔
`FILE_TOO_LARGE`	413	نہیں	250 MB سے بڑی۔
`TIMESTAMPS_UNAVAILABLE`	422	نہیں	اس ٹرانسکرپٹ میں وقت نہیں ہے، اس لیے srt اور vtt ایکسپورٹ دستیاب نہیں۔ txt یا json استعمال کریں۔
`PROVIDER_REJECTED`	422	نہیں	AI ٹرانسکرپشن ماڈل اس آڈیو کو پروسیس نہیں کر سکا۔
`SOURCE_RATE_LIMITED`	503	ہاں	ماخذ کا پلیٹ فارم ہماری رفتار محدود کر رہا ہے۔ کام خود بخود دوبارہ کوشش کرتا ہے۔
`SOURCE_BLOCKED`	503	ہاں	ماخذ کے پلیٹ فارم نے حاصل کرنے کی کوشش مسدود کر دی۔ کام خود بخود دوبارہ کوشش کرتا ہے۔
`SOURCE_TIMEOUT`	503	ہاں	ماخذ کے پلیٹ فارم کا وقت ختم ہو گیا۔ کام خود بخود دوبارہ کوشش کرتا ہے۔
`SOURCE_CHANGED`	503	ہاں	ہمارے پڑھنے کے دوران ماخذ بدل گیا۔ کام خود بخود دوبارہ کوشش کرتا ہے۔
`PROVIDER_UNAVAILABLE`	503	ہاں	AI ٹرانسکرپشن عارضی طور پر دستیاب نہیں ہے۔ کام خود بخود دوبارہ کوشش کرتا ہے۔
`STORAGE_UNAVAILABLE`	503	ہاں	فائل اسٹوریج عارضی طور پر دستیاب نہیں ہے۔ درخواست دوبارہ بھیجیں۔
`INTERNAL_ERROR`	500	ہاں	یہ ہماری طرف کی خرابی ہے۔ وہی Idempotency-Key کے ساتھ دوبارہ کوشش کریں؛ اگر مسئلہ برقرار رہے تو X-Request-Id حوالے کے طور پر لکھیں۔

سائٹ مینو

دستاویزات

API ریفرنس

یہ کیسے کام کرتا ہے#

توثیق#

Idempotency-Key#

X-Request-Id#

اینڈ پوائنٹس#

کام بنائیں#

کام کا آبجیکٹ#

کام حاصل کریں#

کاموں کی فہرست#

کام منسوخ کریں#

کام دوبارہ چلائیں#

ٹرانسکرپٹ#

ٹرانسکرپٹ ایکسپورٹ کریں#

بیچز#

اپلوڈز#

ویب ہکس#

ایونٹس#

دستخط کی تصدیق کریں#

ویڈیوز تلاش کریں#

ویڈیو کی کیپشن زبانیں#

استعمال اور صلاحیتیں#

ریٹ لمٹس#

خرابیاں#

کوڈز#