API Documentation

Learn how to integrate Transcriptly's API into your application and generate transcripts programmatically.

Last updated: December 25, 2025

Getting Started

Transcriptly provides a RESTful API that allows you to generate transcripts from YouTube videos programmatically.

Base URL

All API requests should be made to:

https://transcriptly.org/api/v1

API Key Authentication

All API requests require authentication using an API key. You can create and manage your API keys in the API Keys section of your dashboard.

API Key Header

Include your API key in the request header:

X-API-Key: your_api_key_here

Getting Your API Key

Sign in to your Transcriptly account
Navigate to the API Keys page in your dashboard
Click "Create API Key" to generate a new key
Copy your API key and store it securely

Note: You can create multiple API keys for different applications or environments. Each key can be individually revoked if needed.

Best Practices

Recommended workflow for using the API efficiently.

Recommended Workflow

Get video information first - Call /video-info to see video details and available languages (1 credit)
Let user choose language - Display available languages to users and let them select
Fetch transcript - Call /transcript with the selected language (1 credit)

Note: If you already know the video has a specific language, you can skip step 1 and directly call /transcript. However, calling /video-info first is recommended to avoid wasting credits on unavailable languages.

1. Get Video Information

Get video metadata and available transcript languages.

POST

/video-info

Request Body

{
  "url": "string (required) - YouTube video URL"
}

Response

{
  "code": 200,
  "message": "success",
  "data": {
    "videoDetails": {
      "title": "string",
      "description": "string",
      "author": "string",
      "authorUrl": "string",
      "thumbnailUrl": "string",
      "lengthSeconds": number
    },
    "availableLanguages": [
      {
        "code": "string",
        "name": "string",
        "isGenerated": boolean
      }
    ]
  }
}

Response Fields

Field	Type	Description
data.videoDetails.title	string	Video title
data.videoDetails.description	string	Video description
data.videoDetails.author	string	Channel name / author
data.videoDetails.authorUrl	string	Channel URL, if not available, it will be empty string
data.videoDetails.thumbnailUrl	string	Video thumbnail image URL
data.videoDetails.lengthSeconds	number	Video duration in seconds
data.availableLanguages[].code	string	ISO language code (e.g., "en", "pt", "es")
data.availableLanguages[].name	string	Full name of available language (e.g., "English", "Portuguese")
data.availableLanguages[].isGenerated	boolean	Currently not used, can be ignored

Credits

This endpoint consumes 1 credit per request. Use this to check video information and available languages before fetching transcripts.

2. Get Transcript

Get transcript content for a specific language.

POST

/transcript

Request Body

{
  "url": "string (required) - YouTube video URL",
  "language": "string (optional) - Language code, defaults to 'en'"
}

Request Parameters

Parameter	Type	Required	Description
url	string	Yes	The YouTube video URL. Must be a valid YouTube video URL in one of these formats: https://youtube.com/watch?v=VIDEO_ID https://www.youtube.com/watch?v=VIDEO_ID
language	string	No	The language code for the transcript. If not specified, defaults to "en" (English). Common language codes: en (English), es (Spanish), fr (French), de (German), ja (Japanese), zh (Chinese)

Example Request in Postman

Headers

Request Body

These examples show how to configure the request in Postman, including the required API key header and request body parameters.

Response (Success)

{
  "code": 200,
  "message": "success",
  "data": {
    "language": "string",
    "languageName": "string",
    "segments": [
      {
        "id": number,
        "text": "string",
        "startMs": number,
        "endMs": number,
        "startTimeText": "string"
      }
    ],
    "availableLanguages": [
      {
        "code": "string",
        "name": "string",
        "isGenerated": boolean
      }
    ]
  }
}

Response (No Transcript Available)

{
  "code": 404,
  "message": "No transcript available for this video",
  "data": {
    "availableLanguages": [...]
  }
}

Note: Credits are consumed even when no transcript is available, as the API call has been made.

Response Fields

Field	Type	Description
data.language	string	ISO language code (e.g., "en", "pt-BR")
data.languageName	string	Full name of the transcript language (e.g., "English", "Portuguese (BR)")
data.segments[].id	number	Unique identifier for the transcript segment
data.segments[].text	string	Transcript text content
data.segments[].startMs	number	Start time in milliseconds
data.segments[].endMs	number	End time in milliseconds
data.segments[].startTimeText	string	Formatted start time (e.g., "00:01:23")
data.availableLanguages[].code	string	ISO language code
data.availableLanguages[].name	string	Full name of available language
data.availableLanguages[].isGenerated	boolean	Currently not used, can be ignored

Rate Limits

Requests are limited based on your subscription plan. Rate limit information is included in the response headers:

X-RateLimit-Limit: Maximum requests per hour
X-RateLimit-Reset: Time when the rate limit resets

Credits

This endpoint consumes 1 credit per request, regardless of success or failure. The number of credits consumed is returned in the X-Credits-Consumed header.

Important: Credits are consumed even if the requested language is not available. We recommend calling /video-info first to check available languages.

Code Examples

Examples of using the API in different programming languages.

JavaScript / Node.js

// Step 1: Get video information
const videoInfoResponse = await fetch('https://transcriptly.org/api/v1/video-info', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    url: 'https://www.youtube.com/watch?v=VIDEO_ID'
  })
});

const videoInfo = await videoInfoResponse.json();
console.log('Available languages:', videoInfo.data.availableLanguages);

// Step 2: Get transcript for a specific language
const transcriptResponse = await fetch('https://transcriptly.org/api/v1/transcript', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    url: 'https://www.youtube.com/watch?v=VIDEO_ID',
    language: 'en'
  })
});

const transcript = await transcriptResponse.json();
console.log('Transcript segments:', transcript.data.segments);

Python

import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://transcriptly.org/api/v1"

# Step 1: Get video information
video_info_response = requests.post(
    BASE_URL + "/video-info",
    headers={"X-API-Key": API_KEY},
    json={"url": "https://www.youtube.com/watch?v=VIDEO_ID"}
)
video_info = video_info_response.json()
print("Available languages:", video_info["data"]["availableLanguages"])

# Step 2: Get transcript
transcript_response = requests.post(
    BASE_URL + "/transcript",
    headers={"X-API-Key": API_KEY},
    json={
        "url": "https://www.youtube.com/watch?v=VIDEO_ID",
        "language": "en"
    }
)
transcript = transcript_response.json()
print("Transcript segments:", transcript["data"]["segments"])

cURL

# Step 1: Get video information
curl -X POST https://transcriptly.org/api/v1/video-info \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"url": "https://www.youtube.com/watch?v=VIDEO_ID"}'

# Step 2: Get transcript
curl -X POST https://transcriptly.org/api/v1/transcript \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"url": "https://www.youtube.com/watch?v=VIDEO_ID", "language": "en"}'

Error Codes

Possible error responses from the API.

400

Bad Request - Invalid parameters

401

Unauthorized - Invalid or missing API key

403

Forbidden - Insufficient credits

404

Not Found - Video or transcript not found

429

Too Many Requests - Rate limit exceeded

500

Internal Server Error

4001

Invalid URL - Invalid YouTube URL format

4002

No Transcript - No transcript available for this video

4003

Insufficient Credits - Not enough credits to generate transcript

4004

Invalid Parameters - Invalid request parameters

5001

API Error - External service error