Presets

Presets are saved job configurations that let you run the same transcoding setup repeatedly without specifying the full body each time. Define your recipe or FFmpeg args once, save it as a preset, then run jobs with just a presetId and an input URL.

How presets work

1. Create a preset — save a job configuration (recipe or FFmpeg) to your account
2. Run a job — reference the preset by ID and supply your input URL
3. Input URLs are injected at runtime — the preset stores the pipeline config, you provide the media

Preset (saved):                  Job (at runtime):
┌────────────────────┐           ┌────────────────────┐
│ mode: "recipe"     │     +     │ presetId: "abc123"  │
│ output: "mp4"      │           │ input.url: "..."    │
│ recipe: compress   │           └────────────────────┘
│ crf: 28            │                    ↓
└────────────────────┘           Merged job submitted
                                 to Xora

Creating a preset

From the dashboard

1. Go to Dashboard → Presets
2. Click Create Preset
3. Configure your recipe or FFmpeg arguments
4. Name it and save

Using starter presets

Xora provides built-in starter presets you can clone:

Starter	Type	Description
Web ready MP4	Recipe	Browser playback and sharing (passthrough/remux when possible)
Web ready 720p	Recipe	Smaller web delivery MP4 at 720p
Edit proxy 1080p	Recipe	Timeline editing proxy at source resolution
Edit proxy 720p	Recipe	Scrub-friendly 720p edit proxy (all-intra)
Compress video	Recipe	H.264 compression with CRF 28
Extract audio	Recipe	Copy audio when possible; MP3 fallback otherwise
Thumbnail	Recipe	Capture frame at 1 second as JPG
Resize HD	Recipe	Scale to 1280×720
Merge audio (concat)	Recipe	Join two+ audio files
Merge video (concat)	Recipe	Join two+ video files
GIF preview	FFmpeg	8fps, 320px animated GIF

Clone a starter from Dashboard → Presets → Starters.

Running a job with a preset

Supply the presetId along with your input:

cURL

curl -X POST https://api.xora.sh/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "presetId": "01KPRESET1234ABCDEF",
    "input": {
      "url": "https://example.com/my-video.mp4"
    }
  }'

Node.js

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({
    presetId: '01KPRESET1234ABCDEF',
    input: {
      url: 'https://example.com/my-video.mp4'
    }
  })
});
const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    "https://api.xora.sh/v1/jobs",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "presetId": "01KPRESET1234ABCDEF",
        "input": {
            "url": "https://example.com/my-video.mp4"
        }
    }
)
data = response.json()
print(data)

Response

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

The preset’s recipe/FFmpeg config is merged with your input URL and submitted as a new job.

With a webhook

You can also pass a webhookUrl when running a preset:

{
  "presetId": "01KPRESET1234ABCDEF",
  "input": { "url": "https://example.com/video.mp4" },
  "webhookUrl": "https://your-server.com/xora-webhook"
}

With a custom output path

If you have a default custom storage provider configured, you can specify where the output should land when running a preset:

{
  "presetId": "01KPRESET1234ABCDEF",
  "input": { "url": "https://example.com/video.mp4" },
  "outputPath": "exports/my-custom-destination.mp4"
}

Skip input staging

For range-capable URLs (CDNs, S3/R2 presigned links), set stageInput: false on the job or save it in the preset body. See Input Staging.

{
  "presetId": "01KPRESET1234ABCDEF",
  "input": { "url": "https://cdn.example.com/video.mp4" },
  "stageInput": false
}

Multi-file presets

For concat or multi-file FFmpeg presets, supply input_files instead of input:

{
  "presetId": "01KPRESETCONCAT",
  "input_files": {
    "in_1": "https://example.com/part1.mp3",
    "in_2": "https://example.com/part2.mp3"
  }
}

Placeholder system

When you save a preset, Xora automatically replaces real URLs with placeholders. This way, the preset template is reusable with any input:

Preset body stores	You provide at job time
{{in_1}}, {{in_2}}	input_files.in_1, input_files.in_2
{{input_url}}	input.url
No input field (recipe presets)	input.url (required)

Note

Recipe presets (except concat) always require input.url at job time. The preset never stores the input URL — it’s always provided when you create the job.

Sharing presets

You can share any preset with a unique share link:

1. Go to Dashboard → Presets → your preset
2. Click Share to generate a share token
3. Share the URL with others

Recipients can clone the shared preset into their own account. You can revoke the share link at any time.

Limits

Limit	Value
Max presets per user	50
Max name length	64 characters
Max body size	16 KB

Tip

Presets appear in your job list — the preset_id and preset_name fields are included on every job that was created from a preset.