YouTube Downloader API Documentation

.M4A Audio

Initialize a Download (Process Audio)

Initializes (processes) the audio download of a YouTube video, using the video ID.

The response of this request will be a video download resource, with an ID that can be used in the Get A Download method, to retrieve the actual file URL for download.

After the video download is created, a background job will start processing the request and fetch the audio file from YouTube servers. This process could be fast for short videos, but could take up to 10 minutes for long videos.

The M4A file will be available anytime for download, once the process has been completed. If you want a new download link generated, you simply need to send another ‘Get A Download’ request with the downloadID.

If you initialize a download more than once and we have a successful download existing for the file, we will return the download object instead of initiating the process again - this avoids accidental duplicate credit charges for the user.

Endpoint

POST https://dashboard.transcriptdownloader.com/api/downloads/audio

Body

{
     "youtube_video_id": "<string>",
     "include_webhook": "<string>"
}
Parameter Type Required Description
youtube_video_id string Yes The YouTube video ID
include_webhook string No A publicly reachable URL. When the job completes or fails, the response will be POSTed to this URL. Test your URL first using POST /api/webhook/test.

Example responses

Successful response - when the download process has been initialized.

{
    "data": {
        "id": "01JW72M0AGW3M6R3QDCS30RD2P",
        "media_id": "Fqdz6A-5d04",
        "type": "audio",
        "duration": "01:47:55",
        "cost": "1.079",
        "status": "pending",
        "created_at": "2025-01-23T00:30:50.000000Z",
        "transcript_speaker_id": "01JW72M0AGW3M6R3QDCS30RD2P",
        "transcript_speaker_cost": "1.079",
        "audio_url": null
    }
}

Subsequent response - prior to completion, processing the audio and readying for download

{
      "error": "You already have a pending download for this video",
      "id": "01JW72M0AGW3M6R3QDCS30RD2P"
}

A download can be accessed through the API by using the following endpoint:

Endpoint

GET https://dashboard.transcriptdownloader.com/downloads/{downloadId}

Example responses

Success - Download has been processed correctly

{
    "data": {
        "id": "01JW72M0AGW3M6R3QDCS30RD2P",
        "media_id": "Fqdz6A-5d04",
        "type": "audio",
        "duration": "01:47:55",
        "cost": "1.079",
        "status": "success",
        "created_at": "2025-01-23T00:30:50.000000Z",
        "transcript_speaker_id": "01JW72M0AGW3M6R3QDCS30RD2P",
        "transcript_speaker_cost": "1.079",
        "audio_url": "https://drive.transcriptdownloader.com/audios/youtube-tBBaHQoPZR0.m4a?Expires=..."
    }
}

Success - Download still processing

{
    "data": {
        "id": "01JW72M0AGW3M6R3QDCS30RD2P",
        "media_id": "Fqdz6A-5d04",
        "type": "audio",
        "duration": "01:47:55",
        "cost": "1.079",
        "status": "pending",
        "created_at": "2025-01-23T00:30:50.000000Z",
        "transcript_speaker_id": "01JW72M0AGW3M6R3QDCS30RD2P",
        "transcript_speaker_cost": "1.079",
        "audio_url": null
    }
}

Failed download

{
    "data": {
        "id": "01JW72M0AGW3M6R3QDCS30RD2P",
        "media_id": "Fqdz6A-5d04",
        "type": "audio",
        "duration": "01:47:55",
        "cost": "1.079",
        "status": "failed",
        "created_at": "2025-01-23T00:30:50.000000Z",
        "transcript_speaker_id": "01JW72M0AGW3M6R3QDCS30RD2P",
        "transcript_speaker_cost": "1.079",
        "audio_url": null
    }
}

Error responses

.MP4 Video

Initialize a Download (Process Video)

Initializes (processes) the video download of a YouTube video using the video ID.

The response will be a download resource with an ID that can be used in the Get A Download method to retrieve the signed video file URL.

After the download record is created, a background job starts downloading and processing the MP4 file. Short videos may complete in under a minute; longer videos can take up to 20 minutes.

If a successful download already exists for the video, the existing download record is returned — no duplicate charge is applied.

Endpoint

POST https://dashboard.transcriptdownloader.com/api/downloads/video

Body

{
     "youtube_video_id": "<string>",
     "include_webhook": "<string>"
}
Parameter Type Required Description
youtube_video_id string Yes The YouTube video ID
include_webhook string No A publicly reachable URL. When the job completes or fails, the response will be POSTed to this URL. Test your URL first using POST /api/webhook/test.

Example responses

Successful response — download process initialized:

{
    "data": {
        "id": "01JW72M0AGW3M6R3QDCS30RD2P",
        "media_id": "Fqdz6A-5d04",
        "type": "youtube_video",
        "duration": "01:47:55",
        "cost": "1.079",
        "status": "pending",
        "created_at": "2025-01-23T00:30:50.000000Z",
        "transcript_speaker_id": "01JW72M0AGW3M6R3QDCS30RD2P",
        "transcript_speaker_cost": "1.079",
        "file_urls": null
    }
}

Subsequent response — prior to completion, download already pending:

{
      "error": "You already have a pending download for this video",
      "id": "01JW72M0AGW3M6R3QDCS30RD2P"
}

Success — video ready for download:

Use the Get A Download endpoint with the id to retrieve signed URLs once processing is complete.

{
    "data": {
        "id": "01JW72M0AGW3M6R3QDCS30RD2P",
        "media_id": "Fqdz6A-5d04",
        "type": "youtube_video",
        "duration": "01:47:55",
        "cost": "1.079",
        "status": "success",
        "created_at": "2025-01-23T00:30:50.000000Z",
        "transcript_speaker_id": "01JW72M0AGW3M6R3QDCS30RD2P",
        "transcript_speaker_cost": "1.079",
        "file_urls": [
            "https://drive.transcriptdownloader.com/videos/youtube-Fqdz6A-5d04.mp4?Expires=..."
        ]
    }
}

Error responses

Transcripts & Metadata

Get Profile Information & Full Channel List

Our API retrieves a YouTube channel’s profile and full media list with partial metadata. For complete metadata, use the ‘initialize transcription & metadata’ endpoint on individual media. Results may take a moment to compile.

Endpoint

POST https://dashboard.transcriptdownloader.com/api/channel/profile

Body

{
    "url": "<string>"
}

Example Response

The response will include the channel’s profile metadata, and partial metadata info for all media in list.

{
    "status": "success",
    "youtube_id": "UCuD-OWq0lLKLGkuWuNs35sA",
    "title": "State Of Mind",
    "url": "https://www.youtube.com/@state-of-mind",
    "thumbnail": "https://yt3.ggpht.com/...",
    "description": "Channel description...",
    "total_media": 3,
    "creation_date": "2014-01-29 23:41:51",
    "subscriber_count": 62800,
    "total_views": 2155260,
    "country": "US",
    "cost": "0.500",
    "source": "api",
    "videos": [
        {
            "youtube_id": "p8x9NVSZ0r4",
            "title": "Video Title",
            "thumbnail": "https://i.ytimg.com/vi/p8x9NVSZ0r4/default.jpg",
            "published_at": "2024-07-12 00:00:25",
            "duration": 490
        }
    ],
    "download": {
        "id": "01K31YQ38SNP30F7218NX4SMN7",
        "youtube_video_id": "UCuD-OWq0lLKLGkuWuNs35sA",
        "type": "list",
        "cost": "0.500",
        "status": "success",
        "response": null,
        "created_at": "2025-08-19T20:01:17.000000Z"
    }
}

Error responses

Initialize Transcription & Metadata using YouTube Video ID and Language

Our API allows you to get a Youtube Video Transcripts & Metadata in real time.

Endpoint

POST https://dashboard.transcriptdownloader.com/api/transcripts

Body

{
    "youtube_video_id": "<string>",
    "language": "<string>",
    "include_comments": boolean,
    "include_webhook": "<string>"
}
Parameter Type Required Description
youtube_video_id string Yes The YouTube video ID
language string Yes Language code (e.g. en, de, fr)
include_comments boolean No Include video comments in the response
include_webhook string No A publicly reachable URL. When the job completes or fails, the response will be POSTed to this URL. Test your URL first using POST /api/webhook/test.

Example response

{
  "status": "ok",
  "video": {
    "youtube_id": "AyOjAEn36b8",
    "link": "https://youtube.com/watch?v=AyOjAEn36b8",
    "title": "Video Title",
    "description": "",
    "publishedAt": "2025-05-29 17:00:09",
    "duration": "00:00:58",
    "viewCount": 2828633,
    "likeCount": 101223,
    "commentCount": 3260,
    "channelId": "UC0biv5ldm7-TzRXdr79pqAw",
    "channelName": "Channel Name",
    "transcriptsWithTimeStamps": [
      {
        "dur": "2.08",
        "text": "transcript text",
        "start": "0.16"
      }
    ],
    "transcripts": "Full transcript text..."
  },
  "download": {
    "id": "123DDJNRUND",
    "youtube_video_id": "AyOjAEn36b8",
    "type": "captions",
    "cost": "1.600",
    "status": "success",
    "created_at": "2025-06-16T21:34:43.000000Z"
  }
}

Error responses

Get a Previously Generated Transcript & Metadata, Using Download ID

Endpoint

GET https://dashboard.transcriptdownloader.com/api/transcripts/{downloadID}

The response data structure will be similar to when you process a transcript for the first time, with the exception that this does not generate a new process and does not have an extra cost for you.

Transcript with Speaker Diarization

Create Transcript with Speaker Labels

Generates a transcript with speaker diarization (speaker labels) from a previously downloaded audio file. This endpoint automatically identifies and labels different speakers in the audio, making it ideal for interviews, podcasts, meetings, and multi-speaker content.

📋 Note: You must first download the audio using the Initialize a Download endpoint. Use the transcript_speaker_id from the audio download response.

Endpoint

POST https://dashboard.transcriptdownloader.com/api/transcriptspeakerid

Body

{
    "transcript_with_speaker_id": "<string>",
    "include_webhook": "<string>"
}
Parameter Type Required Description
transcript_with_speaker_id string Yes The transcript_speaker_id from the audio download response
include_webhook string No A publicly reachable URL. When the job completes or fails, the response will be POSTed to this URL. Test your URL first using POST /api/webhook/test.

The transcript_with_speaker_id is the transcript_speaker_id returned from the audio download endpoints.

Example responses

Success - Transcript ready

{
    "status": "success",
    "transcript_speaker_id": "01JW72M0AGW3M6R3QDCS30RD2P",
    "media_id": "Fqdz6A-5d04",
    "transcript_speaker_cost": "1.079",
    "data": {
        "transcriptsWithTimeStamps": [
            {
                "text": "Hello everyone, welcome to the show.",
                "start": 0.0,
                "duration": 2.5,
                "speaker": "Speaker 1"
            },
            {
                "text": "Thanks for having me.",
                "start": 2.5,
                "duration": 1.8,
                "speaker": "Speaker 2"
            }
        ],
        "language": "en",
        "duration": 6475.5
    }
}

Pending - Transcription in progress

{
    "status": "pending",
    "message": "Transcription in progress",
    "transcript_speaker_id": "01JW72M0AGW3M6R3QDCS30RD2P",
    "media_id": "Fqdz6A-5d04",
    "transcript_speaker_cost": "1.079"
}

Success - No speech detected

{
    "status": "success",
    "transcript_speaker_id": "01JW72M0AGW3M6R3QDCS30RD2P",
    "media_id": "Fqdz6A-5d04",
    "transcript_speaker_cost": "1.079",
    "data": {
        "transcriptsWithTimeStamps": [],
        "duration": 0,
        "message": "No speech detected in audio"
    }
}

Audio still processing

{
    "status": "pending",
    "message": "Audio download in progress and is required before transcription",
    "transcript_speaker_id": "01JW72M0AGW3M6R3QDCS30RD2P"
}

Error responses

Rate Limiting

The API has a rate limit of 150 requests per minute.

Support

If you need assistance or have any questions about using the API, please contact our support team at https://transcriptdownloader.com/#contact.