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

> Easily get video metadata like title duration and thumbnail using the ReClip API. Send a POST request to the /api/info endpoint with your video URL to access structured data.

- Repository: [Avery Gan/reclip](https://github.com/averygan/reclip)
- Tags: how-to-guide
- Published: 2026-09-05

---

**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:

```bash
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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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:

```json
{
  "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`](https://github.com/averygan/reclip/blob/main/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:

```bash
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:

```python
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:

```javascript
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`](https://github.com/averygan/reclip/blob/main/requirements.txt)**, specifically **Flask** and **yt-dlp**. The **[`README.md`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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.