---
title: Compress Video Job API
slug: compress-video-job
url: https://apyhub.com/apyhub/service/compress-video-job
provider: ApyHub
categories: [Media Kit]
tags: [compress, job, video]
auth: api_key
version: 1.0
service_type: job
endpoints: 3
atoms: 5-400
mcp: true
alias: job-compress-video
---

# Compress Video Job API

Compress large videos from a file upload or URL as a background job. Poll for status and get a downloadable output when processing succeeds.

## Endpoints

| Method | URL | Description | Atoms |
| --- | --- | --- | --- |
| POST | `https://api.eu.apyhub.com/apyhub/compress-video-job/file-to-json` | What it does Submits a video file for compression as an asynchronous job and returns a job identifi… | 400 |
| GET | `https://api.eu.apyhub.com/apyhub/compress-video-job/jobs/:job_id` | What it does Checks the status of a video compression job by job ID and returns the job record in a… | 5 |
| POST | `https://api.eu.apyhub.com/apyhub/compress-video-job/url-to-json` | What it does Submits a video compression job using a source video URL and returns a job identifier… | 400 |

## Endpoint reference

### Submit file

`POST https://api.eu.apyhub.com/apyhub/compress-video-job/file-to-json` · 400 atoms · accepts `multipart/form-data` · returns `application/json`

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `video` | body | string (binary) | yes | Source video file. |
| `compression_percentage` | body | string | no | Integer 0–100. Omitted or empty defaults to 50. Invalid non-numeric or out-of-range values return 400. |
| `persistent` | query | boolean | no |  |

#### Quickstart

Upload a video file to start a compression job and get back a job ID.

```bash
curl -X POST "https://api.eu.apyhub.com/apyhub/compress-video-job/file-to-json" \
  -H "apy-token: $APY_TOKEN" \
  -F "video=@/path/to/video.mp4"
```

#### What you'll get back

Returns a JSON object with a required `job_id` string field containing the job identifier for status polling.

```json
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### Check video compression job status

`GET https://api.eu.apyhub.com/apyhub/compress-video-job/jobs/:job_id` · 5 atoms · accepts `application/json` · returns `application/json`

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `job_id` | path | string (uuid) | yes |  |

#### Quickstart

Check the status of a video compression job by its job ID.

```bash
curl -X GET "https://api.eu.apyhub.com/apyhub/compress-video-job/jobs/:job_id" \
  -H "apy-token: $APY_TOKEN" 
```

#### What you'll get back

Returns a JSON object with a `data` object. That `data` object can include `job_id` and `status` for every response, and `url` and `message` when available.

```json
{
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "successful",
    "url": "https://assets.apyhub.com/samples/sample.mp4"
  }
}
```

### Submit url

`POST https://api.eu.apyhub.com/apyhub/compress-video-job/url-to-json` · 400 atoms · accepts `application/json` · returns `application/json`

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `video_url` | body | string (uri) | yes | HTTP(S) URL of the source video to download and compress. Example: `https://assets.apyhub.com/samples/sample.mp4`. |
| `compression_percentage` | body | string | no | Integer 0–100 as a string. Omitted or empty defaults to 50. Maps to FFmpeg CRF 30 + (percentage / 4). |
| `persistent` | query | boolean | no |  |

#### Quickstart

Submit a video URL to start an async compression job.

```bash
curl -X POST "https://api.eu.apyhub.com/apyhub/compress-video-job/url-to-json" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "video_url": "https://assets.apyhub.com/samples/sample.mp4",
  "compression_percentage":"50" 
}'
```

#### What you'll get back

Returns a JSON object with a `job_id` string field — the UUID job identifier you can use for status polling.

```json
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

## About

## What it does
Video Compressor compresses a video file asynchronously and gives you a job ID for polling the result. Send either a source video file or a source video URL, choose an optional `compression_percentage` from 0 to 100, and check the job until the compressed file is ready.

Use `POST /file-to-json` when you already have the video as multipart upload, or `POST /url-to-json` when the source lives at an HTTP(S) URL. If you omit `compression_percentage`, the job defaults to 50. Both submission endpoints return a UUID `job_id` immediately, without wrapping it in `data`.

Poll `GET /jobs/:job_id` to read the job status. The response includes `job_id` and `status`, where `status` is `pending`, `successful`, or `failed`. When the job succeeds, the response also includes a presigned or CDN `url` to the output video. Failed and pending jobs include a human-readable `message`.

Video Compressor is a good fit for upload pipelines, media libraries, and workflows that need smaller video files before storage or delivery. Use it to reduce bandwidth, speed up playback, or prepare assets for downstream processing.

## Usage

Base URL: `https://api.eu.apyhub.com` (default region — see
`GET https://apyhub.com/api/public/regions` for the rest).

Authenticate with an ApyHub API key in the `apy-token` header.
Full docs and a live playground: https://apyhub.com/apyhub/service/compress-video-job
