How to Download a Video with a Specific Format ID Using ReClip: A Complete API Guide

To download a video with a specific format ID using ReClip, retrieve available formats via POST /api/info, submit your chosen format_id to POST /api/download, and poll GET /api/status/<job_id> until the job completes.

ReClip is a lightweight Flask-based service that wraps yt-dlp to provide a RESTful API for media downloads. According to the averygan/reclip source code, the application exposes yt-dlp's internal format identifiers through a structured JSON workflow, enabling precise control over video quality selection. This guide walks through the exact API calls and implementation details found in app.py to help you programmatically download specific video renditions.

Understanding the ReClip Download Workflow

The ReClip service orchestrates video downloads through a three-step process that separates metadata retrieval from the actual download execution. This design allows clients to inspect available quality options before committing bandwidth to a specific format.

The Three-Step Process

1. Metadata Extraction – Query the video URL to retrieve a list of available format IDs and their corresponding resolutions.
2. Format Selection – Choose a specific format_id from the list (such as "136" for 720p) and submit it to the download endpoint.
3. Job Monitoring – Poll the job status endpoint until the download completes, then retrieve the file.

Step 1: Retrieve Available Format IDs

Before downloading, you must call the POST /api/info endpoint to inspect the available streams. According to the implementation in app.py (lines 12-30), this endpoint iterates over info["formats"] returned by yt-dlp and extracts the highest-bitrate stream for each resolution.

Each format object in the response contains an id field representing the yt-dlp format identifier, alongside human-readable labels like "720p".

Submit your target URL to the info endpoint:

POST /api/info HTTP/1.1
Content-Type: application/json

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

The API returns a JSON object containing the video metadata and available formats:

{
  "title": "Example Video",
  "thumbnail": "https://i.ytimg.com/vi/example/hqdefault.jpg",
  "duration": 125,
  "uploader": "Channel Name",
  "formats": [
    {"id": "137", "label": "1080p", "height": 1080},
    {"id": "136", "label": "720p", "height": 720},
    {"id": "135", "label": "480p", "height": 480}
  ]
}

Extract the id value from your desired format object to use in the next step.

Step 2: Submit Your Format ID for Download

Once you have selected a format ID, submit it to the POST /api/download endpoint. As implemented in app.py (lines 66-84), this endpoint accepts the URL, format type ("video" or "audio"), and the optional format_id parameter.

The request must include:

• url: The video URL
• format: Either "video" or "audio"
• format_id: The specific yt-dlp format identifier (e.g., "136")
• title: The video title for filename generation

Send the download request with your selected format ID:

POST /api/download HTTP/1.1
Content-Type: application/json

{
  "url": "https://www.youtube.com/watch?v=example",
  "format": "video",
  "format_id": "136",
  "title": "Example Video"
}

The API immediately returns a job identifier for tracking:

{
  "job_id": "a1b2c3d4e5"
}

This job_id represents a temporary job record stored by the Flask application while a background thread processes the download.

Step 3: Monitor and Retrieve the Download

ReClip handles downloads asynchronously. After initiating the job, you must poll the status endpoint until the download completes.

Query the job status using GET /api/status/<job_id>:

GET /api/status/a1b2c3d4e5 HTTP/1.1

A completed job returns the following response:

{
  "status": "done",
  "error": null,
  "filename": "Example Video.mp4"
}

Once the status indicates "done", retrieve the actual file:

GET /api/file/a1b2c3d4e5 HTTP/1.1

The server responds with the MP4 file attachment named according to the title provided in your original request.

How ReClip Handles Format Selection Internally

The format ID processing occurs within the run_download() function in app.py (lines 38-44). When you provide a format_id, the application constructs a yt-dlp command string that forces the specific video stream while automatically selecting the best available audio track.

The command assembly logic follows this pattern:

• If format_id is provided: The command uses -f "<format_id>+bestaudio/best" and forces MP4 output.
• If format_choice is "audio": The command extracts audio-only.
• Default behavior: Uses "bestvideo+bestaudio" selector.

This implementation ensures that your specified format ID takes precedence for the video stream, while the audio stream is automatically merged to produce a complete MP4 file.

Summary

• Retrieve metadata first by calling POST /api/info to get available format IDs from the formats array.
• Submit downloads to POST /api/download with the specific format_id parameter to force a particular quality level.
• Monitor progress via GET /api/status/<job_id> until the status returns "done".
• Fetch the file from GET /api/file/<job_id> once processing completes.
• Internal implementation in app.py passes your format ID to yt-dlp using the -f flag with automatic audio merging.

Frequently Asked Questions

What is a format ID in ReClip?

A format ID is the unique identifier string assigned by yt-dlp to a specific video stream rendition (such as "137" for 1080p or "136" for 720p). ReClip exposes these IDs through the /api/info endpoint, allowing you to select exact quality levels rather than relying on generic "best" or "worst" selectors.

Can I download audio-only with a specific format ID?

Yes. When calling POST /api/download, set the format parameter to "audio". However, according to the run_download() implementation in app.py, specifying a format_id alongside "audio" will still prioritize that specific stream; for pure audio extraction, omit the format_id to let yt-dlp select the best audio stream automatically.

How do I check the status of my download job?

Send a GET request to /api/status/<job_id> where <job_id> is the UUID returned by the download endpoint. The endpoint returns a JSON object with a status field that progresses from pending states to "done" when the file is ready, or "error" if the download failed.

What file format does ReClip output?

ReClip forces MP4 output for all video downloads when a specific format_id is provided. The run_download() function in app.py explicitly configures yt-dlp to merge the selected video stream with the best available audio into an MP4 container, regardless of the original source format.

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