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

> Learn to download video with specific format ID using ReClip API. Get format info, initiate download, and track job status for efficient video retrieval.

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

---

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

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

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

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

```json
{
  "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>`:

```http
GET /api/status/a1b2c3d4e5 HTTP/1.1

```

A completed job returns the following response:

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

```

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

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