توثيق المطوّرين

وثائق واجهة برمجة تطبيقات TokCaption

واجهة REST API لتفريغ نصوص فيديوهات TikTok العامة، وتشغيل تحليل الافتتاحيات الجاذبة بالذكاء الاصطناعي، وإعادة كتابة السيناريوهات، وتصدير التفريغ النصي بكميات كبيرة. صادِق باستخدام مفتاح API، وأرسل الرابط، ثم استعلم عن النتيجة. تتوفر إمكانية الوصول إلى API في خطة Pro.

REST API · v2.1.0

TokCaption API

فرّغ نصوص فيديوهات TikTok العامة، وشغّل تحليل الافتتاحيات الجاذبة بالذكاء الاصطناعي، وصدّر النتائج بكميات كبيرة — كل ذلك عبر واجهة REST API نظيفة بصيغة JSON. صادِق باستخدام مفتاح API وابدأ خلال استدعاءين. تفضّل مساعدي الذكاء الاصطناعي؟ الأدوات نفسها متاحة كـخادم MCP لـ Claude وChatGPT.

عنوان URL الأساسي

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

المصادقة

X-API-Key

نقاط النهاية

27 عبر 6 مجموعة

المصادقة

أنشئ مفتاح API من الإعدادات ← مفاتيح API (خطة Pro). أرسله مع كل طلب عبر الترويسة X-API-Key. يمكن لتطبيقات لوحة التحكم والهاتف بدلاً من ذلك إرسال رمز Supabase JWT كـ Authorization: Bearer <jwt>. احتفظ بالمفاتيح على الخادم، ولا تضمّنها أبداً في حزمة المتصفح.

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

البدء السريع

أرسل رابطاً ثم استعلم عن المهمة حتى تكتمل. غالباً ما يكتمل الرابط الواحد مباشرةً، فتحقّق من حالة الاستجابة قبل الاستعلام.

الخطوة 1 — الإرسال

أرسل طلب POST /api/v1/jobs مع عناوين URL الخاصة بك. واحفظ قيمة job_id التي يتم إرجاعها.

الخطوة 2 — الاستعلام

أرسل طلبات GET /api/v1/jobs/{jobId} كل 1–2 ثانية حتى تصبح الحالة نهائية، ثم اقرأ items[].transcript_text.

تريد رابطاً واحداً فقط ولا ترغب في الاستعلام المتكرر؟ استخدم 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	عدد كبير جداً من طلبات الإرسال أو الاستعلام أو الوكلاء خلال فترة قصيرة. التزم بقيمة الترويسة 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 العامة للتفريغ النصي وتابع تقدم المهام.

POST/api/v1/jobs

إرسال مهمة التفريغ النصي

حدّ submit

أرسل من 1 إلى N من روابط TikTok العامة للتفريغ النصي. يحدد حجم الدفعة وفق خطتك؛ وقد يعيد الرابط الواحد النتيجة النهائية مباشرةً ضمن الاستجابة.

المصادقة: مفتاح API أو رمز JWTالطلب: application/jsonالاستجابة: 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"}'

قد يُرجع الرابط الواحد الاستجابة HTTP 200 مع حمولة نهائية بحالة completed أو failed عند اكتمال المعالجة بشكل مباشر.
تُرجع الدفعات الاستجابة HTTP 202 مع job_id وحالة إجمالية وحالات لكل عنصر داخل items.
افحص مصفوفة العناصر لمعرفة حالة كل فيديو: في الانتظار، أو قيد المعالجة، أو مكتمل، أو فاشل.
تعيين include_download_assets: true في الخطة المجانية يُرجع PLAN_REQUIRED (403).

حقول نص الطلب

`urls`مطلوب string[]	روابط فيديوهات TikTok. حدّ الدفعة في الخطة المجانية هو 5.
`output_language` string	لغة التفريغ النصي المستهدفة (رمز ISO). القيمة الافتراضية en.
`also_translate_to` string[]	لغات إضافية لترجمة التفريغ النصي إليها.
`allow_asr_fallback` boolean	نسخ الصوت صوتياً عندما لا يوجد مسار تسميات توضيحية. القيمة الافتراضية false.
`include_download_assets` boolean	احفظ ملفات الفيديو والغلاف للتنزيل. متاح لخطة Pro فقط.
`idempotency_key` string	مفتاح لمنع التكرار؛ إعادة استخدامه تُرجع المهمة الأصلية.

استجابة النجاح · 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 أو رمز JWTالطلب: noneالاستجابة: 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	التصفية حسب حالة المهمة (مثل: مكتملة، قيد المعالجة، فاشلة).

استجابة النجاح

{
  "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 أو رمز JWTالطلب: noneالاستجابة: 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.

استجابة النجاح

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

إلغاء مهمة

ألغِ العناصر المنتظرة أو قيد المعالجة في مهمة. تُعيد العناصر الملغاة حصتها.

المصادقة: مفتاح API أو رمز JWTالطلب: noneالاستجابة: 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

معرّف المهمة المراد إلغاؤها.

استجابة النجاح

{
  "cancelled_count": 3
}

الأخطاء

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

GET/api/v1/quick

تفريغ سريع (رابط واحد)

حدّ submit

أرسل رابطاً واحداً وانتظر (حتى نحو 55 ثانية) للحصول على نتيجة نهائية. وهو اختصار متزامن لواجهة المهام.

المصادقة: مفتاح API أو رمز JWTالطلب: noneالاستجابة: 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"

يُرجع HTTP 200 عند الوصول إلى حالة نهائية (completed/failed)، أو HTTP 202 إذا كانت المعالجة ما زالت جارية عند انتهاء فترة الانتظار، وعندها استعلم عن /api/v1/jobs/{jobId}.

المعلمات

urlمطلوب

string · query

رابط فيديو TikTok واحد.

استجابة النجاح

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

استيراد جماعي

Proحدّ submit

أرسل قائمة روابط أو نصاً خاماً يحتوي على روابط. تقبل الخطة المجانية رابطاً واحداً، بينما يتطلب الاستيراد الجماعي خطة Pro.

المصادقة: مفتاح API أو رمز JWTالطلب: application/jsonالاستجابة: 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 أو رمز JWTالطلب: noneالاستجابة: 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

جلب تفريغ نصي واحد حسب المعرّف، مع النص الكامل والمقاطع والترجمات والبيانات الوصفية والأصول.

المصادقة: مفتاح API أو رمز JWTالطلب: noneالاستجابة: 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": "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 أو رمز JWTالطلب: noneالاستجابة: 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	معرّف التفريغ النصي.
`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)

تصدير عدة تفريغات نصية دفعة واحدة كملف ZIP، حسب قائمة المعرّفات أو المرشحات. تتطلب صيغ json/pdf خطة Pro.

المصادقة: مفتاح API أو رمز JWTالطلب: application/jsonالاستجابة: 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[]	معرّفات تفريغ نصي صريحة. احذفها لاستخدام المرشحات.
`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 أو رمز JWTالطلب: noneالاستجابة: 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

معرّف التفريغ النصي.

استجابة النجاح

{
  "deleted": true
}

الأخطاء

AUTH_REQUIRED401NOT_FOUND404INTERNAL_ERROR500

GET/api/v1/transcripts/stats

إحصائيات التفريغ النصي

حدّ poll

إجماليات مجمّعة لحسابك.

المصادقة: مفتاح API أو رمز JWTالطلب: noneالاستجابة: 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 أو رمز JWTالطلب: noneالاستجابة: 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

معرّف التفريغ النصي.

استجابة النجاح

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

الأخطاء

AUTH_REQUIRED401PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404VALIDATION_ERROR400

وكلاء الذكاء الاصطناعي

شغّل تحليل الافتتاحيات الجاذبة وإعادة كتابة السيناريو وتقييم الانتشار الواسع على التفريغ النصي. (Pro)

POST/api/v1/agents/{agentType}

تشغيل وكيل ذكاء اصطناعي

Proحدّ agent

أضف تحليلاً بالذكاء الاصطناعي إلى تفريغ نصي مكتمل في الطابور. يكون agentType أحد القيم: hooks أو script_rewrite أو virality_explain أو hook_score.

المصادقة: مفتاح API أو رمز JWTالطلب: application/jsonالاستجابة: 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 أو رمز JWTالطلب: noneالاستجابة: 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 أو رمز JWTالطلب: noneالاستجابة: 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": "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 للحصول على بياناته الوصفية وأفضل مسار ترجمة متاح، دون إنشاء مهمة.

المصادقة: مفتاح API أو رمز JWTالطلب: application/jsonالاستجابة: 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.
`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 أو رمز JWTالطلب: application/jsonالاستجابة: 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

تحليل المدخلات الملصوقة

صنّف النص الملصوق أو معرّفات @ أو الروابط إلى روابط فيديو أو معاينة مجموعة أو معاينة ملف شخصي.

المصادقة: مفتاح API أو رمز JWTالطلب: application/jsonالاستجابة: 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 أو رمز JWTالطلب: noneالاستجابة: 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 أو رمز JWTالطلب: application/jsonالاستجابة: 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

إضافة التفريغ النصي إلى المجلد

أضف تفريغاً نصياً إلى مجلد (عملية آمنة عند التكرار).

المصادقة: مفتاح API أو رمز JWTالطلب: application/jsonالاستجابة: 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

معرّف المجلد المستهدف.

استجابة النجاح · HTTP 201

{
  "added": true
}

الأخطاء

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404INTERNAL_ERROR500

الحساب والمفاتيح والفوترة

إدارة مفاتيح API، وفحص الخطط والحصص، وإرسال الملاحظات.

POST/api/v1/api-keys

إنشاء مفتاح API

Pro

أنشئ مفتاح API فعّالاً. يُعرض المفتاح كاملاً مرة واحدة فقط، فاحفظه بأمان. متاح لخطة Pro فقط.

المصادقة: مفتاح API أو رمز JWTالطلب: application/jsonالاستجابة: 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

Pro

اعرض مفاتيحك النشطة حسب البادئة (لا يُعاد السر أبداً). متاح لخطة Pro فقط.

المصادقة: مفتاح API أو رمز JWTالطلب: noneالاستجابة: 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

عرض الخطط

قائمة عامة بالخطط النشطة وحدودها. لا يتطلب مصادقة.

المصادقة: عام (بدون مصادقة)الطلب: noneالاستجابة: 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 أو رمز JWTالطلب: noneالاستجابة: 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 أو رمز JWTالطلب: application/jsonالاستجابة: 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…

POST/api/v1/jobs

إرسال مهمة التفريغ النصي

حدّ submit

المصادقة: مفتاح API أو رمز JWTالطلب: application/jsonالاستجابة: 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"}'

قد يُرجع الرابط الواحد الاستجابة HTTP 200 مع حمولة نهائية بحالة completed أو failed عند اكتمال المعالجة بشكل مباشر.
تُرجع الدفعات الاستجابة HTTP 202 مع job_id وحالة إجمالية وحالات لكل عنصر داخل items.
افحص مصفوفة العناصر لمعرفة حالة كل فيديو: في الانتظار، أو قيد المعالجة، أو مكتمل، أو فاشل.
تعيين include_download_assets: true في الخطة المجانية يُرجع PLAN_REQUIRED (403).

حقول نص الطلب

`urls`مطلوب string[]	روابط فيديوهات TikTok. حدّ الدفعة في الخطة المجانية هو 5.
`output_language` string	لغة التفريغ النصي المستهدفة (رمز ISO). القيمة الافتراضية en.
`also_translate_to` string[]	لغات إضافية لترجمة التفريغ النصي إليها.
`allow_asr_fallback` boolean	نسخ الصوت صوتياً عندما لا يوجد مسار تسميات توضيحية. القيمة الافتراضية false.
`include_download_assets` boolean	احفظ ملفات الفيديو والغلاف للتنزيل. متاح لخطة Pro فقط.
`idempotency_key` string	مفتاح لمنع التكرار؛ إعادة استخدامه تُرجع المهمة الأصلية.

استجابة النجاح · 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