مرجع API

النصوص V2

V2 هو نموذج النصوص المبسّط الذي يملكه المستخدم. يركّز على الاستجابة السريعة من الذاكرة المؤقتة، ونتائج متّسقة، ولا ترجمات مفاجئة ما لم تطلب لغة معيّنة.

عنوان URL الأساسيhttps://www.youtubetranscript.dev/api/v2

ما يمكنك فعله

تفريغ فيديو

الصق رابط YouTube أو معرّف الفيديو واحصل على النص، عادةً خلال ثوانٍ.

POST/transcribe

تفريغ عدة فيديوهات

أرسل حتى 3,000 فيديو في طلب واحد واحصل على إشعار عند الانتهاء.

POST/batch

قوائم التشغيل والقنوات

حوّل قائمة تشغيل أو قناة إلى قائمة فيديوهات جاهزة للتفريغ.

POST/playlists/resolve

ملفاتك الصوتية والمرئية

ارفع ملفًا وفرّغه باستخدام التعرف على الكلام.

POST/uploads

إدارة النصوص

اعرض نصوصك أو اجلبها أو ترجمها أو احذفها.

GET/transcripts

متابعة المهام الطويلة

تابع مهام التعرف على الكلام أو استلم Webhook عند انتهائها.

GET/jobs/{job_id}

جديد: معامل mode واحد لكل مصادر النص

اختر auto, captions_only, human_captions_only, speech_to_text_only بدلًا من الجمع بين source وallow_asr. تستمر الطلبات الحالية في العمل تمامًا كما كانت. تعرّف على طريقة العمل

مواصفات OpenAPI

نزّل ملف YAML لاستيراده في Postman أو Insomnia، أو لتوليد عملاء، أو للصقه في ChatGPT / Claude.

OpenAPI 3.0: V2 (موصى به)

تفريغ فيديو واحد

أسرع طريقة لمعالجة فيديو واحد في كل مرة. تُعاد النصوص المستندة إلى الترجمات المصاحبة خلال ثوانٍ؛ أما ASR فيعمل بشكل غير متزامن ويُستطلع عبر /api/v2/jobs/{job_id}.

تفريغ فيديو

Transcribe a single YouTube video. Returns immediately for caption-based videos. With mode=auto it falls back to ASR (async) when captions are unavailable: you get status processing and a job_id to poll at /api/v2/jobs/{job_id}, or the result is POSTed to webhook_url if you set one. Responses include the mode the request ran with.

POST/api/v2/transcribe

المعاملات

videostringمطلوب

YouTube URL or 11-character video ID. Required unless upload_id is set.

upload_idstring

Transcribe an uploaded media file instead of a YouTube video (see /uploads). Forces the ASR path (mode must be omitted or speech_to_text_only); webhook_url required. The upload id is returned as video_id in results.

modeauto | captions_only | human_captions_only | speech_to_text_only

Where the transcript comes from (recommended). auto: captions first, speech-to-text (ASR) only if the video has none. captions_only: any captions, never ASR. human_captions_only: human-made captions only. speech_to_text_only: always transcribe the audio. auto and speech_to_text_only can charge ASR credits. Replaces source + allow_asr; cannot be combined with them. Note: mode=auto is not the same as legacy source=auto (captions only, which is mode=captions_only). When omitted, your account default from the API Dashboard applies: auto for accounts created from October 2026, captions_only for older accounts unless changed. ASR modes work without webhook_url: poll the returned job_id.

languageISO 639-1

Preferred transcript language (e.g. en). If unavailable, captions in another language may be returned: transcript.language reports the actual language.

sourceauto | manual | asr

Legacy, still supported: use mode instead. Default: auto. asr transcribes the audio (async, requires webhook_url).

allow_asrboolean

Legacy, still supported: use mode=auto instead. Falls back to ASR if captions fail.

formatobject

{ timestamp, paragraphs, words }: include extra structure in the transcript.

webhook_urluri

When set, ASR results are POSTed to your URL. Optional with mode (poll the job_id instead); required for legacy source=asr. Ignored by captions_only and human_captions_only, which never use ASR.

asr_optionsobject

Rich ASR config: language (+ codeSwitching, medicalMode, keyTerms), translateTo, speaker diarization (speakerLabels, speakerId + type/known values, multichannel, exact or min/max expected speakers), speech understanding (topics, summary, moderation, PII, profanity, sentiment), and formatting (punctuation, text formatting, filler words, custom date/phone/email patterns). Billable add-ons increase cost: preview with /transcribe/estimate. See the AsrOptions schema in the OpenAPI spec.

curl -X POST https://www.youtubetranscript.dev/api/v2/transcribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": "dQw4w9WgXcQ",
    "mode": "auto",
    "language": "en",
    "format": { "timestamp": true, "paragraphs": true }
  }'

الاستجابة (200)

{
  "request_id": "req_abc123",
  "status": "completed",
  "data": {
    "video_id": "dQw4w9WgXcQ",
    "video_title": "Example video",
    "transcript": {
      "text": "Welcome to this tutorial...",
      "language": "en",
      "source": "auto",
      "segments": [
        { "text": "Welcome to this tutorial.", "start": 0, "end": 2500 }
      ]
    }
  },
  "credits_used": 1,
  "mode": "auto"
}

تقدير التكلفة

Dry-run credit estimate. Returns the ASR base cost plus any add-on surcharge for the requested asr_options without creating a job or charging credits.

POST/api/v2/transcribe/estimate

المعاملات

videostringمطلوب

YouTube URL or 11-character video ID.

modeauto | captions_only | human_captions_only | speech_to_text_only

Same values as /transcribe. Use speech_to_text_only (or auto) to preview the ASR cost.

sourceauto | manual | asr

Legacy, still supported: use mode instead. Defaults to asr for cost preview.

asr_optionsobject

Same shape as /transcribe. Add-on charges are prorated by duration.

curl -X POST https://www.youtubetranscript.dev/api/v2/transcribe/estimate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": "dQw4w9WgXcQ",
    "mode": "speech_to_text_only",
    "asr_options": {
      "speakerLabels": true,
      "summarization": true,
      "translateTo": "es"
    }
  }'

الاستجابة (200)

{
  "request_id": "req_abc123",
  "video_id": "dQw4w9WgXcQ",
  "source": "asr",
  "mode": "speech_to_text_only",
  "duration_seconds": 213,
  "duration_minutes": 4,
  "max_duration_minutes": 480,
  "exceeds_max_duration": false,
  "base_credits": 3,
  "addon_credits": 2,
  "estimated_credits": 5
}

التحقق من حالة المهمة

Poll a single transcription job. Use this for ASR jobs returned from /transcribe. Returns 202 while running and 200 when complete. Completed ASR jobs include asr_intelligence (summary, topics, sentiment, etc.) when those options were enabled.

GET/api/v2/jobs/{job_id}

المعاملات

job_idpathمطلوب

Identifier returned in the original transcribe response.

include_segmentsboolean

Include segment-level timestamps in the transcript payload.

include_paragraphsboolean

Include paragraph groupings.

include_wordsboolean

Include word-level timestamps (ASR only).

curl -X GET https://www.youtubetranscript.dev/api/v2/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

الاستجابة (200)

{
  "request_id": "req_abc123",
  "status": "completed",
  "data": {
    "video_id": "dQw4w9WgXcQ",
    "transcript": {
      "text": "Welcome to this tutorial...",
      "language": "en",
      "source": "asr",
      "segments": [{ "text": "Welcome to this tutorial.", "start": 0, "end": 2500 }]
    }
  },
  "credits_used": 6
}

ارفع ملفاتك الخاصة

فرّغ ملفات الصوت أو الفيديو الخاصة بك عبر مسار ASR. ثلاث خطوات: سجّل عملية الرفع، وأرسل البايتات بطلب PUT إلى الرابط الموقّع، ثم أنهِ العملية: بعدها استدعِ /transcribe مع upload_id. تصل النتائج إلى الـ webhook الخاص بك وتُستطلع مثل أي مهمة ASR.

رفع ملف

Register an audio/video file upload and get a signed URL. PUT the raw file bytes to signed_url (with the file's Content-Type), finalize via /uploads/{upload_id}/complete, then transcribe with upload_id on /transcribe. Max 2GB and 8 hours per file.

POST/api/v2/uploads

المعاملات

filenamestringمطلوب

Original filename. The extension is preserved for content sniffing.

mime_typestringمطلوب

Must start with audio/ or video/ (e.g. audio/mpeg, video/mp4).

size_bytesintegerمطلوب

File size in bytes. Max 2147483648 (2GB).

duration_secintegerمطلوب

Media duration in seconds. Max 28800 (8 hours). Used for the ASR credit estimate.

curl -X POST https://www.youtubetranscript.dev/api/v2/uploads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "interview.mp3",
    "mime_type": "audio/mpeg",
    "size_bytes": 48211234,
    "duration_sec": 1820
  }'

# Then PUT the raw file bytes to the returned signed_url:
curl -X PUT "SIGNED_URL_FROM_RESPONSE" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @interview.mp3

# Then finalize:
curl -X POST https://www.youtubetranscript.dev/api/v2/uploads/UPLOAD_ID/complete \
  -H "Authorization: Bearer YOUR_API_KEY"

الاستجابة (200)

{
  "upload_id": "up_a1B2c3D4",
  "bucket": "asr-media",
  "path": "user-uuid/up_a1B2c3D4/interview.mp3",
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "signed_url": "https://api.youtubetranscript.dev/storage/v1/object/upload/sign/asr-media/...?token=..."
}

إنهاء الرفع

Finalize an upload after the PUT to signed_url succeeds. Verifies the file exists in storage and marks it ready. The upload can then be transcribed by passing upload_id to /transcribe (source="asr", webhook_url required).

POST/api/v2/uploads/{upload_id}/complete

المعاملات

upload_idpathمطلوب

Upload id returned by POST /uploads.

curl -X POST https://www.youtubetranscript.dev/api/v2/uploads/up_a1B2c3D4/complete \
  -H "Authorization: Bearer YOUR_API_KEY"

الاستجابة (200)

{
  "upload_id": "up_a1B2c3D4",
  "status": "uploaded",
  "filename": "interview.mp3",
  "duration_sec": 1820
}

التفريغ على دفعات

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

تفريغ عدة فيديوهات

Submit up to 3,000 videos in one request. Returns within 2 seconds; poll the returned poll_url or wait for the webhook.

POST/api/v2/batch

المعاملات

video_idsstring[]مطلوب

Up to 3,000 IDs depending on plan. Free = 10, Basic = 500, Pro = 1,500, Business = 3,000.

languageISO 639-1

Preferred language for every video.

modeauto | captions_only | human_captions_only | speech_to_text_only

Where the transcript comes from (recommended). auto: captions first, speech-to-text (ASR) only if the video has none. captions_only: any captions, never ASR. human_captions_only: human-made captions only. speech_to_text_only: always transcribe the audio. auto and speech_to_text_only can charge ASR credits. Replaces source + allow_asr; cannot be combined with them. Note: mode=auto is not the same as legacy source=auto (captions only, which is mode=captions_only). For batch, auto and speech_to_text_only require webhook_url. When omitted, your API Dashboard default applies (an ASR default only when webhook_url is set).

sourceauto | manual | asr

Legacy, still supported: use mode instead. Default: auto. source=asr requires webhook_url.

allow_asrboolean

Legacy, still supported: use mode=auto instead. webhook_url is required.

formatobject

{ timestamp, paragraphs, words }: applied to every result.

webhook_urluri

Delivers the completed batch payload. Required for mode=auto or speech_to_text_only (legacy: allow_asr=true or source=asr).

asr_optionsobject

Rich ASR config applied to every video transcribed via ASR (same shape as /transcribe). Billable add-ons apply per video.

curl -X POST https://www.youtubetranscript.dev/api/v2/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_ids": ["dQw4w9WgXcQ", "jNQXAC9IVRw"],
    "mode": "auto",
    "webhook_url": "https://your-domain.com/webhook",
    "format": { "timestamp": true }
  }'

الاستجابة (202)

{
  "batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "results": [],
  "summary": { "total": 2, "succeeded": 0, "failed": 0, "processing": 2 },
  "poll_url": "https://www.youtubetranscript.dev/api/v2/batch/550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2026-05-15T10:00:00Z"
}

التحقق من حالة الدفعة

Check the status of a batch. Returns 202 while processing and 200 when results are ready. Stop polling once status is "completed", "partial", or "failed": finished batches never change, and re-fetching one more than 60 times in 24h returns 429 with a Retry-After header.

GET/api/v2/batch/{batch_id}

المعاملات

batch_idpathمطلوب

Batch identifier returned from POST /batch.

curl -X GET https://www.youtubetranscript.dev/api/v2/batch/BATCH_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

الاستجابة (200)

{
  "batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "summary": { "total": 2, "succeeded": 2, "failed": 0, "processing": 0 },
  "results": [
    { "request_id": "req_1", "status": "completed", "data": { "video_id": "dQw4w9WgXcQ" } },
    { "request_id": "req_2", "status": "completed", "data": { "video_id": "jNQXAC9IVRw" } }
  ],
  "credits_used": 2,
  "webhook_delivered": true,
  "completed_at": "2026-05-15T10:04:00Z"
}

النصوص والمهام

اعرض نصوصك المحفوظة واجلبها وترجمها واحذفها، واعرض المهام غير المتزامنة. تقبل جميع نقاط النهاية المصادقة نفسها بمفتاح API.

عرض المهام

List your transcription jobs, newest first. Filter by status and paginate. Use the returned job_id with GET /api/v2/jobs/{job_id} to fetch a transcript.

GET/api/v2/jobs

المعاملات

pagequery

Page number (default 1).

limitquery

Items per page (default 50, max 100).

statusquery

completed | processing | failed | requires_asr_confirmation.

curl "https://www.youtubetranscript.dev/api/v2/jobs?status=processing&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

الاستجابة (200)

{
  "jobs": [
    {
      "job_id": "9c2...",
      "video_id": "dQw4w9WgXcQ",
      "video_title": "Example video",
      "language": "en",
      "source": "asr",
      "status": "processing",
      "error": null,
      "credits_used": 0,
      "created_at": "2026-07-06T12:00:00Z",
      "started_at": "2026-07-06T12:00:01Z",
      "completed_at": null
    }
  ],
  "count": 1,
  "pagination": { "page": 1, "limit": 25, "total": 1, "totalPages": 1, "hasMore": false }
}

عرض النصوص

List stored transcripts with search, status, language, and date filters. Metadata only (no full text) unless include_segments=true.

GET/api/v2/transcripts

المعاملات

pagequery

Page number (default 1).

limitquery

Items per page (default 50, max 100).

searchquery

Match video id, title, or transcript text.

statusquery

Filter by status; omit for succeeded.

languagequery

Filter by language code.

date_fromquery

ISO date-time lower bound.

date_toquery

ISO date-time upper bound.

include_segmentsquery

Include segments in each item.

curl "https://www.youtubetranscript.dev/api/v2/transcripts?page=1&limit=50&status=succeeded" \
  -H "Authorization: Bearer YOUR_API_KEY"

الاستجابة (200)

{
  "history": [
    {
      "id": "b1f...",
      "video_id": "dQw4w9WgXcQ",
      "video_title": "Example video",
      "language": "en",
      "source_kind": "auto",
      "status": "succeeded",
      "created_at": "2026-07-06T12:00:00Z",
      "word_count": 1234,
      "segment_count": 88,
      "credits_used": 1
    }
  ],
  "count": 1,
  "pagination": { "page": 1, "limit": 50, "total": 1, "totalPages": 1, "hasMore": false }
}

جلب نص

Fetch the best owned transcript for a video, including asr_intelligence (summary, topics, sentiment, etc.), plus summary and mind_map when generated.

GET/api/v2/transcripts/{video_id}

المعاملات

video_idpathمطلوب

YouTube 11-character video ID.

idquery

Specific transcript/job id.

languagequery

Preferred language version.

sourcequery

auto | manual | asr.

include_timestampsquery

Include segments (default true).

curl "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ?language=en" \
  -H "Authorization: Bearer YOUR_API_KEY"

الاستجابة (200)

{
  "id": "b1f...",
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "text": "Welcome to this tutorial...",
  "segments": [{ "text": "Welcome to this tutorial.", "start": 0, "end": 2500 }],
  "has_timestamps": true,
  "source_kind": "asr",
  "video_title": "Example video",
  "summary": null,
  "mind_map": null,
  "asr_intelligence": {
    "summary": "A short overview of the video...",
    "topics": [{ "text": "Technology", "relevance": 0.92 }],
    "sentiment": [{ "text": "Great tutorial", "sentiment": "POSITIVE" }]
  }
}

ترجمة نص

Translate an owned transcript into a target language using YouTube captions or the AI provider. Returns free if you already own the translation.

POST/api/v2/transcripts/{video_id}/translate

المعاملات

video_idpathمطلوب

YouTube 11-character video ID.

target_languageISO 639-1مطلوب

Language to translate into.

source_languageISO 639-1

Source transcript language to translate from.

providerai | youtube

Translation provider.

allow_ai_fallbackboolean

Fall back to AI when YouTube has no translation.

curl -X POST "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ/translate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "target_language": "es", "provider": "ai" }'

الاستجابة (200)

{
  "success": true,
  "message": "Translation completed",
  "language": "es",
  "credits_used": 4,
  "provider_used": "ai"
}

اللغات المتاحة

List the languages you already own for a video plus the YouTube translation targets available for it.

GET/api/v2/transcripts/{video_id}/languages

المعاملات

video_idpathمطلوب

YouTube 11-character video ID.

include_youtube_defaultquery

Include YouTube translation targets (default true).

curl "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ/languages" \
  -H "Authorization: Bearer YOUR_API_KEY"

الاستجابة (200)

{
  "video_id": "dQw4w9WgXcQ",
  "languages": ["en", "es"],
  "youtube_translation_languages": ["fr", "de", "ja"]
}

حذف نص

Delete owned transcript(s) for a video. Optional language/source query params narrow the deletion; otherwise every language/source is removed. Also deletes bulk by id via POST /api/v2/transcripts/bulk-delete.

DELETE/api/v2/transcripts/{video_id}

المعاملات

video_idpathمطلوب

YouTube 11-character video ID.

languagequery

Only delete this language.

sourcequery

Only delete this source (auto | manual | asr).

curl -X DELETE "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ" \
  -H "Authorization: Bearer YOUR_API_KEY"

الاستجابة (200)

{
  "success": true,
  "deleted": 2,
  "message": "Successfully deleted 2 transcripts"
}

قوائم التشغيل

حوّل قائمة تشغيل إلى معرّفات فيديو، وفرّغها عبر /api/v2/batch، ثم اطّلع على دفعة القائمة وسجلّها.

عرض فيديوهات قائمة تشغيل

Resolve a YouTube playlist by URL or ID into its video list (metadata only). Pair the returned video_id values with /api/v2/batch to transcribe them.

POST/api/v2/playlists/resolveالخطط المدفوعة

المعاملات

playlist_urlstring

Playlist URL. One of playlist_url or playlist_id is required.

playlist_idstring

Playlist ID (the list= value).

limitinteger

Max videos returned (1-100).

curl -X POST https://www.youtubetranscript.dev/api/v2/playlists/resolve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "playlist_url": "https://www.youtube.com/playlist?list=PLxxxx", "limit": 100 }'

الاستجابة (200)

{
  "playlist_id": "PLxxxx",
  "title": "My playlist",
  "total": 42,
  "truncated": false,
  "items": [
    { "video_id": "dQw4w9WgXcQ", "title": "Example video" }
  ]
}

حالة مهام قائمة التشغيل

Fetch a playlist batch and per-video transcription job status. For overall batch progress, poll GET /api/v2/batch/{batch_id}.

GET/api/v2/playlists/{playlist_id}

المعاملات

playlist_idpathمطلوب

Batch ID returned from /playlists/resolve.

curl "https://www.youtubetranscript.dev/api/v2/playlists/{playlist_batch_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

الاستجابة (200)

{
  "playlist": { "id": "3f1...", "playlist_id": "PLxxxx", "title": "My playlist" },
  "videos": [
    { "video_id": "dQw4w9WgXcQ", "video_title": "Example video", "status": "succeeded" }
  ]
}

أحدث مهام قوائم التشغيل

List recent playlist batches for the authenticated user.

GET/api/v2/playlists/history

curl "https://www.youtubetranscript.dev/api/v2/playlists/history" \
  -H "Authorization: Bearer YOUR_API_KEY"

الاستجابة (200)

{
  "history": [
    { "id": "3f1...", "playlist_id": "PLxxxx", "title": "My playlist", "total_videos": 42 }
  ],
  "count": 1
}

القنوات

مسار تفريغ القناة:1. POST /api/v2/channels/resolve: اجلب مقاطع القناة المرفوعة (بيانات الفيديو الوصفية فقط).2. POST /api/v2/batch: أرسل قيم video_id المُعادة لبدء التفريغ. استخدم webhook_url لاستلام النتائج عند الانتهاء.3. GET /api/v2/batch/{batch_id}: استطلع الدفعة لمعرفة التقدّم العام والنتائج المجمّعة.4. GET /api/v2/channels/{channel_id}: اجلب دفعة القناة مع حالة المهمة لكل فيديو؛ وتعرض /channels/history دفعات القنوات السابقة.

عرض فيديوهات قناة

Fetch the uploads of a YouTube channel by URL, channel ID, or @handle. Returns video metadata only: pair the returned video_id values with /api/v2/batch to transcribe them.

POST/api/v2/channels/resolveالخطط المدفوعة

المعاملات

channel_urlstringمطلوب

YouTube channel URL, channel ID, or @handle. One of channel_url, channel_id, or handle must be provided. Handles are the public ID without the @ (for https://www.youtube.com/@jawed, the ID is jawed).

limitinteger

Maximum uploads returned. Defaults to the plan maximum.

Per-request cap: Basic 500 videos · Pro 1,500 videos · Business 3,000 videos. Monthly job cap: Basic 3 · Pro 8 · Business unlimited.

حد المعدل

Plan-based: Free 1 req/s · Basic 25 req/s · Pro 50 req/s · Business 100 req/s. Exceeding the limit returns 429 with a Retry-After header.

curl -X POST https://www.youtubetranscript.dev/api/v2/channels/resolve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "@youtube",
    "limit": 50
  }'

الاستجابة (200)

{
  "channel_id": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
  "channel_title": "YouTube",
  "subscriber_count": 42000000,
  "video_count": 1200,
  "total": 1,
  "truncated": false,
  "items": [
    {
      "video_id": "dQw4w9WgXcQ",
      "title": "Latest upload",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "published_at": "2026-05-01T12:00:00Z",
      "duration_seconds": 420
    }
  ]
}

حالة مهام القناة

Fetch a channel batch and the per-video transcription job status. For overall batch status (counts + progress), poll GET /api/v2/batch/{batch_id} instead: use this endpoint when you also need each video's individual job state.

GET/api/v2/channels/{channel_id}

المعاملات

channel_idpathمطلوب

Batch ID returned from /channels/resolve.

curl -X GET https://www.youtubetranscript.dev/api/v2/channels/CHANNEL_BATCH_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

الاستجابة (200)

{
  "channel": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "channel_id": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "channel_title": "YouTube",
    "total_videos": 2,
    "completed_count": 1,
    "failed_count": 0,
    "status": "processing",
    "created_at": "2026-05-15T10:00:00Z"
  },
  "videos": [
    {
      "id": "job_123",
      "video_id": "dQw4w9WgXcQ",
      "video_title": "Latest upload",
      "status": "succeeded",
      "created_at": "2026-05-15T10:00:00Z",
      "finished_at": "2026-05-15T10:00:10Z"
    }
  ]
}

أحدث مهام القنوات

List recent channel batches for the authenticated user.

GET/api/v2/channels/history

المعاملات

limitquery

Max items (default 50, max 100).

curl -X GET "https://www.youtubetranscript.dev/api/v2/channels/history?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

الاستجابة (200)

{
  "history": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "channel_id": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
      "channel_title": "YouTube",
      "total_videos": 25,
      "completed_count": 25,
      "failed_count": 0,
      "status": "completed",
      "created_at": "2026-05-15T10:00:00Z",
      "completed_at": "2026-05-15T10:12:00Z"
    }
  ],
  "count": 1
}

البحث

ابحث، ثم حوّل إلى نص:1. GET /api/v2/search/videos (/shorts, /channels, /playlists): ابحث عن المحتوى بالكلمات المفتاحية. رصيد واحد لكل طلب.2. أرسل url الفيديو إلى POST /api/v2/transcribe، أو url القناة أو قائمة التشغيل إلى /api/v2/channels/resolve أو /api/v2/playlists/resolve.3. مرّر next_page_token بوصفه page_token للحصول على مزيد من النتائج (رصيد واحد لكل صفحة).

البحث عن الفيديوهات

Search YouTube videos by keyword. Live streams are included with type "live". Pass a result's url to /api/v2/transcribe to get its transcript. 1 credit per request, including each next page. Refunded if the search fails.

GET/api/v2/search/videos

المعاملات

qqueryمطلوب

Search text, up to 200 characters.

durationquery

Video length: under_3_min, 3_to_20_min or over_20_min.

upload_datequery

Only results uploaded within: today, this_week, this_month or this_year.

sort_byquery

relevance (default) or popular.

regionquery

Two-letter country code to localize results, e.g. US.

page_tokenquery

The next_page_token from a previous response, to get the next page. null means there are no more results.

حد المعدل

Plan-based: Free 1 req/s · Basic 25 req/s · Pro 50 req/s · Business 100 req/s. Exceeding the limit returns 429 with a Retry-After header.

curl "https://www.youtubetranscript.dev/api/v2/search/videos?q=python%20tutorial&duration=over_20_min" \
  -H "Authorization: Bearer YOUR_API_KEY"

الاستجابة (200)

{
  "request_id": "6f1c2a9e-4b7d-4f2a-9c1e-2d3b4a5c6d7e",
  "type": "videos",
  "query": "python tutorial",
  "results": [
    {
      "type": "video",
      "video_id": "kqtD5dpn9C8",
      "url": "https://www.youtube.com/watch?v=kqtD5dpn9C8",
      "title": "Python for Beginners - Learn Coding with Python in 1 Hour",
      "thumbnail": "https://i.ytimg.com/vi/kqtD5dpn9C8/hq720.jpg",
      "channel": {
        "channel_id": "UCWv7vMbMWH4-V0ZXdmDpPBA",
        "title": "Programming with Mosh",
        "handle": "programmingwithmosh",
        "url": "https://www.youtube.com/@programmingwithmosh",
        "thumbnail": "https://yt3.ggpht.com/..."
      },
      "view_count": 25574982,
      "view_count_text": "25,574,982 views",
      "published_at": null,
      "published_text": "6 years ago",
      "duration_seconds": 3606,
      "duration_text": "1:00:06",
      "badges": []
    }
  ],
  "next_page_token": "cDA6RWdJUUFV...",
  "credits_used": 1,
  "credits_remaining": 4602
}

البحث عن Shorts

Search YouTube Shorts by keyword. 1 credit per request, including each next page. Refunded if the search fails.

GET/api/v2/search/shorts

المعاملات

qqueryمطلوب

Search text, up to 200 characters.

upload_datequery

Only results uploaded within: today, this_week, this_month or this_year.

sort_byquery

relevance (default) or popular.

regionquery

Two-letter country code to localize results, e.g. US.

page_tokenquery

The next_page_token from a previous response, to get the next page. null means there are no more results.

حد المعدل

Plan-based: Free 1 req/s · Basic 25 req/s · Pro 50 req/s · Business 100 req/s. Exceeding the limit returns 429 with a Retry-After header.

curl "https://www.youtubetranscript.dev/api/v2/search/shorts?q=python%20tips" \
  -H "Authorization: Bearer YOUR_API_KEY"

الاستجابة (200)

{
  "request_id": "0b8e7d6c-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
  "type": "shorts",
  "query": "python tips",
  "results": [
    {
      "type": "short",
      "video_id": "gbYLsUngzLc",
      "url": "https://www.youtube.com/watch?v=gbYLsUngzLc",
      "title": "Top 10 Most Important Python Functions You Must Know!",
      "thumbnail": "https://i.ytimg.com/vi/gbYLsUngzLc/oar2.jpg",
      "channel": null,
      "view_count": 1200000,
      "view_count_text": "1.2M views",
      "published_at": null,
      "published_text": null,
      "duration_seconds": null,
      "duration_text": null,
      "badges": []
    }
  ],
  "next_page_token": "cDA6RWdJUUNR...",
  "credits_used": 1,
  "credits_remaining": 4601
}

البحث عن القنوات

Search YouTube channels by keyword. Pass a result's url to /api/v2/channels/resolve to list its videos. 1 credit per request, including each next page. Refunded if the search fails.

GET/api/v2/search/channels

المعاملات

qqueryمطلوب

Search text, up to 200 characters.

upload_datequery

Only results uploaded within: today, this_week, this_month or this_year.

sort_byquery

relevance (default) or popular.

regionquery

Two-letter country code to localize results, e.g. US.

page_tokenquery

The next_page_token from a previous response, to get the next page. null means there are no more results.

حد المعدل

Plan-based: Free 1 req/s · Basic 25 req/s · Pro 50 req/s · Business 100 req/s. Exceeding the limit returns 429 with a Retry-After header.

curl "https://www.youtubetranscript.dev/api/v2/search/channels?q=python" \
  -H "Authorization: Bearer YOUR_API_KEY"

الاستجابة (200)

{
  "request_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "type": "channels",
  "query": "python",
  "results": [
    {
      "type": "channel",
      "channel_id": "UCKQdc0-Targ4nDIAUrlfKiA",
      "url": "https://www.youtube.com/@PythonSimplified",
      "title": "Python Simplified",
      "handle": "PythonSimplified",
      "description": "Hi everyone! My name is Mariya and I'm a software developer...",
      "thumbnail": "https://yt3.googleusercontent.com/...",
      "subscriber_count": 286000,
      "subscriber_count_text": "286K",
      "badges": ["Verified"]
    }
  ],
  "next_page_token": "cDA6RWdJUUFn...",
  "credits_used": 1,
  "credits_remaining": 4600
}

البحث عن قوائم التشغيل

Search YouTube playlists by keyword. Pass a result's url to /api/v2/playlists/resolve to list its videos. 1 credit per request, including each next page. Refunded if the search fails.

GET/api/v2/search/playlists

المعاملات

qqueryمطلوب

Search text, up to 200 characters.

upload_datequery

Only results uploaded within: today, this_week, this_month or this_year.

sort_byquery

relevance (default) or popular.

regionquery

Two-letter country code to localize results, e.g. US.

page_tokenquery

The next_page_token from a previous response, to get the next page. null means there are no more results.

حد المعدل

Plan-based: Free 1 req/s · Basic 25 req/s · Pro 50 req/s · Business 100 req/s. Exceeding the limit returns 429 with a Retry-After header.

curl "https://www.youtubetranscript.dev/api/v2/search/playlists?q=python%20course" \
  -H "Authorization: Bearer YOUR_API_KEY"

الاستجابة (200)

{
  "request_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "type": "playlists",
  "query": "python course",
  "results": [
    {
      "type": "playlist",
      "playlist_id": "PLsyeobzWxl7omDoEYrrf3oXvXxa6MPgek",
      "url": "https://www.youtube.com/playlist?list=PLsyeobzWxl7omDoEYrrf3oXvXxa6MPgek",
      "title": "Python Tutorial | Complete Python Course (Beginner to Advanced)",
      "thumbnail": "https://i.ytimg.com/vi/YZkyL-f-YXY/hq720.jpg",
      "video_count": 54,
      "first_video_id": "YZkyL-f-YXY",
      "channel": {
        "channel_id": "UC59K-uG2A5ogwIrHw4bmlEg",
        "title": "Telusko",
        "handle": "Telusko",
        "url": "https://www.youtube.com/@Telusko",
        "thumbnail": null
      }
    }
  ],
  "next_page_token": "cDA6RWdJUUF3...",
  "credits_used": 1,
  "credits_remaining": 4599
}

التكاملات

حزم SDK رسمية، وخادم MCP لـ Claude وCursor، وGPT مخصّص، وقوالب جاهزة لـ Make وn8n.

MCP serverClaude · Cursor

المستودع

أضف خادم YouTube Transcript MCP إلى Claude Desktop أو Cursor أو أي عميل متوافق مع MCP. يضيف أدوات لتفريغ الفيديوهات وجلب النصوص الموجودة والتحقق من الاستخدام.

التثبيت والإعداد

claude mcp add --transport http youtubetranscript https://mcp.youtubetranscript.dev --header "x-api-token: YOUR_API_KEY"

Node SDKnpm

npm

أنواع TypeScript متكاملة، وإعادة المحاولة، وأدوات مساعدة للتقسيم إلى صفحات، والتحقق من توقيع webhook.

التثبيت والاستخدام

npm install youtube-transcript-api

Python SDKPyPI

PyPI

عملاء متزامنون وغير متزامنين، وملفات تعريف الأنواع، وأدوات مساعدة لمسارات الدفعات وwebhook.

التثبيت والاستخدام

pip install youtubetranscriptdevapi

Custom GPTChatGPT

فتح في ChatGPT

أضف GPT المخصّص الخاص بنا إلى ChatGPT لتلخيص أي فيديو على YouTube أو الاقتباس منه أو ترجمته أو الاستعلام عنه بلغة طبيعية. يعمل عبر /api/v2/gpt/* في الخلفية.

· تسجيل دخول عبر OAuth: دون مفتاح API في المحادثة
· بديل ASR عند غياب الترجمات المصاحبة
· اقتباسات مع الطوابع الزمنية وروابط المصدر
· تجربة مجانية لكل حساب

Make.com & n8nبدون كود

تصفّح القوالب

استورد القالب (أو انسخ المقتطف) لإضافة التفريغ إلى عمليات الأتمتة الحالية: Notion وSheets وSlack وAirtable ومسارات على غرار Zapier.

وحدة Make.com

Module: HTTP > Make a request
- URL: https://www.youtubetranscript.dev/api/v2/transcribe
- Method: POST
- Headers:
    Authorization: Bearer {{connection.api_key}}
    Content-Type: application/json
- Body type: Raw / JSON
- Request content:
    {
      "video": "{{1.video_url}}",
      "format": { "timestamp": true }
    }

عقدة HTTP في n8n

{
  "name": "Transcribe Video",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "POST",
    "url": "https://www.youtubetranscript.dev/api/v2/transcribe",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendBody": true,
    "specifyBody": "json",
    "jsonBody": "={ \"video\": $json.video_url }"
  }
}

Postman / OpenAPIبنقرة واحدة

مجموعة Postman

استورد مواصفات OpenAPI إلى Postman أو Insomnia أو أي أداة تدعم OpenAPI 3.

تنزيل YAML لـ V2 تنزيل JSON لـ V2

الأخطاء

تُعيد الأخطاء جسم JSON يحتوي على code وmessage. وتعكس حالة HTTP فئة الخطأ.

حالة HTTP	رمز الخطأ	الوصف
400	`invalid_request`	Invalid JSON or missing required fields
401	`invalid_api_key`	Missing or invalid API key
402	`payment_required`	Insufficient credits
404	`no_captions`	No captions available and ASR not used
429	`rate_limit_exceeded`	Too many requests, check Retry-After
500	`internal_error`	Server error, retry with backoff

حدود المعدل والحصص

حدود لكل خطة على الطلبات المستمرة وأحجام الدفعات. تجاوز الحد يُعيد 429 مع ترويسة Retry-After.

الخطة	الطلبات	حجم الدفعة
Free	1 req/s	10 videos
Basic	25 req/s	500 videos
Pro	50 req/s	1,500 videos
Business	100 req/s	3,000 videos

الدعم

تحتاج مساعدة؟ تواصل معنا: عادةً نردّ خلال ساعات قليلة.

support@youtubetranscript.dev

Status

وقت التشغيل والحوادث

ما يمكنك فعله

تفريغ فيديو

تقدير التكلفة

التحقق من حالة المهمة

رفع ملف

إنهاء الرفع

تفريغ عدة فيديوهات

التحقق من حالة الدفعة

عرض المهام

عرض النصوص

جلب نص

ترجمة نص

اللغات المتاحة

حذف نص

عرض فيديوهات قائمة تشغيل

حالة مهام قائمة التشغيل

أحدث مهام قوائم التشغيل

عرض فيديوهات قناة

حالة مهام القناة

أحدث مهام القنوات

البحث عن الفيديوهات

البحث عن Shorts

البحث عن القنوات

البحث عن قوائم التشغيل

موارد ذات صلة