Media Extraction API

Enterprise-grade media extraction platform powered by yt-dlp. This API provides programmatic access to media metadata extraction from hundreds of supported platforms using the yt-dlp engine.

Note: This API extracts metadata only. It does not download, store, or host any media files. It returns information, metadata, and direct stream URLs obtained through the extraction engine.

Base URL

http://yt.girodev.it.com/api/v1

Quick Start

Get started in seconds with your API key:

1. Get your API Key

Create an API key from the admin dashboard (admin credentials required).

2. Make your first request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://yt.girodev.it.com/api/v1/media/info?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ"

3. View the response

{
  "success": true,
  "info": {
    "id": "dQw4w9WgXcQ",
    "title": "Rick Astley - Never Gonna Give You Up (Video)",
    "duration": 212,
    "uploader": "Rick Astley",
    "view_count": 1500000000,
    "extractor": "youtube"
  },
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

Authentication

The API uses API key authentication for all public endpoints. Include your API key in the Authorization header of every request.

Obtaining an API Key

API keys are managed through the admin dashboard (admin credentials required).

Using Your API Key

Include the key in the Authorization header using either format:

# Bearer format (recommended)
Authorization: Bearer ytg_abc123def456...

# Bare key format
Authorization: ytg_abc123def456...

Example Requests

cURL

curl -H "Authorization: Bearer ytg_abc123def456..." \
  "http://yt.girodev.it.com/api/v1/media/extract?url=https://www.youtube.com/watch?v=VIDEO_ID"

Python

import httpx

API_KEY = "ytg_abc123def456..."
BASE_URL = "http://yt.girodev.it.com/api/v1"

headers = {"Authorization": f"Bearer {API_KEY}"}
params = {"url": "https://www.youtube.com/watch?v=VIDEO_ID"}

response = httpx.get(
    f"{BASE_URL}/media/extract",
    headers=headers,
    params=params
)
print(response.json())

JavaScript

const API_KEY = "ytg_abc123def456...";
const BASE_URL = "http://yt.girodev.it.com/api/v1";

fetch(`${BASE_URL}/media/extract?url=https://www.youtube.com/watch?v=VIDEO_ID`, {
    headers: {
        "Authorization": `Bearer ${API_KEY}`
    }
})
.then(res => res.json())
.then(data => console.log(data));

Go

package main

import (
    "fmt"
    "net/http"
    "io"
)

func main() {
    url := "http://yt.girodev.it.com/api/v1/media/extract?url=https://www.youtube.com/watch?v=VIDEO_ID"
    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("Authorization", "Bearer ytg_abc123def456...")
    
    resp, _ := http.DefaultClient.Do(req)
    body, _ := io.ReadAll(resp.Body)
    defer resp.Body.Close()
    
    fmt.Println(string(body))
}

PHP

<?php
$client = new \GuzzleHttp\Client();
$response = $client->get('http://yt.girodev.it.com/api/v1/media/extract', [
    'headers' => [
        'Authorization' => 'Bearer ytg_abc123def456...'
    ],
    'query' => [
        'url' => 'https://www.youtube.com/watch?v=VIDEO_ID'
    ]
]);
echo $response->getBody();

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer ytg_abc123def456...");

var response = await client.GetAsync(
    "http://yt.girodev.it.com/api/v1/media/extract?url=https://www.youtube.com/watch?v=VIDEO_ID"
);
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://yt.girodev.it.com/api/v1/media/extract?url=https://www.youtube.com/watch?v=VIDEO_ID"))
    .header("Authorization", "Bearer ytg_abc123def456...")
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Rate Limits

Each API key has configurable rate limits to ensure fair usage of the platform. Rate limits are applied on both per-minute and per-day windows.

Rate Limit Headers

Every response includes rate limit information:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per minute
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit resets
`Retry-After`	Seconds to wait before retrying (on 429)

Rate Limit Exceeded

When you exceed your rate limit, the API returns:

HTTP 429 Too Many Requests

{
    "success": false,
    "error": "Rate limit exceeded. Please wait before making more requests.",
    "code": "rate_limit_exceeded",
    "details": {
        "retry_after": 45.2
    }
}

Media Extraction

These endpoints allow you to extract various types of information from media URLs. All endpoints require an API key.

Extract All Information

GET /api/v1/media/extract?url=https://www.youtube.com/watch?v=VIDEO_ID

Returns all available information including metadata, formats, and thumbnails.

Extract Video Formats Only

GET /api/v1/media/video?url=https://www.youtube.com/watch?v=VIDEO_ID

Returns only video format information.

Extract Audio Formats Only

GET /api/v1/media/audio?url=https://www.youtube.com/watch?v=VIDEO_ID

Returns only audio format information.

Extract Thumbnails

GET /api/v1/media/images?url=https://www.youtube.com/watch?v=VIDEO_ID

Returns all available thumbnails and images.

Extract Metadata Only

GET /api/v1/media/info?url=https://www.youtube.com/watch?v=VIDEO_ID

Returns only metadata (title, description, uploader, etc.) without formats or thumbnails.

Parameters

Parameter	Type	Required	Description
`url`	string	Yes	The media URL to extract information from (max 2048 chars)

Channels

Get Channel Information

GET /api/v1/channel/info?url=https://www.youtube.com/@ChannelName

Returns detailed information about a channel or uploader.

List Channel Videos

GET /api/v1/channel/videos?url=https://www.youtube.com/@ChannelName

Returns a list of videos from a channel.

Search

Search Media

GET /api/v1/search?query=never+gonna+give+you+up&limit=10

Search for media content across supported platforms.

Parameters

Parameter	Type	Required	Description
`query`	string	Yes	Search query (max 500 chars)
`limit`	integer	No	Number of results (1-50, default: 10)
`source`	string	No	Filter by platform (e.g., "youtube", "soundcloud")

Error Codes

HTTP Status	Code	Description
`400`	`bad_request`	Invalid request parameters
`400`	`unsupported_url`	The URL is not supported by the extraction engine
`400`	`extraction_failed`	Failed to extract media information
`400`	`extraction_timeout`	Extraction timed out (URL may be unreachable)
`401`	`missing_api_key`	No API key provided in Authorization header
`401`	`invalid_api_key`	The provided API key is invalid
`403`	`api_key_inactive`	The API key is deactivated
`429`	`rate_limit_exceeded`	Rate limit exceeded, slow down requests
`500`	`internal_server_error`	Unexpected server error

Supported Platforms

The API supports extraction from 100+ platforms through the yt-dlp engine, including:

Video: YouTube, Vimeo, Twitch, Dailymotion, Facebook Video, Twitter/X, Instagram, TikTok
Audio: SoundCloud, Bandcamp, Mixcloud, Audiomack
Live: Twitch, YouTube Live, Livestream
News: BBC, CNN, NBC, Fox News, CBS, ABC News, PBS
And many more...

For a complete list of supported platforms, check the OpenAPI schema.

General Endpoints

Health Check

GET /api/v1/health

Check the API health status.

Version Information

GET /api/v1/version

Get API version and server information.