API reference

The Video Encoder API lets you upload source files, start transcoding jobs and fetch the results from your own code. It uses JSON over HTTPS, standard HTTP status codes and bearer-token authentication.

All endpoints live under one base URL:

https://video-encoder.net/api/v1

Request and response bodies are JSON encoded in UTF-8, except file uploads and downloads. Timestamps are ISO 8601 in UTC. Sizes are in bytes, durations in seconds and bitrates in bits per second.

API access is included in the Studio plan and enabled for all accounts during the closed beta.

Authentication

Create an API key in the dashboard under Settings → API keys. Keys start with ve_live_ and are shown only once. Send the key in the Authorization header of every request:

curl https://video-encoder.net/api/v1/jobs \
  -H "Authorization: Bearer ve_live_••••••••••••••••"

A request without a valid key is rejected with status 401:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api"
Content-Type: application/json

{"error":{"type":"authentication_error","code":"invalid_api_key","message":"Missing or invalid API key. Send your key in the Authorization header as a Bearer token."},"request_id":"4b1e9f6c0d2a7e3f8a5b6c7d8e9f0a1b"}

Keep keys on your server. Never put them in browser or mobile app code.

Uploads

A job can read its source from a public URL or from a file you upload first. Uploads are resumable: create an upload, then send the file in one or more parts.

POST/api/v1/uploads
curl https://video-encoder.net/api/v1/uploads \
  -H "Authorization: Bearer $VE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "interview.mov", "size": 4402341888}'

{
  "id": "upl_3n7c0b2wq4",
  "upload_url": "https://video-encoder.net/api/v1/uploads/upl_3n7c0b2wq4/data",
  "part_size": 67108864,
  "expires_at": "2026-11-13T09:40:12Z"
}
PUT/api/v1/uploads/{id}/data

Send each part with a Content-Range header. After an interruption, request GET /api/v1/uploads/{id} to see how many bytes were received and continue from there. The upload is complete when the last byte arrives.

curl -X PUT https://video-encoder.net/api/v1/uploads/upl_3n7c0b2wq4/data \
  -H "Authorization: Bearer $VE_API_KEY" \
  -H "Content-Range: bytes 0-67108863/4402341888" \
  --data-binary @part-000.bin

Create a job

POST/api/v1/jobs
FieldTypeDescription
inputstringUpload ID (upl_…) or an HTTPS URL we can download the source from. Required.
presetstringPreset ID, see Presets. Required unless output is given.
outputobjectManual settings: container, video (codec, width, height, crf or bitrate, fps) and audio (codec, bitrate, channels). Fields set here override the preset.
webhook_urlstringHTTPS URL that receives job events.
metadataobjectUp to 20 string keys and values of your own, returned with the job.
curl https://video-encoder.net/api/v1/jobs \
  -H "Authorization: Bearer $VE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "upl_3n7c0b2wq4",
    "preset": "web-vp9",
    "output": {"video": {"height": 720, "crf": 32}},
    "metadata": {"episode": "42"}
  }'

The response is the new job object with status queued and status code 201.

Retrieve a job

GET/api/v1/jobs/{id}

A job moves through queued, processing and then completed or failed. While it is processing, progress goes from 0 to 100.

{
  "id": "job_8f2kq1x9vd",
  "status": "completed",
  "progress": 100,
  "preset": "youtube-1080p",
  "input": {
    "filename": "interview.mov",
    "size": 4402341888,
    "duration": 1514.2,
    "video": { "codec": "prores", "width": 1920, "height": 1080, "fps": 25 }
  },
  "output": {
    "container": "mp4",
    "size": 641728512,
    "video": { "codec": "h264", "width": 1920, "height": 1080, "bitrate": 3016000 },
    "audio": { "codec": "aac", "bitrate": 384000, "channels": 2 },
    "ssim": 0.987
  },
  "billed_minutes": 26,
  "created_at": "2026-11-12T09:41:07Z",
  "completed_at": "2026-11-12T09:52:44Z",
  "expires_at": "2026-11-15T09:52:44Z"
}

List jobs

GET/api/v1/jobs?status=completed&limit=20

Returns jobs from newest to oldest in data. Filter by status; page with limit (up to 100) and the next_cursor value from the previous page passed as cursor.

Download the output

GET/api/v1/jobs/{id}/output

Redirects with 302 to a signed download link that is valid for one hour. Range requests are supported, so downloads can be resumed. For HLS jobs the link points to a ZIP archive with the playlists and segments.

curl -L -o interview-1080p.mp4 \
  -H "Authorization: Bearer $VE_API_KEY" \
  https://video-encoder.net/api/v1/jobs/job_8f2kq1x9vd/output

Cancel or delete a job

DELETE/api/v1/jobs/{id}

Cancels a queued or processing job, or deletes the files of a finished one before the retention period ends. Cancelled jobs are not billed. Returns 204 with no body.

Presets

GET/api/v1/presets

Returns all presets with their full settings, including the ones you saved in the dashboard. Built-in presets:

IDOutput
youtube-1080pMP4, H.264 High, 1080p, AAC 384 kbps
youtube-2160pMP4, H.264 High, 4K, AAC 384 kbps
mobile-720pMP4, H.264 Main, 720p, AAC 128 kbps
web-vp9WebM, VP9, 1080p, Opus 128 kbps
web-av1WebM, AV1, 1080p, Opus 128 kbps
vertical-1080MP4, H.264, 1080×1920, AAC 192 kbps
archive-hevcMKV, HEVC Main 10, source resolution, FLAC
hls-abrHLS, H.264, 1080p / 720p / 480p, AAC
audio-aacM4A, AAC 192 kbps, loudness normalised

Webhooks

If a job has a webhook_url, we send a POST request with a JSON body when the job reaches completed or failed. The events are job.completed and job.failed; the body contains the event type and the full job object.

{
  "type": "job.completed",
  "created_at": "2026-11-12T09:52:45Z",
  "data": { "id": "job_8f2kq1x9vd", "status": "completed", … }
}

Every request carries a VE-Signature header of the form t=1794477165,v1=…. To verify it, compute an HMAC-SHA256 of t, a dot and the raw request body with your webhook secret from the dashboard, and compare it with v1. Reject requests older than five minutes.

Answer with any 2xx status within 10 seconds. Otherwise we retry with exponential backoff for up to 24 hours.

Errors

Errors use standard HTTP status codes and a JSON body with an error object and a request_id. Include the request ID when you report a problem.

StatusTypeMeaning
400invalid_requestA field is missing or has a wrong value. error.param names the field.
401authentication_errorThe API key is missing, revoked or wrong.
402quota_exceededThe plan has no minutes left and extra minutes are disabled.
404not_foundThe job or upload does not exist or has expired.
409conflictThe job is in a state that does not allow this action.
413file_too_largeThe source is larger than your plan allows.
422unsupported_mediaThe source could not be decoded.
429rate_limitedToo many requests, see below.
5xxapi_errorSomething went wrong on our side. Retry the request later.

Rate limits

Each API key can make 120 requests per minute and run up to 10 jobs at the same time; further jobs wait in the queue. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. When the limit is exceeded, the API answers 429 with a Retry-After header in seconds.