apyhub
▣ FILE CONVERSION

Compress Video Job API

What it does

Video Compressor lets you submit a video file or a video URL, set a compression percentage, and get back an async job you can poll for the compressed result.

Use POST /file-to-json when you already have the source video as multipart file upload, or POST /url-to-json when the video lives at an HTTP(S) URL. In both cases, compression_percentage is a string from 0 to 100; if you omit it or send an empty value, the service defaults to 50. The upload endpoint accepts video, and the URL endpoint accepts video_url.

Each successful submission returns a job_id immediately. Check GET /jobs/:job_id to follow the job state. The status response includes job_id, status, and, when the job finishes successfully, a url for the compressed output. If the job is still running or has failed, you also get a human-readable message.

Use Video Compressor when you need to shrink uploaded assets before storage, reduce bandwidth for previews, or normalize delivery files in a media workflow.

▣ ENDPOINT 01 / 03
POST
Submit video compression job (multipart file)
https://api.eu.apyverse.com/apyhub/compress-video/file-to-json

QUICKSTART

GUIDE

Quickstart

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

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

What you'll get back

Returns a JSON object with a job_id string field, which is the UUID of the async job you can use for status polling.

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}
TRY ITLIVE · 400 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.
Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.
body*
Source video file.
Integer **0–100**. Omitted or empty defaults to **50**. Invalid non-numeric or out-of-range values return **400**.

About this endpoint

What it does

Submits a video file for asynchronous compression and returns a job identifier immediately. The uploaded file is sent in the request body, and the optional query parameter controls whether the job is persistent.

Query Parameter(s)

AttributeTypeMandatoryDescription
persistentBooleanNoWhether the compression job is persistent.

Request Body

ParameterTypeMandatoryDescription
videoStringYesSource video file. Binary upload.
compression_percentageStringNoInteger 0–100. Omitted or empty defaults to 50. Invalid non-numeric or out-of-range values return 400.

Response

Returns a JSON object with a job_id string field formatted as a UUID. This identifier is returned immediately after a successful async video job submission and is used for status polling.

ParameterTypeMandatoryDescription
job_idStringYesJob identifier for status polling. Format: UUID.

Notes

This endpoint kicks off an async job and returns immediately with a job identifier; the actual work runs in the background. Pair this call with the corresponding job_check endpoint — poll that until the status reaches a terminal state to retrieve the result. Extract the job_id value from the response body.

Query parameters

Name
Type
Description
persistentOPTIONAL
boolean
—

Body

Name
Type
Description
bodyREQUIRED
object
—

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ ENDPOINT 02 / 03
POST
Submit video compression job (source URL)
https://api.eu.apyverse.com/apyhub/compress-video/url-to-json

QUICKSTART

GUIDE

Quickstart

Submit a video URL to start an asynchronous compression job.

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

What you'll get back

Returns a JSON object with a job_id string field containing the UUID of the created job for later status polling.

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}
TRY ITLIVE · 400 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.
body*
HTTP(S) URL of the source video to download and compress.
Integer 0–100 as a string. Omitted or empty defaults to **50**. Maps to FFmpeg CRF `30 + (percentage / 4)`.

About this endpoint

What it does

Submits an asynchronous video compression job using a source video URL and returns a job identifier immediately. The request body carries the source URL and optional compression percentage; the response contains the job ID you use to poll for completion.

Query Parameter(s)

AttributeTypeMandatoryDescription
persistentBooleanNoControls whether the job is persistent.

Request Body

ParameterTypeMandatoryDescription
video_urlStringYesHTTP(S) URL of the source video to download and compress. Format: URI.
compression_percentageStringNoInteger 0–100 as a string. Omitted or empty defaults to 50. Maps to FFmpeg CRF 30 + (percentage / 4).

Response

Returns a JSON object with a job_id string field — a UUID job identifier for status polling.

ParameterTypeMandatoryDescription
job_idStringYesJob identifier for status polling. Format: UUID.

Notes

This endpoint kicks off an async job and returns immediately with a job identifier; the actual work runs in the background. Pair this call with the corresponding job_check endpoint — poll that until the status reaches a terminal state to retrieve the result. Use the returned job_id value for polling.

Query parameters

Name
Type
Description
persistentOPTIONAL
boolean
—

Body

Name
Type
Description
bodyREQUIRED
object
—
▣ ENDPOINT 03 / 03
GET
Check video compression job status
https://api.eu.apyverse.com/apyhub/compress-video/jobs/:job_id

QUICKSTART

GUIDE

Quickstart

Check the status of a compression job by its UUID.

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

What you'll get back

Returns a JSON object with a data object. Inside data, job_id is the job UUID, status is one of pending, successful, or failed, message is a human-readable status, and url is present when the job is successful.

{
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "successful",
    "url": "https://assets.apyhub.com/samples/sample.mp4"
  }
}
TRY ITLIVE · 1 ATOM
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Checks the current status of a video compression job by job_id and returns the job metadata in a data object. When the job has completed successfully, the response can include a url to the compressed video output.

Path Parameter(s)

AttributeTypeMandatoryDescription
job_idStringYesJob identifier in UUID format.

Response

Returns a JSON object with a data object field. The data object contains job_id as a UUID string, status as a string enum, and may include url and message depending on the job state.

ParameterTypeMandatoryDescription
dataObjectNoJob status payload. Contains job_id, status, and may include url when status is successful, and message for pending or failed responses.
data.job_idStringNoJob identifier in UUID format.
data.statusENUMNoJob state. Allowed values: pending, successful, failed. pending while submitted or processing; successful when output is ready; failed when the worker marked the job failed.
data.urlStringNoPresigned or CDN URL to the job output. Present when status is successful. URI format.
data.messageStringNoHuman-readable status message for pending or failed responses.

Path parameters

Name
Type
Description
job_idREQUIRED
string
—
▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.

Product
CatalogPricingQuickstartBecome a providerStatus (opens in new tab)
Company
AboutBlogCareers (opens in new tab)Contact
Legal
Terms of ServicePrivacy PolicyProvider terms
© 2026 APYHUB · BUILT FOR DEVELOPERS