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:
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.
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.
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" }
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
| Field | Type | Description |
|---|---|---|
input | string | Upload ID (upl_…) or an HTTPS URL we can download the source from. Required. |
preset | string | Preset ID, see Presets. Required unless output is given. |
output | object | Manual settings: container, video (codec, width, height, crf or bitrate, fps) and audio (codec, bitrate, channels). Fields set here override the preset. |
webhook_url | string | HTTPS URL that receives job events. |
metadata | object | Up 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
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
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
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
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
Returns all presets with their full settings, including the ones you saved in the dashboard. Built-in presets:
| ID | Output |
|---|---|
youtube-1080p | MP4, H.264 High, 1080p, AAC 384 kbps |
youtube-2160p | MP4, H.264 High, 4K, AAC 384 kbps |
mobile-720p | MP4, H.264 Main, 720p, AAC 128 kbps |
web-vp9 | WebM, VP9, 1080p, Opus 128 kbps |
web-av1 | WebM, AV1, 1080p, Opus 128 kbps |
vertical-1080 | MP4, H.264, 1080×1920, AAC 192 kbps |
archive-hevc | MKV, HEVC Main 10, source resolution, FLAC |
hls-abr | HLS, H.264, 1080p / 720p / 480p, AAC |
audio-aac | M4A, 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.
| Status | Type | Meaning |
|---|---|---|
400 | invalid_request | A field is missing or has a wrong value. error.param names the field. |
401 | authentication_error | The API key is missing, revoked or wrong. |
402 | quota_exceeded | The plan has no minutes left and extra minutes are disabled. |
404 | not_found | The job or upload does not exist or has expired. |
409 | conflict | The job is in a state that does not allow this action. |
413 | file_too_large | The source is larger than your plan allows. |
422 | unsupported_media | The source could not be decoded. |
429 | rate_limited | Too many requests, see below. |
5xx | api_error | Something 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.