apyhub
▣ FILE CONVERSION · FILE MANIPULATION

Compress Video Job API

Hosted on ApyHub

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.

▣ ENDPOINT 01 / 03
POST
Submit file
http://localhost:8080/apyhub/compress-video-job/file-to-json
QUICKSTARTGUIDE

Quickstart

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

curl -X POST "http://localhost:8080/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.

{
  "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 compression as an asynchronous job and returns a job identifier immediately. The request includes the source video file and can optionally set whether the job is persistent.

Query Parameter(s)

AttributeTypeMandatoryDescription
persistentBooleanNoWhether the submitted job is persistent.

Request Body

ParameterTypeMandatoryDescription
videoStringYesSource video file. Binary file 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 required job_id string field — a UUID job identifier for status polling. The endpoint returns the job identifier directly at the top level, not wrapped in data.

ParameterTypeMandatoryDescription
job_idStringYesJob identifier for status polling. UUID format.

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 field from the top-level response.

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 03 / 03
POST
Submit url
http://localhost:8080/apyhub/compress-video-job/url-to-json
QUICKSTARTGUIDE

Quickstart

Submit a video URL to start an async compression job.

curl -X POST "http://localhost:8080/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.

{
  "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 a video compression job using a source video URL and returns a job identifier immediately. The compression request is processed asynchronously; the submitted job can then be polled using the returned job_id.

Query Parameter(s)

AttributeTypeMandatoryDescription
persistentBooleanNoWhether the job should be 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 — the job identifier for status polling. The response is not wrapped in data.

ParameterTypeMandatoryDescription
job_idStringYesJob identifier for status polling. Format: UUID.

Notes

This endpoint kicks off an async job and returns immediately with the job_id 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.

Query parameters

Name
Type
Description
persistentOPTIONAL
boolean
—

Body

Name
Type
Description
bodyREQUIRED
object
—
▣ ENDPOINT 02 / 03
GET
Check video compression job status
http://localhost:8080/apyhub/compress-video-job/jobs/:job_id
QUICKSTARTGUIDE

Quickstart

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

curl -X GET "http://localhost:8080/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.

{
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "successful",
    "url": "https://assets.apyhub.com/samples/sample.mp4"
  }
}
TRY ITLIVE · 5 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.

About this endpoint

What it does

Checks the status of a video compression job by job ID and returns the job record in a JSON object. When the job is successful, the response can include a url for the compressed output.

Path Parameter(s)

AttributeTypeMandatoryDescription
job_idStringYesJob identifier in UUID format.

Response

Returns a JSON object with a data object field containing job_id (string), status (string enum: pending, successful, failed), message (string), and url (string URI, present when status is successful). Success status code is not declared in the schema.

AttributeTypeMandatoryDescription
dataObjectNoJob status payload.
data.job_idStringNoJob identifier in UUID format.
data.statusENUMNoJob state. Allowed values: pending while submitted or processing, successful when output is ready, failed when the worker marked the job failed.
data.messageStringNoHuman-readable status for pending or failed responses.
data.urlStringNoPresigned or CDN URL to the job output. Present when status is successful. Format: URI.

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
CatalogPricingBecome a providerStatus (opens in new tab)
Company
AboutBlogCareers (opens in new tab)Contact
Legal
Terms of ServicePrivacy PolicyProvider terms
© 2026 APYHUB · BUILT FOR DEVELOPERS