Compress Video

The compress recipe re-encodes video with H.264 at a configurable quality level (CRF). This is the most common way to reduce file size for web delivery.

Basic usage

curl -X POST https://api.xora.sh/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "recipe",
    "input": {
      "url": "https://example.com/raw-video.mp4"
    },
    "output": {
      "format": "mp4"
    },
    "recipe": {
      "name": "compress",
      "crf": 28
    }
  }'

const response = await fetch('https://api.xora.sh/v1/jobs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    mode: 'recipe',
    input: {
      url: 'https://example.com/raw-video.mp4'
    },
    output: {
      format: 'mp4'
    },
    recipe: {
      name: 'compress',
      crf: 28
    }
  })
});
const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://api.xora.sh/v1/jobs",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "mode": "recipe",
        "input": {
            "url": "https://example.com/raw-video.mp4"
        },
        "output": {
            "format": "mp4"
        },
        "recipe": {
            "name": "compress",
            "crf": 28
        }
    }
)
data = response.json()
print(data)

Response

{
  "jobId": "01JXYZ1234ABCDEF56789000",
  "state": "queued"
}

Parameters

Parameter	Type	Required	Default	Description
`name`	string	Yes	—	Must be `"compress"`
`crf`	number	No	`23`	Constant Rate Factor — controls quality vs size tradeoff

Understanding CRF

CRF (Constant Rate Factor) controls the quality-to-size tradeoff on a scale from 0 (lossless) to 51 (worst quality):

CRF	Quality	Typical use
18	Visually lossless	Archival, professional
23	High quality	Default, general purpose
28	Good quality	Web delivery, smaller files
32	Medium quality	Previews, bandwidth-constrained
38+	Low quality	Rough previews only

Supported output formats

Format	Description
`mp4`	H.264 in MP4 container — best compatibility
`webm`	VP8/VP9 in WebM — smaller for web
`mov`	H.264 in QuickTime — for Apple/pro workflows

Full example with polling

# 1. Create the job
JOB=$(curl -s -X POST https://api.xora.sh/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "recipe",
    "input": { "url": "https://example.com/large-video.mp4" },
    "output": { "format": "mp4" },
    "recipe": { "name": "compress", "crf": 28 }
  }')

JOB_ID=$(echo "$JOB" | jq -r '.jobId')
echo "Created job: $JOB_ID"

# 2. Poll until done
while true; do
  STATUS=$(curl -s "https://api.xora.sh/v1/jobs/$JOB_ID" \
    -H "Authorization: Bearer YOUR_API_KEY")
  STATE=$(echo "$STATUS" | jq -r '.state')
  echo "State: $STATE"
  [ "$STATE" = "completed" ] || [ "$STATE" = "failed" ] && break
  sleep 3
done

# 3. Download
URL=$(echo "$STATUS" | jq -r '.output.signedUrl')
curl -o compressed.mp4 "$URL"

import fs from 'fs';
import { pipeline } from 'stream/promises';

// 1. Create the job
const createResponse = await fetch('https://api.xora.sh/v1/jobs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    mode: 'recipe',
    input: { url: 'https://example.com/large-video.mp4' },
    output: { format: 'mp4' },
    recipe: { name: 'compress', crf: 28 }
  })
});
const { jobId } = await createResponse.json();
console.log(`Created job: ${jobId}`);

// 2. Poll until done
let status;
while (true) {
  const statusResponse = await fetch(`https://api.xora.sh/v1/jobs/${jobId}`, {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  });
  status = await statusResponse.json();
  console.log(`State: ${status.state}`);
  if (status.state === 'completed' || status.state === 'failed') break;
  await new Promise(resolve => setTimeout(resolve, 3000));
}

// 3. Download
if (status.state === 'completed') {
  const downloadResponse = await fetch(status.output.signedUrl);
  if (!downloadResponse.ok) throw new Error(`Unexpected response: ${downloadResponse.statusText}`);
  await pipeline(downloadResponse.body, fs.createWriteStream('compressed.mp4'));
  console.log('File downloaded successfully.');
} else {
  console.error('Job failed:', status.error);
}

import time
import requests

# 1. Create the job
create_response = requests.post(
    "https://api.xora.sh/v1/jobs",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "mode": "recipe",
        "input": {"url": "https://example.com/large-video.mp4"},
        "output": {"format": "mp4"},
        "recipe": {"name": "compress", "crf": 28}
    }
)
job_id = create_response.json()["jobId"]
print(f"Created job: {job_id}")

# 2. Poll until done
status = None
while True:
    status_response = requests.get(
        f"https://api.xora.sh/v1/jobs/{job_id}",
        headers={"Authorization": "Bearer YOUR_API_KEY"}
    )
    status = status_response.json()
    print(f"State: {status['state']}")
    if status["state"] in ["completed", "failed"]:
        break
    time.sleep(3)

# 3. Download
if status["state"] == "completed":
    download_response = requests.get(status["output"]["signedUrl"])
    with open("compressed.mp4", "wb") as f:
        f.write(download_response.content)
    print("File downloaded successfully.")
else:
    print("Job failed:", status.get("error"))