How to Get Video Metadata Using the ReClip API: A Complete Guide

Send a POST request to the /api/info endpoint with a JSON payload containing the video URL to retrieve structured metadata including title, duration, thumbnail, uploader, and available stream formats.

The averygan/reclip repository provides a lightweight Flask backend that wraps yt-dlp (a maintained fork of youtube-dl) to simplify video metadata extraction. When you need to get video metadata using the ReClip API, the service executes background extraction via shell commands and returns a normalized JSON response suitable for downstream processing or frontend display.

How the ReClip API Extracts Video Metadata

ReClip functions as a thin wrapper around yt-dlp's JSON output mode. When a client submits a URL, the server executes the following command:

yt-dlp --no-playlist -j <url>

The -j flag forces JSON output per line, while --no-playlist restricts extraction to the single video URL provided. Inside app.py, the helper function parse_ytdlp_json (defined at lines 24-28) reads the first valid JSON line from yt-dlp's stdout and deserializes it into a Python dictionary. This approach keeps the API stateless and eliminates the need for persistent storage or caching layers.

The /api/info Endpoint Implementation

According to the source code in app.py, the /api/info route is implemented between lines 97-140. This endpoint accepts POST requests exclusively and expects a JSON body with a single key:

{
  "url": "https://www.youtube.com/watch?v=abc123"
}

The Flask server validates the presence of the URL parameter, invokes the yt-dlp subprocess, and constructs a concise response object. Because the logic resides entirely within this route handler, the API can be deployed as a microservice without external database dependencies.

Response Schema and Format Deduplication

The JSON response returned by the ReClip API contains five primary fields:

• title: The video title extracted via info.get("title")
• thumbnail: Direct URL to the default preview image
• duration: Total length in seconds as an integer
• uploader: Channel name or username string
• formats: Array of available streams with deduplicated resolutions

Each entry in the formats array includes:

• id: The yt-dlp format identifier (e.g., "136")
• label: Human-readable resolution (e.g., "720p")
• height: Integer pixel height (e.g., 720)

As implemented in lines 13-28 of the endpoint logic (within app.py), ReClip deduplicates formats to return only the best-quality stream per resolution, reducing payload size while preserving all available quality tiers.

Practical Code Examples

Retrieving Metadata with cURL

Use the following command to test the API from any terminal:

curl -X POST https://your-reclip-host/api/info \
     -H "Content-Type: application/json" \
     -d '{"url":"https://www.youtube.com/watch?v=abc123"}'

Fetching Data with Python Requests

For Python applications, use the requests library to parse the response:

import requests

resp = requests.post(
    "http://localhost:8899/api/info",
    json={"url": "https://www.youtube.com/watch?v=abc123"},
)
data = resp.json()

print("Title:", data["title"])
print("Duration (s):", data["duration"])
print("Available formats:")
for fmt in data["formats"]:
    print(f"  {fmt['label']} (id={fmt['id']})")

Querying from JavaScript

Modern browser environments or Node.js can utilize the Fetch API:

fetch("/api/info", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://www.youtube.com/watch?v=abc123" })
})
  .then(r => r.json())
  .then(info => {
    console.log(info.title);
    console.log(info.formats);
  });

Deployment Dependencies

Running the ReClip API locally requires the dependencies listed in requirements.txt, specifically Flask and yt-dlp. The README.md file in the repository root contains platform-specific installation instructions and quick-start commands. No additional configuration files or environment variables are mandatory for basic metadata retrieval operations.

Summary

• The ReClip API exposes a single POST endpoint at /api/info to extract video metadata using yt-dlp.
• Response construction and format deduplication logic reside in app.py (lines 97-140 for the route, with helper functions at lines 24-28).
• The API returns title, thumbnail, duration, uploader, and a deduplicated array of stream formats.
• Stateless architecture allows deployment without databases; dependencies are limited to Flask and yt-dlp per requirements.txt.

Frequently Asked Questions

What authentication is required to use the ReClip API?

The ReClip API does not implement authentication in the open-source version available in the averygan/reclip repository. Any HTTP client can POST to /api/info without API keys or tokens, making it suitable for internal networks or development environments where security constraints are handled at the network layer.

Why does the formats array exclude some resolution options?

ReClip intentionally deduplicates formats to return only the highest-quality stream available for each resolution tier. According to the source code analysis, this logic executes within the /api/info endpoint implementation, ensuring the response contains unique entries for resolutions like 720p or 480p without redundant bitrate variants.

Can I modify which metadata fields are returned?

Yes. Since the response building logic is contained in app.py between lines 97-140, you can fork the repository and modify the dictionary construction to include additional yt-dlp fields such as view_count, upload_date, or description. The parse_ytdlp_json function at lines 24-28 provides the raw data object from which you can extract any available metadata key.

Is the ReClip API suitable for high-volume production use?

The current implementation runs as a single Flask process without built-in rate limiting, request queuing, or caching. While suitable for low-to-moderate traffic, high-volume production deployments should implement a reverse proxy (like Nginx), a caching layer (Redis), or a task queue (Celery) in front of the API to prevent yt-dlp subprocesses from overwhelming server resources.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}