# Xora

> FFmpeg in the cloud, for agents & humans. Xora runs real FFmpeg argument
> arrays behind one REST endpoint: POST a job with raw args or a named recipe,
> poll deterministic job state (or take a webhook), and collect outputs from a
> signed URL or your own Cloudflare R2 bucket.

Base URL: https://api.xora.sh/v1
Auth: `Authorization: Bearer <api key>` (create keys in the dashboard at https://xora.sh/app)
OpenAPI spec: https://api.xora.sh/v1/openapi.json
Interactive reference: https://xora.sh/docs/api
MCP server: https://api.xora.sh/v1/mcp — remote MCP over Streamable HTTP, same
Bearer auth; tools: create_upload, create_job, get_job, list_recipes, cancel_job. Connect:
`claude mcp add --transport http xora https://api.xora.sh/v1/mcp --header "Authorization: Bearer <api key>"`
Agent skill: https://xora.sh/skills/xora/SKILL.md — recipe selection, job loop,
and error-branching guidance for Claude; install to ~/.claude/skills/xora/

Core loop:
1. `POST /v1/jobs` with `{"mode":"ffmpeg","input_files":{"in_1":"<https url>"},"output_files":{"out_1":"out.mp4"},"ffmpeg":{"args":["-i","{{in_1}}","...","{{out_1}}"]}}`
   or `{"mode":"recipe","input":{"url":"<https url>"},"output":{"format":"mp4"},"recipe":{"name":"compress","crf":23}}`
2. Poll `GET /v1/jobs/{id}` until `state` is terminal: `completed | failed | rejected | cancelled`
   (progress reported in percent; pass `webhookUrl` to be called back instead of polling).
3. Download the output via the signed URL on the job, or configure BYOB delivery
   to your own R2 bucket so outputs never need collecting.

Local files (no public URL): `POST /v1/uploads` with `{"sizeBytes":<bytes>,"filename":"clip.mp4"}`
returns `{uploadId, url, expiresAt, maxBytes}`; `PUT` the raw bytes to `url` (1 hour, no auth
header), then create the job with `"input":{"uploadId":"<uploadId>"}` in place of `input.url`.
Single-input recipe/probe/ffmpeg modes only; 5 GB per file; uploads are deleted after 3 days
and are reusable across jobs until then. See https://xora.sh/docs/guides/direct-uploads

## Docs

- [Introduction](https://xora.sh/docs/introduction): What Xora is, the job model, supported formats
- [Quickstart](https://xora.sh/docs/quickstart): Zero to a completed job in under two minutes
- [Authentication](https://xora.sh/docs/authentication): API keys and dashboard sessions
- [Job lifecycle](https://xora.sh/docs/job-lifecycle): Every job state, progress, polling, retry
- [Output formats](https://xora.sh/docs/output-formats): Which recipes produce which formats
- [API reference](https://xora.sh/docs/api): Interactive OpenAPI explorer

## Recipes (mode: "recipe")

- [Web ready](https://xora.sh/docs/recipes/web-ready): Probe first; remux or transcode only when needed for browser playback
- [Transcode](https://xora.sh/docs/recipes/transcode): Convert between MP4, WebM, MOV, and audio formats
- [Compress](https://xora.sh/docs/recipes/compress): Shrink file size with H.264 CRF control
- [Resize](https://xora.sh/docs/recipes/resize): Scale with automatic aspect handling
- [Trim](https://xora.sh/docs/recipes/trim): Cut a time range from video or audio
- [Concat](https://xora.sh/docs/recipes/concat): Stream-copy merge of same-format files
- [Extract audio](https://xora.sh/docs/recipes/extract-audio): Pull the audio track, stream-copy when possible
- [Thumbnail](https://xora.sh/docs/recipes/thumbnail): Grab a frame as JPG or PNG
- [Edit proxy](https://xora.sh/docs/recipes/proxy): Scrub-friendly low-res proxies for timeline editors
- [Probe](https://xora.sh/docs/recipes/probe): Enriched ffprobe metadata on the job record

## Guides

- [MCP server](https://xora.sh/docs/guides/mcp): Connect agents over the Model Context Protocol — tool-call the jobs API directly
- [Custom FFmpeg args](https://xora.sh/docs/guides/ffmpeg): mode "ffmpeg" — raw argument arrays with {{in_1}}/{{out_1}} placeholders
- [Direct uploads](https://xora.sh/docs/guides/direct-uploads): presigned PUT for local files, then input.uploadId instead of input.url
- [Webhooks](https://xora.sh/docs/guides/webhooks): Terminal-state callbacks instead of polling
- [Error handling](https://xora.sh/docs/guides/error-handling): Structured errors, rejected vs failed, retries
- [Presets](https://xora.sh/docs/guides/presets): Save a job configuration, run it by presetId
- [Storage providers (BYOB)](https://xora.sh/docs/guides/storage-providers): Deliver outputs to your own Cloudflare R2 bucket
- [Input staging](https://xora.sh/docs/guides/input-staging): stageInput: false for byte-range reads from seekable origins

## Optional

- [Full docs in one file](https://xora.sh/llms-full.txt): Every docs page above as plain Markdown
- [Pricing](https://xora.sh/pricing/): Free tier (25 credits/mo, 2 GB stored media, 250 MB max input, no credit card); Build $15/mo (400 credits, 15 GB storage, 2 GB max input, BYOB); Scale $49/mo (1500 credits, 100 GB storage, 6 GB max input, BYOB). One meter: credits. 1 credit = 1 minute of processing work a job performs (probe, staging, encode, merge — metered per second); each GB of output the job produces adds 10 credits, counted once, same for managed storage or BYOB. Typical jobs: thumbnail ~0.1 credits, podcast hour to MP3 ~2, 10-min 1080p transcode ~12. Downloads are unlimited and free; inputs are never charged. Credits and storage are hard caps: when exhausted, new jobs return a LIMIT_EXCEEDED error (HTTP 402) until reset or upgrade. Jobs ending failed or rejected bill nothing. Every completed job returns cost.totalUsd on the job record.
- [Blog](https://xora.sh/blog): Guides on FFmpeg workflows, n8n automation, encoding practices

---

# Full docs

---

# Introduction

Source: https://xora.sh/docs/introduction/

Xora is a **programmatic video transcoding API**. Send a URL (or [upload a local file](https://xora.sh/docs/guides/direct-uploads/)), pick a recipe (or write your own FFmpeg command), and get processed media back — all through a single REST endpoint at **`https://api.xora.sh/v1`**.

## How it works

```
Your app                         Xora
   │                               │
   ├── POST /api/v1/jobs ─────────▶│  (input URL + recipe)
   │                               │
   │◀── 202 { jobId, state } ──────┤  (job accepted)
   │                               │
   │    ... processing ...         │
   │                               │
   ├── GET /api/v1/jobs/:id ──────▶│  (check status)
   │◀── { state, signedUrl } ──────┤  (download when ready)
   │                               │
```

1. **Authenticate** — use an API key (`Authorization: Bearer nte_…`) or sign in to the dashboard.
2. **Create a job** — `POST /api/v1/jobs` with a recipe or custom FFmpeg args.
3. **Wait for completion** — poll the job status or receive a [webhook](https://xora.sh/docs/guides/webhooks/).
4. **Download** — grab your output from the signed URL, or have it delivered to [your own R2 bucket](https://xora.sh/docs/guides/storage-providers/).

## What you can do

| Feature | Description |
|---------|-------------|
| **9 built-in recipes** | [Web ready](https://xora.sh/docs/recipes/web-ready/), [Edit proxy](https://xora.sh/docs/recipes/proxy/), [compress](https://xora.sh/docs/recipes/compress/), [transcode](https://xora.sh/docs/recipes/transcode/), [resize](https://xora.sh/docs/recipes/resize/), [trim](https://xora.sh/docs/recipes/trim/), [extract audio](https://xora.sh/docs/recipes/extract-audio/), [thumbnail](https://xora.sh/docs/recipes/thumbnail/), [concat](https://xora.sh/docs/recipes/concat/) |
| **Probe jobs** | Inspect media with [`mode: "probe"`](https://xora.sh/docs/recipes/probe/) — enriched ffprobe metadata on the job record |
| **Custom FFmpeg** | Pass your own [FFmpeg argument array](https://xora.sh/docs/guides/ffmpeg/) for full control |
| **Direct uploads** | [Upload local files](https://xora.sh/docs/guides/direct-uploads/) with a presigned URL when there's nothing public to point at |
| **Presets** | Save and reuse [job configurations](https://xora.sh/docs/guides/presets/) — run them with a single `presetId` |
| **Input staging** | Optionally [skip copying inputs](https://xora.sh/docs/guides/input-staging/) when your URL supports HTTP byte ranges |
| **Webhooks** | Get notified when jobs [complete or fail](https://xora.sh/docs/guides/webhooks/) |
| **BYOB storage** | Route outputs to [your own Cloudflare R2 bucket](https://xora.sh/docs/guides/storage-providers/) |
| **Files API** | [List, inspect, and delete](https://xora.sh/docs/api/) stored output files |

## Supported formats

| Type | Formats |
|------|---------|
| Video | `mp4`, `webm`, `mov`, `gif` |
| Audio | `mp3`, `aac`, `wav` |
| Image | `jpg`, `png` |

Probe jobs return metadata on the job record — see [Probe Media Metadata](https://xora.sh/docs/recipes/probe/).

See [Output Formats](https://xora.sh/docs/output-formats/) for details on which recipes support which formats.

## Components

| Piece | What it does |
|-------|-------------|
| **REST API** | `POST /api/v1/jobs`, `GET /api/v1/jobs/:id`, uploads, files, presets, tokens, usage |
| **Dashboard** | Web UI at `/app` — manage presets, inspect jobs, create API keys |

## Next steps

- [**Quickstart →**](https://xora.sh/docs/quickstart/) — create your first transcoding job in 2 minutes
- [**Recipes →**](https://xora.sh/docs/recipes/web-ready/) — browse all 10 built-in recipes
- [**API Reference →**](https://xora.sh/docs/api/) — interactive OpenAPI docs

---

# Quickstart

Source: https://xora.sh/docs/quickstart/

This guide takes you from zero to a completed transcoding job. You'll generate a thumbnail from a sample video using a single API call.

## Prerequisites

- A Xora account — [sign up here](https://xora.sh/app/sign-up) (free)
- An API key — create one in the [dashboard](https://xora.sh/app/dashboard/tokens)

**Tip:**
Your API key starts with `nte_` and is shown only once when created. Copy it somewhere safe.

## Your first job

1. **Create a thumbnail job**

    Send a `POST` to `/api/v1/jobs` with the `thumbnail` recipe. This captures a single frame from a video at the 1-second mark:

**cURL:**
```bash
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://samplelib.com/lib/preview/mp4/sample-5s.mp4"
    },
    "output": {
      "format": "jpg"
    },
    "recipe": {
      "name": "thumbnail",
      "seekSeconds": 1
    }
  }'
```
**Node.js:**
```javascript
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://samplelib.com/lib/preview/mp4/sample-5s.mp4'
    },
    output: {
      format: 'jpg'
    },
    recipe: {
      name: 'thumbnail',
      seekSeconds: 1
    }
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
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://samplelib.com/lib/preview/mp4/sample-5s.mp4"
        },
        "output": {
            "format": "jpg"
        },
        "recipe": {
            "name": "thumbnail",
            "seekSeconds": 1
        }
    }
)
data = response.json()
print(data)
```

    You'll get a `202 Accepted` response with the job ID:

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

2. **Check job status**

    Poll the job to see its progress. Replace `JOB_ID` with the `jobId` from step 1:

**cURL:**
```bash
curl https://api.xora.sh/v1/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```
**Node.js:**
```javascript
const response = await fetch('https://api.xora.sh/v1/jobs/JOB_ID', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
import requests

response = requests.get(
    "https://api.xora.sh/v1/jobs/JOB_ID",
    headers={
        "Authorization": "Bearer YOUR_API_KEY"
    }
)
data = response.json()
print(data)
```

    While processing, you'll see states like `probing`, `transcoding`, etc. with a `progress` percentage:

    ```json
    {
      "jobId": "01JXYZ1234ABCDEF56789000",
      "state": "transcoding",
      "progress": 50
    }
    ```

3. **Download the output**

    When `state` is `"completed"`, the response includes a signed download URL:

    ```json
    {
      "jobId": "01JXYZ1234ABCDEF56789000",
      "state": "completed",
      "progress": 100,
      "output": {
        "signedUrl": "https://cdn.xora.sh/...signed-url..."
      },
      "output_files": {
        "output": {
          "filename": "output.jpg",
          "file_type": "image",
          "file_format": "jpg",
          "mime_type": "image/jpeg",
          "storage_url": "https://cdn.xora.sh/...signed-url..."
        }
      }
    }
    ```

    Open the `signedUrl` in your browser or download it with curl:

**cURL:**
```bash
curl -o thumbnail.jpg "SIGNED_URL_HERE"
```
**Node.js:**
```javascript
import fs from 'fs';
import { pipeline } from 'stream/promises';

const response = await fetch('SIGNED_URL_HERE');
if (!response.ok) throw new Error(`Unexpected response: ${response.statusText}`);
await pipeline(response.body, fs.createWriteStream('thumbnail.jpg'));
```
**Python:**
```python
import requests

response = requests.get("SIGNED_URL_HERE")
with open("thumbnail.jpg", "wb") as f:
    f.write(response.content)
```

## Processing a local file

The job above used a public sample URL. When your file only exists locally,
request a presigned upload, `PUT` the bytes, then create the job against the
returned `uploadId` instead of a URL:

**cURL:**
```bash
# 1. Request an upload (sizeBytes is checked against your plan limit)
curl -X POST https://api.xora.sh/v1/uploads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sizeBytes": 734003200, "filename": "my-video.mp4" }'

# 2. Upload the bytes to the returned url (no auth header needed)
curl -X PUT "PRESIGNED_URL_HERE" --upload-file my-video.mp4

# 3. Create the job with the uploadId
curl -X POST https://api.xora.sh/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "recipe",
    "input": { "uploadId": "UPLOAD_ID_HERE" },
    "output": { "format": "jpg" },
    "recipe": { "name": "thumbnail", "seekSeconds": 1 }
  }'
```
**Node.js:**
```javascript
import { statSync, openAsBlob } from 'node:fs';

const path = 'my-video.mp4';
const auth = { Authorization: 'Bearer YOUR_API_KEY' };

const { uploadId, url } = await fetch('https://api.xora.sh/v1/uploads', {
  method: 'POST',
  headers: { ...auth, 'Content-Type': 'application/json' },
  body: JSON.stringify({ sizeBytes: statSync(path).size, filename: path }),
}).then((r) => r.json());

await fetch(url, { method: 'PUT', body: await openAsBlob(path) });

const job = await fetch('https://api.xora.sh/v1/jobs', {
  method: 'POST',
  headers: { ...auth, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    mode: 'recipe',
    input: { uploadId },
    output: { format: 'jpg' },
    recipe: { name: 'thumbnail', seekSeconds: 1 },
  }),
}).then((r) => r.json());
```
**Python:**
```python
import os, requests

path = "my-video.mp4"
auth = {"Authorization": "Bearer YOUR_API_KEY"}

upload = requests.post(
    "https://api.xora.sh/v1/uploads",
    headers=auth,
    json={"sizeBytes": os.path.getsize(path), "filename": path},
).json()

with open(path, "rb") as f:
    requests.put(upload["url"], data=f)

job = requests.post(
    "https://api.xora.sh/v1/jobs",
    headers=auth,
    json={
        "mode": "recipe",
        "input": {"uploadId": upload["uploadId"]},
        "output": {"format": "jpg"},
        "recipe": {"name": "thumbnail", "seekSeconds": 1},
    },
).json()
```

**Note:**
Uploads are kept for 3 days and can be reused by multiple jobs in that window.
See [Direct Uploads](https://xora.sh/docs/guides/direct-uploads/) for size limits and the full
flow.

## Using a preset instead

If you've saved a preset in the [dashboard](https://xora.sh/app/dashboard/presets), you can run a job with just its ID:

**cURL:**
```bash
curl -X POST https://api.xora.sh/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "presetId": "YOUR_PRESET_ID",
    "input": { "url": "https://example.com/video.mp4" }
  }'
```
**Node.js:**
```javascript
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: 'YOUR_PRESET_ID',
    input: { url: 'https://example.com/video.mp4' }
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
import requests

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

**Note:**
Presets save your recipe/FFmpeg configuration so you don't have to repeat it every time. See the [Presets guide](https://xora.sh/docs/guides/presets/) for details.

## Receiving webhooks instead of polling

Instead of polling, you can pass a `webhookUrl` to get notified when the job finishes:

**cURL:**
```bash
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/video.mp4" },
    "output": { "format": "jpg" },
    "recipe": { "name": "thumbnail", "seekSeconds": 1 },
    "webhookUrl": "https://your-server.com/webhook"
  }'
```
**Node.js:**
```javascript
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/video.mp4' },
    output: { format: 'jpg' },
    recipe: { name: 'thumbnail', seekSeconds: 1 },
    webhookUrl: 'https://your-server.com/webhook'
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
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/video.mp4" },
        "output": { "format": "jpg" },
        "recipe": { "name": "thumbnail", "seekSeconds": 1 },
        "webhookUrl": "https://your-server.com/webhook"
    }
)
data = response.json()
print(data)
```

Xora will `POST` the job result to your URL when it reaches a terminal state. See [Webhooks](https://xora.sh/docs/guides/webhooks/).

## What's next?

- [**Recipes →**](https://xora.sh/docs/recipes/web-ready/) — web-ready video, edit proxy, compress, transcode, resize, trim, extract audio, thumbnails, concat
- [**Probe metadata →**](https://xora.sh/docs/recipes/probe/) — inspect media with `mode: "probe"`
- [**Custom FFmpeg →**](https://xora.sh/docs/guides/ffmpeg/) — full control with your own FFmpeg arguments
- [**Direct Uploads →**](https://xora.sh/docs/guides/direct-uploads/) — process local files with no public URL
- [**Presets →**](https://xora.sh/docs/guides/presets/) — save and reuse job configurations
- [**Input Staging →**](https://xora.sh/docs/guides/input-staging/) — skip copying inputs when your URL supports byte ranges
- [**Storage Providers →**](https://xora.sh/docs/guides/storage-providers/) — route outputs directly to your own Cloudflare R2 bucket
- [**Job lifecycle →**](https://xora.sh/docs/job-lifecycle/) — understand job states and progress
- [**API Reference →**](https://xora.sh/docs/api/) — full interactive API docs

---

# Authentication

Source: https://xora.sh/docs/authentication/

Every request to the Xora API must be authenticated. You can use an **API key** (for programmatic access) or a **Clerk session** (for the dashboard UI).

## API keys

API keys start with `nte_` and are 52 characters long. You create them in the [dashboard](https://xora.sh/app/dashboard/tokens) and they're shown **only once** — copy the full key when it's displayed.

### Sending your key

You can pass your API key in either of two headers:

**cURL (Authorization):**
```bash
curl https://api.xora.sh/v1/jobs \
  -H "Authorization: Bearer nte_your_api_key_here"
```
**cURL (X-API-KEY):**
```bash
curl https://api.xora.sh/v1/jobs \
  -H "X-API-KEY: nte_your_api_key_here"
```
**Node.js:**
```javascript
const response = await fetch('https://api.xora.sh/v1/jobs', {
  headers: {
    'Authorization': 'Bearer nte_your_api_key_here'
  }
});
```
**Python:**
```python
import requests

response = requests.get(
    "https://api.xora.sh/v1/jobs",
    headers={
        "Authorization": "Bearer nte_your_api_key_here"
    }
)
```

Both methods are equivalent. Use whichever fits your HTTP client best.

### Creating a key

1. Sign in at [xora.sh/app](https://xora.sh/app/sign-in)
2. Go to **Dashboard → Tokens**
3. Click **Create Token** and give it a name (e.g., "Production API")
4. Copy the full key immediately — it won't be shown again

### Revoking a key

In **Dashboard → Tokens**, click the delete button next to any key. Once revoked, all requests using that key will receive a `401` response immediately.

**Caution:**
Revoking a key is instant and irreversible. Any running integrations using that key will stop working.

## Dashboard sessions

The web dashboard at `/app` uses [Clerk](https://clerk.com) for authentication. When you interact with the dashboard, it calls `/api/v1/*` on **`xora.sh`** (same origin) using your Clerk session cookie — no API key needed.

Programmatic clients should use **`https://api.xora.sh/v1`** with an API key.

## Error responses

If authentication fails, the API returns a `401` status with this JSON body:

```json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required. Provide a valid Bearer token or sign in via the dashboard.",
    "retryable": false
  }
}
```

Common causes:
- Missing `Authorization` or `X-API-KEY` header
- Key doesn't start with `nte_`
- Key has been revoked
- Key was copy-pasted incorrectly (check for trailing spaces)

## CORS

Browser requests are allowed from the configured dashboard origin (set via `XORA_PUBLIC_ORIGIN`). If CORS is not configured, all origins are allowed.

The API accepts these headers in cross-origin requests:
- `Authorization`
- `Content-Type`
- `X-API-KEY`

## Security best practices

**Tip:**
- **Never expose keys in client-side code.** Call the Xora API from your backend server, not from browser JavaScript.
- **Use separate keys** for development, staging, and production.
- **Rotate keys periodically.** Create a new key, update your integration, then revoke the old one.
- **Name your keys** descriptively (e.g., "CI Pipeline", "Production Backend") so you know what to revoke if one leaks.

---

# Job Lifecycle

Source: https://xora.sh/docs/job-lifecycle/

Every transcoding job moves through a series of states from creation to completion (or failure). Understanding these states helps you build robust integrations.

## Job states

When you create a job, it begins as `queued` and progresses through these states:

```
queued → probing → planning → transcoding → merging → completed
                         ↘ (optional segmenting on legacy paths)
                                                                  ↘ failed
                                                                  ↘ rejected
                                                                  ↘ cancelled
```

| State | Description |
|-------|-------------|
| `queued` | Job accepted, waiting to be picked up |
| `probing` | Analyzing the input file (codec, duration, resolution, byte-range support) |
| `planning` | Determining the processing strategy |
| `segmenting` | Legacy state — not used on current engine paths (inputs are range-read or staged once) |
| `transcoding` | Actively processing media (longest phase) |
| `merging` | Assembling or wrapping media streams into the final container file |
| `completed` | Done — output is ready for download |
| `failed` | Something went wrong — check `error` for details |
| `rejected` | Input was rejected before processing (e.g., unsupported format or unsafe command) |
| `cancelled` | You cancelled the job before it finished |

### Terminal states

A job is **terminal** when it reaches one of: `completed`, `failed`, `rejected`, or `cancelled`. Terminal jobs cannot transition to another state (except via `retry`).

## Tracking progress

The `progress` field is a number from `0` to `100` that updates as the job runs:

```json
{
  "jobId": "01JXYZ...",
  "state": "transcoding",
  "progress": 65
}
```

- `0` — job is queued or just started
- `1–99` — actively processing
- `100` — completed

**Note:**
Progress updates are approximate. Short jobs may jump from 0 to 100. Longer jobs update more gradually as they process.

## Polling for completion

The simplest way to track a job is to poll `GET /api/v1/jobs/:id` until the state is terminal:

**cURL / Bash:**
```bash
# Poll every 2 seconds
while true; do
  RESPONSE=$(curl -s https://api.xora.sh/v1/jobs/JOB_ID \
    -H "Authorization: Bearer YOUR_API_KEY")

  STATE=$(echo "$RESPONSE" | jq -r '.state')
  PROGRESS=$(echo "$RESPONSE" | jq -r '.progress')

  echo "State: $STATE, Progress: $PROGRESS%"

  if [ "$STATE" = "completed" ] || [ "$STATE" = "failed" ] || \
     [ "$STATE" = "rejected" ] || [ "$STATE" = "cancelled" ]; then
    echo "$RESPONSE" | jq .
    break
  fi

  sleep 2
done
```
**Node.js:**
```javascript
const pollJob = async (jobId) => {
  const terminalStates = ['completed', 'failed', 'rejected', 'cancelled'];
  
  while (true) {
    const response = await fetch(`https://api.xora.sh/v1/jobs/${jobId}`, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    });
    const data = await response.json();
    
    console.log(`State: ${data.state}, Progress: ${data.progress}%`);
    
    if (terminalStates.includes(data.state)) {
      console.log('Final job details:', data);
      break;
    }
    
    // Wait 2 seconds before polling again
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
};

pollJob('JOB_ID');
```
**Python:**
```python
import time
import requests

def poll_job(job_id):
    terminal_states = {"completed", "failed", "rejected", "cancelled"}
    
    while True:
        response = requests.get(
            f"https://api.xora.sh/v1/jobs/{job_id}",
            headers={
                "Authorization": "Bearer YOUR_API_KEY"
            }
        )
        data = response.json()
        
        print(f"State: {data['state']}, Progress: {data['progress']}%")
        
        if data["state"] in terminal_states:
            print("Final job details:", data)
            break
            
        # Wait 2 seconds before polling again
        time.sleep(2)

poll_job("JOB_ID")
```

**Tip:**
For production use, consider [webhooks](https://xora.sh/docs/guides/webhooks/) instead of polling. They're more efficient and you get notified instantly.

## Using webhooks

Instead of polling, pass a `webhookUrl` when creating a job. Xora will `POST` the result to your URL when the job reaches a terminal state:

**cURL:**
```bash
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/video.mp4" },
    "output": { "format": "mp4" },
    "recipe": { "name": "compress", "crf": 28 },
    "webhookUrl": "https://your-server.com/xora-webhook"
  }'
```
**Node.js:**
```javascript
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/video.mp4' },
    output: { format: 'mp4' },
    recipe: { name: 'compress', crf: 28 },
    webhookUrl: 'https://your-server.com/xora-webhook'
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
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/video.mp4" },
        "output": { "format": "mp4" },
        "recipe": { "name": "compress", "crf": 28 },
        "webhookUrl": "https://your-server.com/xora-webhook"
    }
)
data = response.json()
print(data)
```

See the [Webhooks guide](https://xora.sh/docs/guides/webhooks/) for payload format and configuration.

## Job actions

### Cancel a job

Stop a running job before it completes:

**cURL:**
```bash
curl -X POST https://api.xora.sh/v1/jobs/JOB_ID/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"
```
**Node.js:**
```javascript
const response = await fetch('https://api.xora.sh/v1/jobs/JOB_ID/cancel', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
import requests

response = requests.post(
    "https://api.xora.sh/v1/jobs/JOB_ID/cancel",
    headers={
        "Authorization": "Bearer YOUR_API_KEY"
    }
)
data = response.json()
print(data)
```

```json
{
  "cancelled": true
}
```

**Note:**
Cancellation is best-effort. If the job is already completing, it may finish before the cancel takes effect.

### Retry a failed job

Retry a job that ended in `failed`, `rejected`, or `cancelled` state. The retry uses the same input parameters:

**cURL:**
```bash
curl -X POST https://api.xora.sh/v1/jobs/JOB_ID/retry \
  -H "Authorization: Bearer YOUR_API_KEY"
```
**Node.js:**
```javascript
const response = await fetch('https://api.xora.sh/v1/jobs/JOB_ID/retry', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
import requests

response = requests.post(
    "https://api.xora.sh/v1/jobs/JOB_ID/retry",
    headers={
        "Authorization": "Bearer YOUR_API_KEY"
    }
)
data = response.json()
print(data)
```

```json
{
  "retried": true,
  "jobId": "01JXYZ1234ABCDEF56789000"
}
```

### Delete job output

Remove the hosted output files from storage. This is permanent:

**cURL:**
```bash
curl -X DELETE https://api.xora.sh/v1/jobs/JOB_ID/output \
  -H "Authorization: Bearer YOUR_API_KEY"
```
**Node.js:**
```javascript
const response = await fetch('https://api.xora.sh/v1/jobs/JOB_ID/output', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
import requests

response = requests.delete(
    "https://api.xora.sh/v1/jobs/JOB_ID/output",
    headers={
        "Authorization": "Bearer YOUR_API_KEY"
    }
)
data = response.json()
print(data)
```

```json
{
  "jobId": "01JXYZ1234ABCDEF56789000",
  "deleted": true
}
```

**Caution:**
Deleted outputs cannot be recovered. Download the files before deleting if you need to keep them.

## Listing jobs

Fetch a paginated list of your jobs, optionally filtered by state:

**cURL:**
```bash
# List recent jobs
curl "https://api.xora.sh/v1/jobs?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by state
curl "https://api.xora.sh/v1/jobs?state=completed&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
**Node.js:**
```javascript
// List recent jobs
const responseRecent = await fetch('https://api.xora.sh/v1/jobs?limit=20&offset=0', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
console.log(await responseRecent.json());

// Filter by state
const responseState = await fetch('https://api.xora.sh/v1/jobs?state=completed&limit=10', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
console.log(await responseState.json());
```
**Python:**
```python
import requests

# List recent jobs
response_recent = requests.get(
    "https://api.xora.sh/v1/jobs?limit=20&offset=0",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
print(response_recent.json())

# Filter by state
response_state = requests.get(
    "https://api.xora.sh/v1/jobs?state=completed&limit=10",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
print(response_state.json())
```

```json
{
  "jobs": [
    {
      "id": "01JXYZ...",
      "mode": "recipe",
      "recipe_name": "compress",
      "state": "completed",
      "created_at": "2026-06-04T10:00:00.000Z",
      "completed_at": "2026-06-04T10:00:45.000Z",
      "duration_seconds": 120.5
    }
  ],
  "limit": 20,
  "offset": 0
}
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | number | `20` | Results per page (max 100) |
| `offset` | number | `0` | Skip this many results |
| `state` | string | — | Filter by state: `queued`, `probing`, `planning`, `segmenting`, `transcoding`, `merging`, `completed`, `failed`, `rejected`, `cancelled` |

---

# Output Formats

Source: https://xora.sh/docs/output-formats/

Xora supports 9 output formats across video, audio, and image transcoding jobs. You specify the format in your job's `output.format` field.

For media inspection without transcoding, use [`mode: "probe"`](https://xora.sh/docs/recipes/probe/) — metadata is returned on the job record, not as a file.

## Supported formats

| Format | Type | MIME Type | Description |
|--------|------|-----------|-------------|
| `mp4` | Video | `video/mp4` | H.264 video — universal playback, great for web |
| `webm` | Video | `video/webm` | VP8/VP9 video — optimized for web browsers |
| `mov` | Video | `video/quicktime` | QuickTime container — common in Apple/pro workflows |
| `gif` | Image | `image/gif` | Animated GIF — for previews and social media |
| `mp3` | Audio | `audio/mpeg` | MPEG audio — most compatible audio format |
| `aac` | Audio | `audio/aac` | Advanced Audio Coding — better quality than MP3 at same bitrate |
| `wav` | Audio | `audio/wav` | Uncompressed audio — lossless, large files |
| `jpg` | Image | `image/jpeg` | JPEG image — for thumbnails and frame captures |
| `png` | Image | `image/png` | PNG image — lossless, supports transparency |

## Which recipes support which formats

| Recipe | Video formats | Audio formats | Image formats |
|--------|--------------|---------------|---------------|
| **webReady** | `mp4` | — | — |
| **proxy** | `mp4` | — | — |
| **compress** | `mp4`, `webm`, `mov` | — | — |
| **transcode** | `mp4`, `webm`, `mov` | `mp3`, `aac`, `wav` | — |
| **resize** | `mp4`, `webm`, `mov` | — | — |
| **trim** | `mp4`, `webm`, `mov` | `mp3`, `aac`, `wav` | — |
| **extractAudio** | — | `mp3`, `aac`, `wav` (fallback only) | — |
| **thumbnail** | — | — | `jpg`, `png` |
| **concat** | `mp4`, `webm`, `mov` | `mp3`, `aac`, `wav` | — |

**Note:**
Custom [FFmpeg jobs](https://xora.sh/docs/guides/ffmpeg/) can produce any of the 9 media formats. The table above applies to recipe mode only.

## Choosing a format

### Video

- **`mp4`** — safest default. Plays everywhere (browsers, phones, desktop). Uses H.264 codec.
- **`webm`** — smaller file sizes for the same quality. Best for web-only use. Not universally supported on older devices.
- **`mov`** — use when your downstream workflow requires QuickTime (e.g., Final Cut Pro, After Effects).

### Audio

- **`mp3`** — most compatible. Use for podcasts, music, or any general-purpose audio.
- **`aac`** — higher quality than MP3 at the same bitrate. Default audio codec in MP4 containers.
- **`wav`** — uncompressed, lossless audio. Use when quality matters more than file size (e.g., mastering, sound design).

### extractAudio (special case)

For the [extractAudio](https://xora.sh/docs/recipes/extract-audio/) recipe, `output.format` is only the **transcode fallback** when the source audio cannot be stream-copied. Xora probes the input and may deliver a different extension without re-encoding:

| Resolved output | When |
|-----------------|------|
| `.mp3`, `.aac`, `.wav`, `.opus`, `.flac`, `.ogg` | Source codec supports stream copy |
| `output.format` (`mp3`, `aac`, or `wav`) | Source codec not copyable (e.g. AC-3, DTS) |

The completed file extension comes from the engine plan, not necessarily from `output.format`.

### Image

- **`jpg`** — smaller files, great for thumbnails and previews. Lossy compression.
- **`png`** — lossless, supports transparency. Larger files but pixel-perfect quality.

## Setting the format

The format is always specified in the `output` object:

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/video.mp4" },
  "output": { "format": "mp4" },
  "recipe": { "name": "compress", "crf": 28 }
}
```

For FFmpeg multi-file jobs, the format is determined by the output filename extension:

```json
{
  "mode": "ffmpeg",
  "input_files": { "in_1": "https://example.com/video.mp4" },
  "output_files": { "out_1": "result.webm" },
  "ffmpeg": { "args": ["-i", "{{in_1}}", "-c:v", "libvpx-vp9", "{{out_1}}"] }
}
```

---

# Web Ready Video

Source: https://xora.sh/docs/recipes/web-ready/

The `webReady` recipe optimizes videos for **web delivery** — browser playback, embeds, and social sharing — without obvious quality loss. Xora probes the source first, then picks the cheapest path that still meets your goals.

## How it decides

| Source condition | Strategy |
|------------------|----------|
| H.264 video, AAC/MP3 audio, MP4/MOV container, reasonable bitrate, **and faststart already present** | `passthrough`: return your original input URL — no ffmpeg run |
| Browser-compatible source, faststart missing, **no explicit encode settings** | `faststart_remux`: stream-copy and move MP4 metadata to the front |
| Unsupported codec/container, high bitrate, **or explicit encode settings** (`crf`, `bitrateKbps`, `scaleDown`, `width`, `height`) | `web_encode`: H.264/AAC MP4 with fast-decode settings and one keyframe per second |

**Note:**
For timeline editing proxies (always re-encode, optional all-intra keyframes), use the [proxy recipe](https://xora.sh/docs/recipes/proxy/) instead.

## Basic usage

**cURL:**
```bash
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/upload.mov"
    },
    "output": {
      "format": "mp4"
    },
    "recipe": {
      "name": "webReady"
    }
  }'
```
**Node.js:**
```javascript
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/upload.mov' },
    output: { format: 'mp4' },
    recipe: { name: 'webReady' }
  })
});
```
**Python:**
```python
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/upload.mov"},
        "output": {"format": "mp4"},
        "recipe": {"name": "webReady"}
    }
)
```

## Smaller web delivery (720p)

Setting encode options forces a re-encode even when the source is browser-compatible:

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/large-upload.mp4" },
  "output": { "format": "mp4" },
  "recipe": {
    "name": "webReady",
    "scaleDown": true,
    "height": 720,
    "crf": 26
  }
}
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | string | Yes | — | Must be `"webReady"` |
| `scaleDown` | boolean | No | `false` | Downscale when re-encoding. Ignored on passthrough/remux paths. |
| `width` | number | No | auto | Output width when scaling |
| `height` | number | No | `720` | Output height when `scaleDown` is true |
| `crf` | number | No | `26` | Quality when re-encoding (lower = higher quality) |
| `bitrateKbps` | number | No | — | Target video bitrate; overrides CRF when set |
| `startSeconds` | number | No | — | Optional start offset in seconds |
| `durationSeconds` | number | No | — | Optional duration limit in seconds |

## Output format

`webReady` requires MP4 output:

```json
"output": { "format": "mp4" }
```

## When to use webReady vs proxy vs compress

| Use `webReady` when… | Use [proxy](https://xora.sh/docs/recipes/proxy/) when… | Use [compress](https://xora.sh/docs/recipes/compress/) when… |
|----------------------|----------------------------------------|----------------------------------------------|
| Web playback and sharing | Timeline editing and scrubbing | You always want a CRF-controlled re-encode |
| Source may already be web-ready | You always want re-encode | No passthrough/remux shortcuts |
| Optional smaller delivery via CRF/scale | Optional all-intra keyframes | Predictable encode every time |

---

# Transcode Video

Source: https://xora.sh/docs/recipes/transcode/

The `transcode` recipe converts media between formats. Use it to go from MOV to MP4, MP4 to WebM, or to extract audio from video into MP3/AAC/WAV.

## Basic usage

Convert an MOV file to MP4:

**cURL:**
```bash
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/recording.mov"
    },
    "output": {
      "format": "mp4"
    },
    "recipe": {
      "name": "transcode"
    }
  }'
```
**Node.js:**
```javascript
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/recording.mov'
    },
    output: {
      format: 'mp4'
    },
    recipe: {
      name: 'transcode'
    }
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
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/recording.mov"
        },
        "output": {
            "format": "mp4"
        },
        "recipe": {
            "name": "transcode"
        }
    }
)
data = response.json()
print(data)
```

### Response

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

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Must be `"transcode"` |

The transcode recipe takes no extra parameters — the output format in `output.format` determines the conversion target.

## Supported conversions

| Input → Output | Example use case |
|-----------------|-----------------|
| MOV → `mp4` | iPhone recordings for web delivery |
| MP4 → `webm` | Optimized web video |
| WebM → `mp4` | Browser recording to universal format |
| MP4 → `mp3` | Extract audio track as MP3 |
| Video → `aac` | Extract audio as AAC |
| Video → `wav` | Lossless audio extraction |

### Output formats

| Format | Type |
|--------|------|
| `mp4` | Video |
| `webm` | Video |
| `mov` | Video |
| `mp3` | Audio |
| `aac` | Audio |
| `wav` | Audio |

**Tip:**
If you only need the audio from a video, use the [extractAudio recipe](https://xora.sh/docs/recipes/extract-audio/) instead. It stream-copies compatible audio when possible and only transcodes when necessary. `transcode` always targets `output.format`.

## Examples

### MOV to MP4

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/recording.mov" },
  "output": { "format": "mp4" },
  "recipe": { "name": "transcode" }
}
```

### MP4 to WebM

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/video.mp4" },
  "output": { "format": "webm" },
  "recipe": { "name": "transcode" }
}
```

### Video to MP3 (audio extraction)

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/interview.mp4" },
  "output": { "format": "mp3" },
  "recipe": { "name": "transcode" }
}
```

**Note:**
Transcoding always re-encodes the media. If you need to change the container without re-encoding (e.g., remux MKV → MP4), use a [custom FFmpeg job](https://xora.sh/docs/guides/ffmpeg/) with `-c copy`.

---

# Compress Video

Source: https://xora.sh/docs/recipes/compress/

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:**
```bash
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
    }
  }'
```
**Node.js:**
```javascript
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);
```
**Python:**
```python
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

```json
{
  "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 |

**Tip:**
Start with **CRF 28** for web delivery. If quality isn't good enough, try 23. Each step of ~6 roughly halves/doubles the file size.

## 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

**cURL / Bash:**
```bash
# 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"
```
**Node.js:**
```javascript
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);
}
```
**Python:**
```python
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"))
```

**Note:**
Compression doesn't change the resolution or crop the video. If you also want to resize, use the [resize recipe](https://xora.sh/docs/recipes/resize/) instead, or chain jobs.

---

# Resize Video

Source: https://xora.sh/docs/recipes/resize/

The `resize` recipe scales video to a target width and height. Specify one or both dimensions — if you only set one, the other scales proportionally to preserve aspect ratio.

## Basic usage

Resize to 1280×720 (HD):

**cURL:**
```bash
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/4k-video.mp4"
    },
    "output": {
      "format": "mp4"
    },
    "recipe": {
      "name": "resize",
      "width": 1280,
      "height": 720
    }
  }'
```
**Node.js:**
```javascript
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/4k-video.mp4'
    },
    output: {
      format: 'mp4'
    },
    recipe: {
      name: 'resize',
      width: 1280,
      height: 720
    }
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
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/4k-video.mp4"
        },
        "output": {
            "format": "mp4"
        },
        "recipe": {
            "name": "resize",
            "width": 1280,
            "height": 720
        }
    }
)
data = response.json()
print(data)
```

### Response

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

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Must be `"resize"` |
| `width` | number | No* | Target width in pixels |
| `height` | number | No* | Target height in pixels |

*At least one of `width` or `height` is needed to resize.

### Aspect ratio behavior

| Provided | Behavior |
|----------|----------|
| Both `width` and `height` | Scales to exact dimensions |
| Only `width` | Height auto-calculated to preserve aspect ratio |
| Only `height` | Width auto-calculated to preserve aspect ratio |

## Common presets

| Name | Width | Height | Aspect |
|------|-------|--------|--------|
| 4K UHD | 3840 | 2160 | 16:9 |
| 1080p Full HD | 1920 | 1080 | 16:9 |
| 720p HD | 1280 | 720 | 16:9 |
| 480p SD | 854 | 480 | 16:9 |
| Instagram Square | 1080 | 1080 | 1:1 |
| Instagram Story | 1080 | 1920 | 9:16 |

## Examples

### Scale to width, auto height

Only set `width` to scale proportionally:

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/4k-video.mp4" },
  "output": { "format": "mp4" },
  "recipe": { "name": "resize", "width": 1280 }
}
```

A 3840×2160 input becomes 1280×720 (maintains 16:9).

### Scale for Instagram Story (9:16 vertical)

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/landscape.mp4" },
  "output": { "format": "mp4" },
  "recipe": { "name": "resize", "width": 1080, "height": 1920 }
}
```

**Note:**
Setting exact dimensions that don't match the source aspect ratio will stretch the video. For more control (padding, cropping), use a [custom FFmpeg job](https://xora.sh/docs/guides/ffmpeg/) with the `pad` or `crop` filter.

### Output as WebM

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/video.mp4" },
  "output": { "format": "webm" },
  "recipe": { "name": "resize", "width": 854, "height": 480 }
}
```

## Supported output formats

| Format | Description |
|--------|-------------|
| `mp4` | H.264 in MP4 container |
| `webm` | VP8/VP9 in WebM container |
| `mov` | H.264 in QuickTime container |

---

# Trim / Clip

Source: https://xora.sh/docs/recipes/trim/

The `trim` recipe cuts a segment from your media at a specified start time and duration. Use it to extract highlights, remove intros, or clip a specific scene.

## Basic usage

Extract 30 seconds starting at the 1-minute mark:

**cURL:**
```bash
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/long-video.mp4"
    },
    "output": {
      "format": "mp4"
    },
    "recipe": {
      "name": "trim",
      "startSeconds": 60,
      "durationSeconds": 30
    }
  }'
```
**Node.js:**
```javascript
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/long-video.mp4'
    },
    output: {
      format: 'mp4'
    },
    recipe: {
      name: 'trim',
      startSeconds: 60,
      durationSeconds: 30
    }
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
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/long-video.mp4"
        },
        "output": {
            "format": "mp4"
        },
        "recipe": {
            "name": "trim",
            "startSeconds": 60,
            "durationSeconds": 30
        }
    }
)
data = response.json()
print(data)
```

### Response

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

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Must be `"trim"` |
| `startSeconds` | number | No | Start time in seconds (default: `0`) |
| `durationSeconds` | number | No | Duration of the clip in seconds |

**Tip:**
Decimal values are supported for frame-accurate timing. For example, `startSeconds: 60.5` starts at 1 minute and 500 milliseconds.

## Examples

### Extract the first 10 seconds

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/video.mp4" },
  "output": { "format": "mp4" },
  "recipe": {
    "name": "trim",
    "durationSeconds": 10
  }
}
```

### Skip the first 5 seconds (remove intro)

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/video.mp4" },
  "output": { "format": "mp4" },
  "recipe": {
    "name": "trim",
    "startSeconds": 5
  }
}
```

This produces a clip from 5 seconds to the end of the video.

### Extract a highlight from the middle

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/webinar.mp4" },
  "output": { "format": "mp4" },
  "recipe": {
    "name": "trim",
    "startSeconds": 300,
    "durationSeconds": 120
  }
}
```

Extracts a 2-minute clip starting at the 5-minute mark.

### Trim audio

Trimming works on audio files too:

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/podcast.mp3" },
  "output": { "format": "mp3" },
  "recipe": {
    "name": "trim",
    "startSeconds": 0,
    "durationSeconds": 60
  }
}
```

## Supported output formats

| Format | Type |
|--------|------|
| `mp4` | Video |
| `webm` | Video |
| `mov` | Video |
| `mp3` | Audio |
| `aac` | Audio |
| `wav` | Audio |

**Note:**
If `startSeconds + durationSeconds` exceeds the input duration, the output stops at the end of the file — no error is thrown.

---

# Concat / Merge Files

Source: https://xora.sh/docs/recipes/concat/

The `concat` recipe merges two or more media files into a single output using FFmpeg's concat demuxer with stream copy (`-c copy`). This is fast because it doesn't re-encode — it just joins the files end to end.

**Caution:**
All input files **must share the same codec, sample rate, and format**. For example, you can't concat an MP3 and a WAV directly — convert them to the same format first.

## Basic usage

Merge two MP3 files:

**cURL:**
```bash
curl -X POST https://api.xora.sh/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "recipe",
    "input_files": {
      "in_1": "https://example.com/part1.mp3",
      "in_2": "https://example.com/part2.mp3"
    },
    "output": {
      "format": "mp3"
    },
    "recipe": {
      "name": "concat"
    }
  }'
```
**Node.js:**
```javascript
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_files: {
      in_1: 'https://example.com/part1.mp3',
      in_2: 'https://example.com/part2.mp3'
    },
    output: {
      format: 'mp3'
    },
    recipe: {
      name: 'concat'
    }
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
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_files": {
            "in_1": "https://example.com/part1.mp3",
            "in_2": "https://example.com/part2.mp3"
        },
        "output": {
            "format": "mp3"
        },
        "recipe": {
            "name": "concat"
        }
    }
)
data = response.json()
print(data)
```

### Response

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

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Must be `"concat"` |

## Important: `input_files`, not `input`

The concat recipe uses `input_files` instead of `input`. This is the **only recipe** that works this way:

| Key | Pattern | Example |
|-----|---------|---------|
| `in_1` | First file | `"https://example.com/part1.mp4"` |
| `in_2` | Second file | `"https://example.com/part2.mp4"` |
| `in_3` | Third file (optional) | `"https://example.com/part3.mp4"` |
| … | More files | As many as needed |

Keys must follow the pattern `in_` followed by letters, numbers, or underscores. You need **at least two** entries.

**Note:**
Do **not** include an `input` field when using concat. Use `input_files` only. The API will return a validation error if you provide both.

## Examples

### Merge video segments

Join two MP4 clips:

```json
{
  "mode": "recipe",
  "input_files": {
    "in_1": "https://example.com/intro.mp4",
    "in_2": "https://example.com/main.mp4"
  },
  "output": { "format": "mp4" },
  "recipe": { "name": "concat" }
}
```

### Merge three audio files

```json
{
  "mode": "recipe",
  "input_files": {
    "in_1": "https://example.com/chapter1.mp3",
    "in_2": "https://example.com/chapter2.mp3",
    "in_3": "https://example.com/chapter3.mp3"
  },
  "output": { "format": "mp3" },
  "recipe": { "name": "concat" }
}
```

### Merge many files

You can merge as many files as needed:

```json
{
  "mode": "recipe",
  "input_files": {
    "in_part_a": "https://example.com/a.mp4",
    "in_part_b": "https://example.com/b.mp4",
    "in_part_c": "https://example.com/c.mp4",
    "in_part_d": "https://example.com/d.mp4",
    "in_part_e": "https://example.com/e.mp4"
  },
  "output": { "format": "mp4" },
  "recipe": { "name": "concat" }
}
```

## Supported output formats

| Format | Type |
|--------|------|
| `mp4` | Video |
| `webm` | Video |
| `mov` | Video |
| `mp3` | Audio |
| `aac` | Audio |
| `wav` | Audio |

## How it works

The concat recipe uses FFmpeg's **concat demuxer** with stream copy (`-c copy`). This means:

- **No re-encoding** — files are joined as-is, preserving original quality
- **Very fast** — processing time is minimal regardless of file size
- **Inputs must be compatible** — same codec, sample rate, and format

## Troubleshooting

| Problem | Cause | Fix |
|---------|-------|-----|
| "codec mismatch" error | Input files use different codecs | Transcode all inputs to the same format first |
| Audio out of sync | Different sample rates | Ensure all audio tracks use the same sample rate |
| Only 1 `input_files` entry | Need at least 2 | Add a second file |
| Used `input` instead of `input_files` | Wrong field | Remove `input`, use `input_files` with `in_1`, `in_2`, etc. |

---

# Extract Audio

Source: https://xora.sh/docs/recipes/extract-audio/

The `extractAudio` recipe pulls the first audio track from a video (or audio-in-video container) and saves it as a standalone file.

Xora **probes the input** and chooses the best path:

1. **Stream copy** when the source codec maps to a web-friendly file extension (fast, no quality loss).
2. **Transcode** to your `output.format` fallback when stream copy is not possible (for example AC-3, DTS, or E-AC-3).

**Note:**
`output.format` is a **fallback**, not a forced output type. If the input audio is AAC and you pass `"format": "mp3"`, you still get `.aac` via stream copy — not a re-encoded MP3.

## How output format is chosen

After probing, Xora resolves the output file extension:

| Source audio codec | Output file | Method |
|-------------------|-------------|--------|
| `mp3` | `.mp3` | Stream copy |
| `aac` | `.aac` | Stream copy |
| `opus` | `.opus` | Stream copy |
| `vorbis` | `.ogg` | Stream copy |
| `flac` | `.flac` | Stream copy |
| `pcm_*` (for example `pcm_s16le`) | `.wav` | Stream copy |
| Anything else (for example `ac3`, `dts`, `eac3`) | `.mp3`, `.aac`, or `.wav` | Transcode to `output.format` |

The default output key is `outputs/{jobId}/result.{ext}` where `{ext}` is the **resolved** extension above — not always the extension from `output.format`.

### Fallback transcode settings

When transcoding is required, `output.format` must be one of `mp3`, `aac`, or `wav`:

| `output.format` | Encoder | Notes |
|-----------------|---------|-------|
| `mp3` (default if invalid) | `libmp3lame` | Best universal compatibility |
| `aac` | AAC @ 192 kbps | Smaller than MP3 at similar quality |
| `wav` | 16-bit PCM | Lossless, large files |

**Caution:**
Jobs are **rejected** if the input has no audio stream (`UNSUPPORTED_JOB`).

## Basic usage

Request MP3 as the fallback (used only when stream copy is not possible):

**cURL:**
```bash
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/interview.mp4"
    },
    "output": {
      "format": "mp3"
    },
    "recipe": {
      "name": "extractAudio"
    }
  }'
```
**Node.js:**
```javascript
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/interview.mp4'
    },
    output: {
      format: 'mp3'
    },
    recipe: {
      name: 'extractAudio'
    }
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
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/interview.mp4"
        },
        "output": {
            "format": "mp3"
        },
        "recipe": {
            "name": "extractAudio"
        }
    }
)
data = response.json()
print(data)
```

### Response

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

When the job completes, check the output file metadata (extension and MIME type) — it reflects the resolved format, which may differ from `output.format`.

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Must be `"extractAudio"` |
| `startSeconds` | number | No | Start offset into the input (seconds) |
| `durationSeconds` | number | No | Maximum duration to extract (seconds) |
| `stageInput` | boolean | No | Set `false` to stream directly from your URL when the host supports HTTP byte ranges (skips copying the full video to engine storage). Default: `true`. See [Input Staging](https://xora.sh/docs/guides/input-staging/). |

| Job field | Type | Required | Description |
|-----------|------|----------|-------------|
| `output.format` | string | Yes | Fallback transcode target: `mp3`, `aac`, or `wav`. Ignored when stream copy applies. |

**Tip:**
For long videos on range-capable CDNs, add `"stageInput": false` to cut job time roughly in half (no full-file staging step).

## Examples

### AAC in MP4 → `.aac` (stream copy)

Input has AAC audio; `output.format` is only used if copy is impossible:

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/video.mp4" },
  "output": { "format": "mp3" },
  "recipe": { "name": "extractAudio" }
}
```

Completed output: `result.aac` (not `result.mp3`).

### AC-3 in MKV → `.mp3` (transcode)

Unsupported for stream copy; falls back to `output.format`:

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/movie.mkv" },
  "output": { "format": "mp3" },
  "recipe": { "name": "extractAudio" }
}
```

Completed output: `result.mp3`.

### Fast extract (skip staging)

```json
{
  "mode": "recipe",
  "input": { "url": "https://cdn.example.com/video.mp4" },
  "output": { "format": "mp3" },
  "recipe": { "name": "extractAudio" },
  "stageInput": false
}
```

### Transcode fallback to AAC

Use when you know the source needs re-encoding and you prefer AAC over MP3:

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/video.mkv" },
  "output": { "format": "aac" },
  "recipe": { "name": "extractAudio" }
}
```

### Custom `outputPath`

If you set `outputPath`, the file extension must match `output.format` at request time. The engine still resolves copy vs transcode from the source; prefer the default output key when you want the resolved extension (for example `.aac` from an AAC source).

## Browser and player compatibility

Stream-copied formats vary in HTML5 `<audio>` support:

| Extension | Broad web support | Notes |
|-----------|-------------------|-------|
| `.mp3`, `.aac`, `.wav` | Excellent | Safest for universal delivery |
| `.opus`, `.flac`, `.ogg` | Good on modern browsers | Older Safari / iOS may need a transcode fallback |

If you need guaranteed playback everywhere, use a source that transcodes (for example AC-3 → `output.format: "mp3"`) or post-process to MP3.

## Common use cases

| Scenario | Suggested `output.format` | Typical result |
|----------|---------------------------|----------------|
| Podcast from video interview | `mp3` | `.aac` or `.mp3` depending on source |
| Audio for transcription API | `mp3` | `.mp3` if source is AC-3/DTS; else copy |
| Music from live performance | `aac` | Copy if already AAC/FLAC; else transcode |
| Audio for further editing | `wav` | `.wav` if PCM source; else transcode to WAV |
| Voice memo from video | `mp3` | Copy if MP3/AAC; else MP3 transcode |

**Tip:**
Need audio from only part of a video? Use `startSeconds` / `durationSeconds` on the recipe, [trim](https://xora.sh/docs/recipes/trim/) first, or use a [custom FFmpeg job](https://xora.sh/docs/guides/ffmpeg/) for a single-pass pipeline.

## Related

- [Output formats](https://xora.sh/docs/output-formats/) — format reference and recipe matrix
- [Input staging](https://xora.sh/docs/guides/input-staging/) — when to set `stageInput: false`
- [Transcode](https://xora.sh/docs/recipes/transcode/) — full container/codec conversion (always re-encodes to `output.format`)

---

# Generate Thumbnail

Source: https://xora.sh/docs/recipes/thumbnail/

The `thumbnail` recipe captures a single frame from a video at a specified time and saves it as a JPG or PNG image. Ideal for video previews, social media cards, and content management systems.

## Basic usage

Capture a frame at the 1-second mark:

**cURL:**
```bash
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/video.mp4"
    },
    "output": {
      "format": "jpg"
    },
    "recipe": {
      "name": "thumbnail",
      "seekSeconds": 1
    }
  }'
```
**Node.js:**
```javascript
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/video.mp4'
    },
    output: {
      format: 'jpg'
    },
    recipe: {
      name: 'thumbnail',
      seekSeconds: 1
    }
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
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/video.mp4"
        },
        "output": {
            "format": "jpg"
        },
        "recipe": {
            "name": "thumbnail",
            "seekSeconds": 1
        }
    }
)
data = response.json()
print(data)
```

### Response

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

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Must be `"thumbnail"` |
| `seekSeconds` | number | No | Time in seconds to capture the frame (default: `0`) |

**Tip:**
Avoid `seekSeconds: 0` — the first frame is often a black or transitional frame. Try `1` or `2` for a more representative image.

## Output format options

| Format | Best for |
|--------|----------|
| `jpg` | Smaller file size, great for web thumbnails |
| `png` | Lossless quality, supports transparency |

## Examples

### Capture at 5 seconds

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/video.mp4" },
  "output": { "format": "jpg" },
  "recipe": { "name": "thumbnail", "seekSeconds": 5 }
}
```

### Capture as PNG (lossless)

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/video.mp4" },
  "output": { "format": "png" },
  "recipe": { "name": "thumbnail", "seekSeconds": 3 }
}
```

### Capture from the middle of a long video

For a 10-minute video, grab a frame at the halfway point:

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/webinar.mp4" },
  "output": { "format": "jpg" },
  "recipe": { "name": "thumbnail", "seekSeconds": 300 }
}
```

## Completed response

When the job finishes, you get a signed URL to the image:

```json
{
  "jobId": "01JXYZ1234ABCDEF56789000",
  "state": "completed",
  "progress": 100,
  "output": {
    "signedUrl": "https://cdn.xora.sh/...signed-url..."
  },
  "output_files": {
    "output": {
      "filename": "output.jpg",
      "file_type": "image",
      "file_format": "jpg",
      "mime_type": "image/jpeg",
      "width": 1920,
      "height": 1080,
      "storage_url": "https://cdn.xora.sh/...signed-url..."
    }
  }
}
```

## Common use cases

| Scenario | `seekSeconds` | Format |
|----------|--------------|--------|
| Video preview card | `1`–`2` | `jpg` |
| Social media share image | `3`–`5` | `jpg` |
| High-quality screenshot | Any | `png` |
| E-commerce product video preview | `0.5` | `jpg` |

**Note:**
Thumbnails are one of the fastest jobs — typically completing in just a few seconds.

**Tip:**
Need an animated preview instead? Use a [custom FFmpeg job](https://xora.sh/docs/guides/ffmpeg/) to generate an animated GIF. Check the "GIF preview" starter preset for an example.

---

# Edit Proxy

Source: https://xora.sh/docs/recipes/proxy/

The `proxy` recipe creates an **edit proxy** — always re-encoded for timeline scrubbing. Unlike [webReady](https://xora.sh/docs/recipes/web-ready/), it never passthroughs or xora-copies the source.

Scale is **optional**. You can create a 1080p edit proxy without downscaling, or a smaller 720p proxy for faster editing.

## Basic usage

**cURL:**
```bash
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/master.mov" },
    "output": { "format": "mp4" },
    "recipe": { "name": "proxy", "crf": 30 }
  }'
```
**Node.js:**
```javascript
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/master.mov' },
    output: { format: 'mp4' },
    recipe: { name: 'proxy', crf: 30 }
  })
});
```

## 720p scrub-friendly proxy

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/master.mov" },
  "output": { "format": "mp4" },
  "recipe": {
    "name": "proxy",
    "scaleDown": true,
    "height": 720,
    "crf": 30,
    "gop": "all_intra"
  }
}
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | string | Yes | — | Must be `"proxy"` |
| `scaleDown` | boolean | No | `false` | Downscale when true |
| `width` | number | No | auto | Output width when scaling |
| `height` | number | No | — | Output height when `scaleDown` is true |
| `crf` | number | No | `32` | Quality (lower = higher quality, larger file) |
| `bitrateKbps` | number | No | — | Target video bitrate; overrides CRF |
| `gop` | string | No | `per_second` | `per_second` (1 keyframe/sec) or `all_intra` (every frame) |
| `startSeconds` | number | No | — | Optional clip start |
| `durationSeconds` | number | No | — | Optional clip duration |

**Caution:**
`all_intra` produces much larger files but enables frame-accurate scrubbing in editors.

## Output format

`proxy` requires MP4 output:

```json
"output": { "format": "mp4" }
```

---

# Probe Media Metadata

Source: https://xora.sh/docs/recipes/probe/

Use **`mode: "probe"`** to run **ffprobe** against an input URL. When the job completes, enriched metadata is returned on the job record under **`probe`** — no output file is written and no storage upload occurs.

The response preserves the raw ffprobe shape (`format`, `streams`, `chapters`, `programs`) and adds convenience flags such as `hasVideo`, `hasAudio`, `isVideo`, `isAudio`, `isImage`, `isHdr`, stream counts, codec names, dimensions, duration, size, bitrate, and frame rate.

Use this when you need media metadata before deciding which encode recipe to run, or to power upload validation and CMS previews.

## Basic usage

**cURL:**
```bash
curl -X POST https://api.xora.sh/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "probe",
    "input": {
      "url": "https://example.com/video.mp4"
    }
  }'
```
**Node.js:**
```javascript
const create = await fetch('https://api.xora.sh/v1/jobs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    mode: 'probe',
    input: { url: 'https://example.com/video.mp4' },
  }),
});

const { id } = await create.json();

const status = await fetch(`https://api.xora.sh/v1/jobs/${id}`, {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
});
const job = await status.json();
console.log(job.probe);
```

Poll `GET /v1/jobs/:id` (or use a [webhook](https://xora.sh/docs/guides/webhooks/)) until `state` is `completed`. Read metadata from **`probe`**, not `output` or `output_files`.

## Request shape

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `mode` | string | Yes | Must be `"probe"` |
| `input.url` | string | One of | HTTPS or S3 URL of the media file to inspect |
| `input.uploadId` | string | One of | Id from [`POST /v1/uploads`](https://xora.sh/docs/guides/direct-uploads/), for locally uploaded files. Provide exactly one of `url` or `uploadId`. |
| `stageInput` | boolean | No | Skip input staging when your origin supports byte ranges. Defaults to `true`. See [Input staging](https://xora.sh/docs/guides/input-staging/). |
| `webhookUrl` | string | No | Optional webhook for completion notification |

Probe jobs do not accept `output`, `recipe`, `outputPath`, or preset bodies.

## Response shape

When the job completes, `probe` includes:

- Raw ffprobe fields under `format`, `streams`, `chapters`, and `programs`
- Top-level convenience flags such as `hasVideo`, `hasAudio`, `isHdr`, `durationSeconds`, `width`, `height`, `videoCodec`, and `audioCodec`
- A nested `flags` object with the same convenience fields for programmatic access

Example (truncated):

```json
{
  "id": "01KSD388ERH85FGR79JCW0SZZ0",
  "state": "completed",
  "mode": "probe",
  "probe": {
    "hasVideo": true,
    "hasAudio": true,
    "isVideo": true,
    "durationSeconds": 125.4,
    "width": 1920,
    "height": 1080,
    "videoCodec": "h264",
    "audioCodec": "aac",
    "flags": {
      "hasVideo": true,
      "hasAudio": true,
      "isVideo": true
    },
    "format": { "duration": "125.400000", "bit_rate": "4500000" },
    "streams": []
  }
}
```

**Note:**
Probe jobs do not transcode or remux media. They only inspect the input and return metadata on the job record. For web delivery decisions based on probe results, follow up with [webReady](https://xora.sh/docs/recipes/web-ready/) or [compress](https://xora.sh/docs/recipes/compress/).

## Related

- [Input staging](https://xora.sh/docs/guides/input-staging/) — set `stageInput: false` when your origin supports byte ranges
- [Web Ready Video](https://xora.sh/docs/recipes/web-ready/) — uses internal probing to pick passthrough vs encode
- [Output formats](https://xora.sh/docs/output-formats/) — media formats for transcode recipes

---

# FFmpeg MCP Server

Source: https://xora.sh/docs/guides/mcp/

The Xora FFmpeg MCP server gives an AI agent real FFmpeg as tool calls. The
agent writes the FFmpeg arguments (or picks a recipe), Xora runs the job in the
cloud, and the agent gets a signed URL for the output. Nothing needs to be
installed where the agent runs.

The server is a remote [MCP](https://modelcontextprotocol.io) server at
`https://api.xora.sh/v1/mcp` (Streamable HTTP). It authenticates with the same
API keys as the REST API and its tools call the same job routes — plan limits,
billing, and structured errors behave identically whether a job comes from
`curl` or from an agent's tool call. For an overview of every way an agent can
reach Xora, see [FFmpeg for AI agents](https://xora.sh/agents/).

## Connect

Two ways to authenticate:

- **OAuth** — clients with OAuth support (claude.ai custom connectors, Claude
  Desktop connectors) discover the flow automatically: add the endpoint URL,
  sign in with your Xora dashboard account, and approve the consent prompt.
- **API key** — an `Authorization: Bearer` header carrying a Xora API key
  (create one in the [dashboard](https://xora.sh/app)), for headless agents,
  CI, and any client that can set a request header.

**claude.ai & Claude Desktop:**
**Settings → Connectors → Add custom connector**, then paste:

```
https://api.xora.sh/v1/mcp
```

The OAuth flow starts automatically: you'll sign in to your Xora
dashboard (if you aren't already) and approve the access prompt. No key
to copy. Revoke any time from the consent screen's dashboard link.
**Claude Code:**
```bash
claude mcp add --transport http xora https://api.xora.sh/v1/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```
**Cursor:**
Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project):

```json
{
  "mcpServers": {
    "xora": {
      "url": "https://api.xora.sh/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```
**TypeScript SDK:**
```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(
  new URL('https://api.xora.sh/v1/mcp'),
  { requestInit: { headers: { authorization: `Bearer ${process.env.XORA_API_KEY}` } } }
);
const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);

const { tools } = await client.listTools();
// create_upload, create_job, get_job, list_recipes, cancel_job
console.log(tools.map((t) => t.name));
```

To verify a connection without writing code:

```bash
npx @modelcontextprotocol/inspector --cli https://api.xora.sh/v1/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --method tools/list
```

## Tools

| Tool | What it does |
|------|--------------|
| `create_job` | Create an asynchronous job — `mode: "recipe"` (named operation), `mode: "ffmpeg"` (raw argument array with `{{in_1}}`/`{{out_1}}` placeholders), or `mode: "probe"` (ffprobe metadata only). Returns `{ id, state }` immediately. |
| `get_job` | Fetch a job by id: state, progress, signed download URLs when completed, `probe` metadata for probe jobs, structured `error` for failed or rejected jobs. |
| `create_upload` | Get a presigned URL for a local file that has no public address. Returns `{ uploadId, url, expiresAt, maxBytes }`; the agent `PUT`s the bytes, then passes `uploadId` to `create_job`. |
| `list_recipes` | Static catalog of the nine recipes with parameters, constraints, and output formats. Costs nothing to call. |
| `cancel_job` | Cancel a queued or running job. |

The server also publishes instructions during the MCP handshake, so most agents
discover the workflow on their own: call `list_recipes` once, `create_job`,
then poll `get_job` until the state is terminal
(`completed | failed | rejected | cancelled`).

## Working with local files

`create_job` needs an input Xora can read. When the agent is holding a file
path rather than a URL, `create_upload` provides the destination:

1. Call `create_upload` with `{ "sizeBytes": 734003200, "filename": "interview.mov" }`.
   The declared size is checked against the plan's per-file limit up front.
2. `PUT` the raw file bytes to the returned `url` — a plain HTTP request the
   agent makes itself, with no `Authorization` header and no form encoding. The
   URL is valid for one hour.
3. Call `create_job` with `"input": { "uploadId": "…" }` in place of
   `"input": { "url": … }`.

Uploads survive for three days and can back any number of jobs in that window,
so an agent producing several outputs from one source should upload once and
reuse the id. See [direct uploads](https://xora.sh/docs/guides/direct-uploads/) for limits and
the REST equivalent.

## The agent loop

A typical `create_job` tool call:

```json
{
  "mode": "recipe",
  "input": { "url": "https://example.com/interview.mov" },
  "output": { "format": "mp4" },
  "recipe": { "name": "compress", "crf": 23 }
}
```

…returns `{ "id": "01JXYZ…", "state": "queued" }`. Polling `get_job` with that
id eventually returns the terminal record:

```json
{
  "id": "01JXYZ1234ABCDEF56789000",
  "state": "completed",
  "progress": 100,
  "output": {
    "signedUrl": "https://cdn.xora.sh/...signed-url..."
  }
}
```

Signed URLs expire, so agents should download promptly (or configure
[BYOB delivery](https://xora.sh/docs/guides/storage-providers/) so outputs land in your own
bucket with nothing to collect). Pass `webhookUrl` on `create_job` to receive a
[webhook](https://xora.sh/docs/guides/webhooks/) on the terminal state instead of polling.

## Errors agents can branch on

Tool failures come back as MCP error results whose text is the API's structured
error JSON, plus the HTTP status:

```json
{
  "httpStatus": 402,
  "error": {
    "code": "LIMIT_EXCEEDED",
    "message": "Plan credits exhausted",
    "feature": "credits",
    "retryable": false
  }
}
```

| `error.code` | HTTP | Meaning |
|--------------|------|---------|
| `VALIDATION_ERROR` | 400 | The request body is wrong — the message says which field. |
| `LIMIT_EXCEEDED` | 402 | Plan credits or storage exhausted; new jobs are refused until reset or upgrade. |
| `PLAN_REQUIRED` | 403 | The feature (for example BYOB) isn't on the current plan. |
| `NOT_FOUND` | 404 | No job with that id on this account. |

Failed and rejected jobs bill nothing — see
[error handling](https://xora.sh/docs/guides/error-handling/) for the difference between the
two.

**Note:**
The endpoint is stateless: no session to keep alive, nothing stored between
requests. Each tool call authenticates with your API key and is scoped to your
account, exactly like a REST call. Revoke the key in the dashboard to cut off a
connected agent.

## The Xora skill

For Claude specifically, there's also an [Agent Skill](https://xora.sh/skills/xora/SKILL.md)
— judgment the tool schemas can't carry: which recipe fits which ask, when to
probe first, how to handle a local file, cost-saving habits like
`stageInput: false`, and how to branch on error codes. It complements the MCP
server (and covers plain REST when MCP isn't connected).

Install it for Claude Code:

```bash
mkdir -p ~/.claude/skills/xora && \
  curl -fsSL https://xora.sh/skills/xora/SKILL.md -o ~/.claude/skills/xora/SKILL.md
```

Use `.claude/skills/xora/SKILL.md` inside a repo to share it with a project
instead, or upload it as a custom skill in claude.ai.

## Step-by-step tutorials

- [How to give Claude FFmpeg with an MCP server](https://xora.sh/blog/give-claude-ffmpeg-mcp/) — Claude Code, claude.ai and Claude Desktop.
- [Run FFmpeg jobs from Cursor with MCP](https://xora.sh/blog/ffmpeg-mcp-cursor/) — set up `mcp.json`, then turn a tested job into REST code.

## FAQ

### Can the agent run any FFmpeg command?

Yes. `create_job` with `mode: "ffmpeg"` takes a raw argument array, including
`-filter_complex` and multiple inputs (`input_files` keyed `in_1`, `in_2`, …).
Output file names in `output_files` use letters, numbers and underscores plus
an extension, for example `clip_720p.mp4`. See
[custom FFmpeg args](https://xora.sh/docs/guides/ffmpeg/).

### Which clients work with the Xora MCP server?

Any client that supports remote MCP servers over Streamable HTTP. The tabs
above show Claude Code, claude.ai and Claude Desktop, Cursor, and the MCP
TypeScript SDK.

### Is there a local (stdio) version?

No local server is needed: the agent only sends JSON, and FFmpeg runs on Xora.
Clients that cannot connect to a remote server can call the
[REST API](https://xora.sh/docs/api/) directly. [`/llms.txt`](https://xora.sh/llms.txt) describes the full
workflow for agents.

### Do MCP jobs cost more than REST jobs?

No. A tool call creates the same job as `POST /v1/jobs` and bills the same
credits. Failed, rejected and cancelled jobs cost nothing. See
[pricing](https://xora.sh/pricing/).

---

# Custom FFmpeg Jobs

Source: https://xora.sh/docs/guides/ffmpeg/

When the built-in [recipes](https://xora.sh/docs/recipes/compress/) don't cover your use case, you can pass your own FFmpeg argument array directly. This gives you full control over filters, codecs, and encoding parameters.

**Tip:**
Add `"stageInput": false` to stream inputs directly from range-capable URLs instead of copying them to engine storage first. See [Input Staging](https://xora.sh/docs/guides/input-staging/).

## How FFmpeg mode works

Set `mode` to `"ffmpeg"` and provide an `ffmpeg.args` array. Xora runs your command with a full FFmpeg build (all codecs and filters available).

There are two input/output patterns:

**Single-file (simple):**

  Use `input` + `output` with `{{input}}` / `{{output}}` placeholders:

  ```json
  {
"mode": "ffmpeg",
"input": { "url": "https://example.com/video.mp4" },
"output": { "format": "mp4" },
"ffmpeg": {
  "args": ["-i", "{{input}}", "-vf", "scale=640:-1", "{{output}}"]
}
  }
  ```

**Multi-file (advanced):**

  Use `input_files` + `output_files` with `{{in_*}}` / `{{out_*}}` placeholders:

  ```json
  {
"mode": "ffmpeg",
"input_files": { "in_1": "https://example.com/video.mp4" },
"output_files": { "out_1": "result.mp4" },
"ffmpeg": {
  "args": ["-i", "{{in_1}}", "-c:v", "libx264", "-crf", "23", "{{out_1}}"]
}
  }
  ```

## Single-file mode

The simplest way — one input, one output. Use `{{input}}` and `{{output}}` as placeholders in your args:

**cURL:**
```bash
curl -X POST https://api.xora.sh/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "ffmpeg",
    "input": { "url": "https://example.com/video.mp4" },
    "output": { "format": "mp4" },
    "ffmpeg": {
      "args": [
        "-i", "{{input}}",
        "-vf", "scale=1280:-1",
        "-c:v", "libx264",
        "-crf", "23",
        "-c:a", "aac",
        "{{output}}"
      ]
    }
  }'
```
**Node.js:**
```javascript
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: 'ffmpeg',
    input: { url: 'https://example.com/video.mp4' },
    output: { format: 'mp4' },
    ffmpeg: {
      args: [
        '-i', '{{input}}',
        '-vf', 'scale=1280:-1',
        '-c:v', 'libx264',
        '-crf', '23',
        '-c:a', 'aac',
        '{{output}}'
      ]
    }
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
import requests

response = requests.post(
    "https://api.xora.sh/v1/jobs",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "mode": "ffmpeg",
        "input": {"url": "https://example.com/video.mp4"},
        "output": {"format": "mp4"},
        "ffmpeg": {
            "args": [
                "-i", "{{input}}",
                "-vf", "scale=1280:-1",
                "-c:v", "libx264",
                "-crf", "23",
                "-c:a", "aac",
                "{{output}}"
            ]
        }
    }
)
data = response.json()
print(data)
```

### Placeholders

| Placeholder | Replaced with |
|-------------|---------------|
| `{{input}}` | Path to the downloaded input file |
| `{{output}}` | Path for the output file (extension from `output.format`) |

## Multi-file mode

For commands with multiple inputs or outputs, use named `input_files` and `output_files`:

**cURL:**
```bash
curl -X POST https://api.xora.sh/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "ffmpeg",
    "input_files": {
      "in_1": "https://example.com/video.mp4",
      "in_2": "https://example.com/watermark.png"
    },
    "output_files": {
      "out_1": "watermarked.mp4"
    },
    "ffmpeg": {
      "args": [
        "-i", "{{in_1}}",
        "-i", "{{in_2}}",
        "-filter_complex", "overlay=10:10",
        "-c:v", "libx264",
        "{{out_1}}"
      ]
    }
  }'
```
**Node.js:**
```javascript
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: 'ffmpeg',
    input_files: {
      in_1: 'https://example.com/video.mp4',
      in_2: 'https://example.com/watermark.png'
    },
    output_files: {
      out_1: 'watermarked.mp4'
    },
    ffmpeg: {
      args: [
        '-i', '{{in_1}}',
        '-i', '{{in_2}}',
        '-filter_complex', 'overlay=10:10',
        '-c:v', 'libx264',
        '{{out_1}}'
      ]
    }
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
import requests

response = requests.post(
    "https://api.xora.sh/v1/jobs",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "mode": "ffmpeg",
        "input_files": {
            "in_1": "https://example.com/video.mp4",
            "in_2": "https://example.com/watermark.png"
        },
        "output_files": {
            "out_1": "watermarked.mp4"
        },
        "ffmpeg": {
            "args": [
                "-i", "{{in_1}}",
                "-i", "{{in_2}}",
                "-filter_complex", "overlay=10:10",
                "-c:v", "libx264",
                "{{out_1}}"
            ]
        }
    }
)
data = response.json()
print(data)
```

### Naming rules

| Field | Key pattern | Example |
|-------|-------------|---------|
| `input_files` | `in_` + alphanumeric/underscore | `in_1`, `in_video`, `in_audio_track` |
| `output_files` | `out_` + alphanumeric/underscore | `out_1`, `out_video`, `out_thumbnail` |

Output file values must be a filename with an extension (e.g., `result.mp4`, `audio.mp3`).

**Note:**
Use either single-file mode (`input`/`output`) **or** multi-file mode (`input_files`/`output_files`) — not both at the same time.

**Tip:**
Single-file mode also accepts `input: { uploadId }` for a file you sent through
[direct uploads](https://xora.sh/docs/guides/direct-uploads/) instead of hosting. Multi-file
mode (`input_files`) takes URLs only.

## Examples

### Generate animated GIF

Create an 8fps, 320px-wide GIF preview:

```json
{
  "mode": "ffmpeg",
  "input_files": { "in_1": "https://example.com/video.mp4" },
  "output_files": { "out_1": "preview.gif" },
  "ffmpeg": {
    "args": [
      "-i", "{{in_1}}",
      "-vf", "fps=8,scale=320:-1:flags=lanczos",
      "-an", "-loop", "0",
      "{{out_1}}"
    ]
  }
}
```

### Add a watermark overlay

```json
{
  "mode": "ffmpeg",
  "input_files": {
    "in_1": "https://example.com/video.mp4",
    "in_2": "https://example.com/logo.png"
  },
  "output_files": { "out_1": "branded.mp4" },
  "ffmpeg": {
    "args": [
      "-i", "{{in_1}}",
      "-i", "{{in_2}}",
      "-filter_complex", "overlay=W-w-10:H-h-10",
      "-c:v", "libx264", "-crf", "23",
      "-c:a", "copy",
      "{{out_1}}"
    ]
  }
}
```

### Extract a 5-second clip as GIF

```json
{
  "mode": "ffmpeg",
  "input": { "url": "https://example.com/video.mp4" },
  "output": { "format": "gif" },
  "ffmpeg": {
    "args": [
      "-ss", "10", "-t", "5",
      "-i", "{{input}}",
      "-vf", "fps=10,scale=480:-1:flags=lanczos",
      "-loop", "0",
      "{{output}}"
    ]
  }
}
```

### Convert to VP9 WebM with custom bitrate

```json
{
  "mode": "ffmpeg",
  "input": { "url": "https://example.com/video.mp4" },
  "output": { "format": "webm" },
  "ffmpeg": {
    "args": [
      "-i", "{{input}}",
      "-c:v", "libvpx-vp9",
      "-b:v", "1M",
      "-c:a", "libopus",
      "{{output}}"
    ]
  }
}
```

### Remux without re-encoding (fast)

Change the container without re-encoding — near instant:

```json
{
  "mode": "ffmpeg",
  "input": { "url": "https://example.com/video.mkv" },
  "output": { "format": "mp4" },
  "ffmpeg": {
    "args": ["-i", "{{input}}", "-c", "copy", "{{output}}"]
  }
}
```

## Security restrictions

FFmpeg jobs run inside a sandboxed environment. The following are **blocked**:

- **Shell metacharacters** — no pipes (`|`), backticks, `$(...)`, etc.
- **Unsafe protocols** — only `https://` and local managed paths are allowed
- **Arbitrary output paths** — output can only go to the managed working directory
- **Unbounded streams** — commands that could generate infinite output are rejected

If your command fails validation, you'll get a `VALIDATION_ERROR` or `UNSUPPORTED_COMMAND` error with a description of what was rejected.

**Caution:**
The `ffmpeg.args` field must be a **JSON array of strings**, not a single command string. Each argument is a separate array element.

**Correct:** `["args": ["-i", "{{input}}", "-vf", "scale=640:-1", "{{output}}"]]`

**Wrong:** `["args": ["-i {{input}} -vf scale=640:-1 {{output}}"]]`

## Limits

| Limit | Value |
|-------|-------|
| Max args | 128 elements |
| Job timeout | 15 minutes |
| Max working disk | 10 GB |

**Note:**
FFmpeg jobs always run as a single processing unit — they are not split into parallel segments like recipe jobs. For very long videos, prefer recipe mode for faster processing.

## Supported output formats

All 9 formats are available in FFmpeg mode: `mp4`, `webm`, `mov`, `gif`, `mp3`, `aac`, `wav`, `jpg`, `png`.

---

# Direct Uploads

Source: https://xora.sh/docs/guides/direct-uploads/

Jobs normally take a URL Xora can fetch. When your file only exists on a laptop,
a CI runner, or inside a private network, **direct uploads** give you somewhere
to put it: ask for a presigned upload, `PUT` the bytes, then reference the
upload by id when you create the job.

```
POST /v1/uploads ──▶ { uploadId, url, expiresAt, maxBytes }
      │
      ├── PUT <url>  (raw file bytes, no auth header)
      │
      └── POST /v1/jobs  { "input": { "uploadId": "…" }, … }
```

Uploads are **transient input storage**, not a media library: objects are
deleted automatically 3 days after upload. Job *outputs* are unaffected and
persist until you delete them (or land in [your own bucket](https://xora.sh/docs/guides/storage-providers/)).

## Upload a file

1. **Request a presigned upload**

    Send the size of the file you're about to upload. Xora checks it against
    your plan's per-file limit before handing back a URL, so you find out
    you're over the cap before spending time on the transfer.

**cURL:**
```bash
curl -X POST https://api.xora.sh/v1/uploads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sizeBytes": 734003200,
    "filename": "interview-cam-a.mp4"
  }'
```
**Node.js:**
```javascript
import { statSync } from 'node:fs';

const path = 'interview-cam-a.mp4';
const res = await fetch('https://api.xora.sh/v1/uploads', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.XORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sizeBytes: statSync(path).size,
    filename: path,
  }),
});
const { uploadId, url } = await res.json();
```
**Python:**
```python
import os, requests

path = "interview-cam-a.mp4"
res = requests.post(
    "https://api.xora.sh/v1/uploads",
    headers={
        "Authorization": f"Bearer {os.environ['XORA_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"sizeBytes": os.path.getsize(path), "filename": path},
)
upload = res.json()
```

    You get back a `201` with the presigned URL:

    ```json
    {
      "uploadId": "01KSD388ERH85FGR79JCW0SZZ0",
      "url": "https://xora-uploads.s3.us-east-1.amazonaws.com/uploads/user_2ab…/01KSD388…mp4?X-Amz-Signature=…",
      "expiresAt": "2026-07-24T13:00:00.000Z",
      "maxBytes": 2147483648
    }
    ```

    `filename` is optional and only its extension is used, to give the stored
    object a sensible suffix. `maxBytes` is the ceiling this upload will accept.

2. **PUT the file bytes**

    Send the raw file as the request body — a single `PUT`, no
    `Authorization` header (the signature is in the URL), and no form encoding.
    The URL is valid for **one hour**.

**cURL:**
```bash
curl -X PUT "PRESIGNED_URL_HERE" \
  --upload-file interview-cam-a.mp4
```
**Node.js:**
```javascript
import { openAsBlob } from 'node:fs';

await fetch(url, {
  method: 'PUT',
  body: await openAsBlob(path),
});
```
**Python:**
```python
with open(path, "rb") as f:
    requests.put(upload["url"], data=f)
```

    A `200` with an `ETag` header means the object is stored. Browsers can
    `PUT` directly too — the bucket allows cross-origin `PUT` from the Xora
    dashboard origin, so an upload never proxies through your own server.

3. **Create a job against the upload**

    Swap `input.url` for `input.uploadId`. Everything else about the job body
    is unchanged.

**cURL:**
```bash
curl -X POST https://api.xora.sh/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "recipe",
    "input": { "uploadId": "01KSD388ERH85FGR79JCW0SZZ0" },
    "output": { "format": "mp4" },
    "recipe": { "name": "compress", "crf": 23 }
  }'
```
**Node.js:**
```javascript
const job = await fetch('https://api.xora.sh/v1/jobs', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.XORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    mode: 'recipe',
    input: { uploadId },
    output: { format: 'mp4' },
    recipe: { name: 'compress', crf: 23 },
  }),
}).then((r) => r.json());
```
**Python:**
```python
job = requests.post(
    "https://api.xora.sh/v1/jobs",
    headers={
        "Authorization": f"Bearer {os.environ['XORA_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "mode": "recipe",
        "input": {"uploadId": upload["uploadId"]},
        "output": {"format": "mp4"},
        "recipe": {"name": "compress", "crf": 23},
    },
).json()
```

    From here it's an ordinary job — poll `GET /v1/jobs/{id}` or take a
    [webhook](https://xora.sh/docs/guides/webhooks/), then download the output.

## Where uploads work

`input.uploadId` is accepted anywhere a single `input.url` is:

| Mode | Supported |
|------|-----------|
| `mode: "recipe"` (single-input recipes) | Yes |
| `mode: "probe"` | Yes |
| `mode: "ffmpeg"` with `input` / `output` | Yes |
| `mode: "ffmpeg"` with `input_files` / `output_files` | No — multi-input jobs take URLs |
| `concat` recipe (`input_files`) | No — takes URLs |
| Running a saved [preset](https://xora.sh/docs/guides/presets/) | Recipe presets: yes — pass `input: { uploadId }`. ffmpeg/concat presets: URL-only |

`input` accepts exactly one of `url` or `uploadId`. Sending both, or neither,
is a `400 VALIDATION_ERROR`.

**Tip:**
Uploads land in the same AWS region the processing workers run in, so Xora
reads them without making a staging copy first — the upload *is* the staged
input. There's nothing to tune: `stageInput` is irrelevant for uploaded files.
See [input staging](https://xora.sh/docs/guides/input-staging/) for how this works with
external URLs.

## Limits and lifetime

| | |
|---|---|
| **Max file size** | 5 GB, or your plan's per-file input limit if it's lower |
| **Upload URL validity** | 1 hour from creation |
| **Object retention** | 3 days, then deleted automatically |
| **Reuse** | An upload can be used by any number of jobs until it expires |
| **Cost** | Uploading is free — inputs are never billed. See [pricing](https://xora.sh/pricing/) |

Uploads are scoped to the account that created them: another account's
`uploadId` reads as not found.

### Re-running a job on the same upload

Nothing is consumed by creating a job. If a job fails and you want to retry
with different settings, or you want a thumbnail *and* an MP4 from one source,
create a second job with the same `uploadId` — no re-upload needed, as long as
the 3-day window hasn't passed.

### Files larger than 5 GB

Direct uploads use a single `PUT`, which caps at 5 GB. If your plan allows
larger inputs (Scale allows 6 GB), host the file and pass `input.url` instead.
Multipart upload support is planned.

## Errors

| `error.code` | HTTP | Meaning |
|---|---|---|
| `LIMIT_EXCEEDED` | 402 | The declared `sizeBytes`, or the file you actually uploaded, is over your plan's per-file limit. |
| `VALIDATION_ERROR` | 400 | On `/v1/uploads`: `sizeBytes` is missing, not positive, or over 5 GB. On `/v1/jobs`: the upload id is unknown, expired, or the bytes were never uploaded. |

The message `upload not found or not yet uploaded` almost always means step 2
didn't finish — the upload record exists but the object doesn't. Complete the
`PUT`, then create the job.

Note that the size check at job creation reads the object Xora actually
stored, not the `sizeBytes` you declared. Under-declaring to get a URL doesn't
get an oversized file past the plan limit; the job is refused instead.

## Agents and MCP

The [MCP server](https://xora.sh/docs/guides/mcp/) exposes the same flow as a `create_upload`
tool, so an agent holding a local file can chain
`create_upload` → `PUT` → `create_job` without a hosting step.

## Related

- [Quickstart](https://xora.sh/docs/quickstart/) — your first job, using a public URL
- [Input staging](https://xora.sh/docs/guides/input-staging/) — `stageInput` for external URLs
- [Storage providers (BYOB)](https://xora.sh/docs/guides/storage-providers/) — durable delivery of *outputs*
- [Error handling](https://xora.sh/docs/guides/error-handling/) — rejected vs failed, retries

---

# Webhooks

Source: https://xora.sh/docs/guides/webhooks/

Webhooks let you receive a notification when a job reaches a terminal state (`completed`, `failed`, `rejected`, or `cancelled`). Instead of polling `GET /api/v1/jobs/:id`, Xora sends a `POST` to your URL with the job result.

## Setting a webhook

### Per-job webhook

Add `webhookUrl` to your job creation request:

**cURL:**
```bash
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/video.mp4" },
    "output": { "format": "mp4" },
    "recipe": { "name": "compress", "crf": 28 },
    "webhookUrl": "https://your-server.com/webhooks/xora"
  }'
```
**Node.js:**
```javascript
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/video.mp4' },
    output: { format: 'mp4' },
    recipe: { name: 'compress', crf: 28 },
    webhookUrl: 'https://your-server.com/webhooks/xora'
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
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/video.mp4" },
        "output": { "format": "mp4" },
        "recipe": { "name": "compress", "crf": 28 },
        "webhookUrl": "https://your-server.com/webhooks/xora"
    }
)
data = response.json()
print(data)
```

### Default webhook

You can set a default webhook URL that's used for all jobs that don't specify their own `webhookUrl`:

**cURL:**
```bash
curl -X POST https://api.xora.sh/v1/settings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaultWebhookUrl": "https://your-server.com/webhooks/xora"
  }'
```
**Node.js:**
```javascript
const response = await fetch('https://api.xora.sh/v1/settings', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    defaultWebhookUrl: 'https://your-server.com/webhooks/xora'
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
import requests

response = requests.post(
    "https://api.xora.sh/v1/settings",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "defaultWebhookUrl": "https://your-server.com/webhooks/xora"
    }
)
data = response.json()
print(data)
```

When a job includes a `webhookUrl`, it overrides the default. When it doesn't, the default is used.

## Webhook payload

When a job reaches a terminal state, Xora sends a `POST` request to your URL with this JSON body:

```json
{
  "data": {
    "jobId": "01JXYZ1234ABCDEF56789000",
    "state": "completed",
    "progress": 100,
    "output": {
      "signedUrl": "https://cdn.xora.sh/...signed-url..."
    },
    "output_files": {
      "output": {
        "file_id": "01JXYZ...-output",
        "filename": "output.mp4",
        "size_mbytes": 12.5,
        "duration": 120.5,
        "file_type": "video",
        "file_format": "mp4",
        "mime_type": "video/mp4",
        "codec": "h264",
        "width": 1920,
        "height": 1080,
        "storage_url": "https://cdn.xora.sh/...signed-url..."
      }
    }
  },
  "timestamp": 1717500000000
}
```

### Failed job payload

```json
{
  "data": {
    "jobId": "01JXYZ1234ABCDEF56789000",
    "state": "failed",
    "progress": 35,
    "error": {
      "code": "TRANSCODE_ERROR",
      "message": "FFmpeg exited with code 1",
      "stage": "transcoding",
      "retryable": true
    }
  },
  "timestamp": 1717500000000
}
```

## Payload fields

| Field | Type | Description |
|-------|------|-------------|
| `data.jobId` | string | The job ID |
| `data.state` | string | Terminal state: `completed`, `failed`, `rejected`, `cancelled` |
| `data.progress` | number | Progress at time of completion (100 for completed) |
| `data.output` | object | Signed URL for single-output jobs |
| `data.outputs` | object | Signed URLs for multi-output jobs |
| `data.output_files` | object | Detailed file metadata per output |
| `data.error` | object | Error details (only present on failure) |
| `timestamp` | number | Unix timestamp in milliseconds |

## Requirements

**Caution:**
Webhook URLs must meet these requirements:
- Must use **HTTPS** (`https://...`)
- Must **not** target private/localhost addresses (`127.0.0.1`, `10.*`, `192.168.*`, `172.16.*`, `169.254.*`, `*.local`)

## Retry behavior

If your endpoint returns a non-2xx response or is unreachable, Xora retries the webhook with **exponential backoff**:

| Attempt | Delay after failure |
|---------|-------------------|
| 1st | Immediate |
| 2nd | 500ms |
| 3rd | 1 second |

After 3 failed attempts, the webhook is abandoned. The job result is still available via `GET /api/v1/jobs/:id`.

**Tip:**
Always return a `200 OK` quickly from your webhook handler. Do your processing asynchronously — if your endpoint takes too long, the retry may fire unnecessarily.

## Testing your webhook

Use the webhook test endpoint to send a sample payload to your configured default URL:

**cURL:**
```bash
curl -X POST https://api.xora.sh/v1/settings/webhook/test \
  -H "Authorization: Bearer YOUR_API_KEY"
```
**Node.js:**
```javascript
const response = await fetch('https://api.xora.sh/v1/settings/webhook/test', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
import requests

response = requests.post(
    "https://api.xora.sh/v1/settings/webhook/test",
    headers={
        "Authorization": "Bearer YOUR_API_KEY"
    }
)
data = response.json()
print(data)
```

### Success response

```json
{
  "ok": true,
  "status": 200
}
```

### Failure response

```json
{
  "ok": false,
  "status": 500
}
```

**Note:**
The test endpoint sends a sample `completed` job payload with test data. It only works when you have a `defaultWebhookUrl` configured in your settings.

## Checking your settings

Read your current webhook configuration:

**cURL:**
```bash
curl https://api.xora.sh/v1/settings \
  -H "Authorization: Bearer YOUR_API_KEY"
```
**Node.js:**
```javascript
const response = await fetch('https://api.xora.sh/v1/settings', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
import requests

response = requests.get(
    "https://api.xora.sh/v1/settings",
    headers={
        "Authorization": "Bearer YOUR_API_KEY"
    }
)
data = response.json()
print(data)
```

```json
{
  "defaultWebhookUrl": "https://your-server.com/webhooks/xora",
  "defaultStorageProviderId": null,
  "updatedAt": "2026-06-04T10:00:00.000Z"
}
```

## Clearing the default webhook

Set `defaultWebhookUrl` to `null`:

**cURL:**
```bash
curl -X PUT https://api.xora.sh/v1/settings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "defaultWebhookUrl": null }'
```
**Node.js:**
```javascript
const response = await fetch('https://api.xora.sh/v1/settings', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    defaultWebhookUrl: null
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
import requests

response = requests.put(
    "https://api.xora.sh/v1/settings",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "defaultWebhookUrl": None
    }
)
data = response.json()
print(data)
```

---

# Error Handling

Source: https://xora.sh/docs/guides/error-handling/

The Xora API uses consistent error responses across all endpoints. This guide covers the error format, common error codes, and best practices for handling failures.

## Error response format

Every error response follows this structure:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of what went wrong",
    "retryable": false
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `code` | string | Machine-readable error code (always UPPER_SNAKE_CASE) |
| `message` | string | Human-readable explanation |
| `retryable` | boolean | Whether the request can be retried |

### Job-specific errors

When a job fails, the error also includes a `stage` field indicating where in the pipeline the failure occurred:

```json
{
  "jobId": "01JXYZ...",
  "state": "failed",
  "error": {
    "code": "TRANSCODE_ERROR",
    "message": "FFmpeg exited with code 1: Invalid data found when processing input",
    "stage": "transcoding",
    "retryable": true
  }
}
```

## Common error codes

### HTTP errors (API layer)

| Code | HTTP Status | Meaning |
|------|-------------|---------|
| `UNAUTHORIZED` | 401 | Missing or invalid API key / session |
| `NOT_FOUND` | 404 | Job, preset, file, or resource not found |
| `VALIDATION_ERROR` | 400 | Request body failed schema validation |

### Processing errors (job failures)

| Code | Meaning | Retryable |
|------|---------|-----------|
| `ENGINE_ERROR` | Processing failure | Usually yes |
| `ENGINE_INVOCATION_ERROR` | Processing timed out or crashed | Yes |
| `ENGINE_INVOKE_FAILED` | Could not start the job | Yes |
| `ENGINE_EMPTY_RESPONSE` | No result was returned | Yes |
| `ENGINE_INVALID_RESPONSE` | Unexpected response format | Yes |
| `CONFIG_ERROR` | Server misconfiguration | No |
| `UNSUPPORTED_COMMAND` | FFmpeg args rejected by security validation | No |
| `TRANSCODE_ERROR` | FFmpeg processing failed | Sometimes |

### Validation errors

| Scenario | Example message |
|----------|----------------|
| Missing input | `"input.url or input.uploadId is required for this recipe"` |
| Both `url` and `uploadId` given | `"input requires exactly one of url or uploadId"` |
| Upload never completed, or unknown id | `"upload not found or not yet uploaded"` |
| Invalid output format | `"Invalid enum value. Expected 'mp4' | 'webm' | ..."` |
| Bad FFmpeg args | `"ffmpeg.args must contain at least 1 element"` |
| Concat with single file | `"concat recipe requires input_files with at least two entries"` |
| Mixed input modes | `"Use either input/output or input_files/output_files, not both"` |
| Invalid webhook URL | `"webhookUrl must use https://"` |

## Handling retryable errors

When `retryable` is `true`, you can retry the request. For job failures, use the retry endpoint:

**cURL:**
```bash
curl -X POST https://api.xora.sh/v1/jobs/JOB_ID/retry \
  -H "Authorization: Bearer YOUR_API_KEY"
```
**Node.js:**
```javascript
const response = await fetch('https://api.xora.sh/v1/jobs/JOB_ID/retry', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
import requests

response = requests.post(
    "https://api.xora.sh/v1/jobs/JOB_ID/retry",
    headers={
        "Authorization": "Bearer YOUR_API_KEY"
    }
)
data = response.json()
print(data)
```

```json
{
  "retried": true,
  "jobId": "01JXYZ1234ABCDEF56789000"
}
```

**Note:**
You can only retry jobs in a terminal state: `failed`, `rejected`, or `cancelled`. Retrying re-runs the job with the original parameters.

### Retry strategy for API calls

For transient API errors (5xx), use exponential backoff:

**Node.js:**
```javascript
async function callXoraApi(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.ok) return response.json();

    const body = await response.json();

    // Don't retry client errors (4xx) — they won't succeed
    if (response.status < 500) throw new Error(body.error.message);

    // Retry server errors with exponential backoff
    if (attempt < maxRetries - 1) {
      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }

  throw new Error('Max retries exceeded');
}
```
**Python:**
```python
import time
import requests

def call_xora_api(url, method="GET", max_retries=3, **kwargs):
    for attempt in range(max_retries):
        response = requests.request(method, url, **kwargs)
        
        if response.status_code < 400:
            return response.json()
            
        body = response.json()
        
        # Don't retry client errors (4xx) — they won't succeed
        if response.status_code < 500:
            raise Exception(body["error"]["message"])
            
        # Retry server errors with exponential backoff
        if attempt < max_retries - 1:
            delay = (2 ** attempt)  # 1s, 2s, 4s
            time.sleep(delay)
            
    raise Exception("Max retries exceeded")
```

## Error responses by endpoint

### POST /api/v1/jobs (create job)

| Status | Code | When |
|--------|------|------|
| 400 | `VALIDATION_ERROR` | Invalid request body |
| 401 | `UNAUTHORIZED` | Bad or missing auth |
| 404 | `NOT_FOUND` | Preset not found (when using `presetId`) |
| 500 | `ENGINE_ERROR` | Server failed to accept the job |

### GET /api/v1/jobs/:id (get job)

| Status | Code | When |
|--------|------|------|
| 401 | `UNAUTHORIZED` | Bad or missing auth |
| 404 | `NOT_FOUND` | Job doesn't exist or belongs to another user |
| 500 | `ENGINE_ERROR` | Server unreachable |

### POST /api/v1/jobs/:id/cancel

| Status | Code | When |
|--------|------|------|
| 401 | `UNAUTHORIZED` | Bad or missing auth |
| 404 | `NOT_FOUND` | Job not found |
| 500 | `ENGINE_ERROR` | Server failed to cancel |

### DELETE /api/v1/jobs/:id/output

| Status | Code | When |
|--------|------|------|
| 401 | `UNAUTHORIZED` | Bad or missing auth |
| 404 | `NOT_FOUND` | Job or output not found |

## Best practices

**Tip:**

1. **Always check `retryable`** — only retry when the error says it's safe to do so.
2. **Use exponential backoff** — don't flood the API with rapid retries.
3. **Log the full error** — the `code`, `message`, and `stage` fields together give you the complete picture.
4. **Handle 401 early** — if you get `UNAUTHORIZED`, check your API key before retrying.
5. **Set up webhooks** — webhook payloads include error details, so you can handle failures without polling.

## Job failure stages

When a job fails, the `stage` field tells you where in the pipeline it broke:

| Stage | What was happening |
|-------|-------------------|
| `probing` | Analyzing the input file |
| `planning` | Deciding how to process |
| `segmenting` | Preparing the input for processing |
| `transcoding` | Running FFmpeg |
| `merging` | Assembling the final output |

This helps you diagnose whether the issue is with your input file, your FFmpeg command, or a transient server problem.

---

# Presets

Source: https://xora.sh/docs/guides/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:**
```bash
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:**
```javascript
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:**
```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

```json
{
  "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:

```json
{
  "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:

```json
{
  "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](https://xora.sh/docs/guides/input-staging/).

```json
{
  "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`:

```json
{
  "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](https://xora.sh/docs/job-lifecycle/) — the `preset_id` and `preset_name` fields are included on every job that was created from a preset.

---

# Storage Providers (BYOB)

Source: https://xora.sh/docs/guides/storage-providers/

By default, Xora stores transcoding outputs in its own managed storage and gives you signed download URLs. With **Bring Your Own Bucket (BYOB)**, you can route outputs directly to your Cloudflare R2 bucket.

## How it works

```
Without BYOB:                         With BYOB:
Video → Xora → Xora storage         Video → Xora → Your R2 bucket
                  ↓                                     ↓
          Signed URL (expires)               Your bucket (permanent)
```

With BYOB, outputs land in your R2 bucket under a prefix you configure. You own the files and manage access yourself.

## Setting up BYOB

1. **Create an R2 bucket**

    In your [Cloudflare dashboard](https://dash.cloudflare.com), create an R2 bucket. Note your **Account ID** (shown in the sidebar) and **bucket name**.

2. **Create R2 API credentials**

    Go to **R2 → Manage R2 API Tokens** → **Create API Token**:
    - Permission: **Object Read & Write**
    - Scope: your bucket
    - Copy the **Access Key ID** and **Secret Access Key**

3. **Add the storage provider in Xora**

    In the Xora [dashboard](https://xora.sh/app/dashboard/settings), go to **Storage Providers** → **Add Provider**, or use the API:

**cURL:**
```bash
curl -X POST https://api.xora.sh/v1/settings/storage-providers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My R2 Bucket",
    "provider": "r2",
    "accountId": "your-cloudflare-account-id",
    "bucket": "my-xora-outputs",
    "prefix": "transcoded/",
    "accessKeyId": "your-r2-access-key",
    "secretAccessKey": "your-r2-secret-key",
    "makeDefault": true
  }'
```
**Node.js:**
```javascript
const response = await fetch('https://api.xora.sh/v1/settings/storage-providers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'My R2 Bucket',
    provider: 'r2',
    accountId: 'your-cloudflare-account-id',
    bucket: 'my-xora-outputs',
    prefix: 'transcoded/',
    accessKeyId: 'your-r2-access-key',
    secretAccessKey: 'your-r2-secret-key',
    makeDefault: true
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
import requests

response = requests.post(
    "https://api.xora.sh/v1/settings/storage-providers",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "name": "My R2 Bucket",
        "provider": "r2",
        "accountId": "your-cloudflare-account-id",
        "bucket": "my-xora-outputs",
        "prefix": "transcoded/",
        "accessKeyId": "your-r2-access-key",
        "secretAccessKey": "your-r2-secret-key",
        "makeDefault": True
    }
)
data = response.json()
print(data)
```

4. **Test the connection**

**cURL:**
```bash
curl -X POST https://api.xora.sh/v1/settings/storage-providers/PROVIDER_ID/test \
  -H "Authorization: Bearer YOUR_API_KEY"
```
**Node.js:**
```javascript
const response = await fetch('https://api.xora.sh/v1/settings/storage-providers/PROVIDER_ID/test', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
import requests

response = requests.post(
    "https://api.xora.sh/v1/settings/storage-providers/PROVIDER_ID/test",
    headers={
        "Authorization": "Bearer YOUR_API_KEY"
    }
)
data = response.json()
print(data)
```

    ```json
    { "ok": true }
    ```

The test writes a small file, verifies it exists, then deletes it. If something is wrong (bad credentials, wrong bucket name), you'll get an error message explaining the issue.

## Configuration fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | A label for this provider (e.g., "Production R2") |
| `provider` | string | Yes | Must be `"r2"` |
| `accountId` | string | * | Your Cloudflare account ID |
| `endpoint` | string | * | Custom S3-compatible endpoint URL |
| `bucket` | string | Yes | R2 bucket name |
| `prefix` | string | No | Object key prefix (e.g., `"media/"`) — trailing slash added automatically |
| `accessKeyId` | string | Yes | R2 API token access key ID |
| `secretAccessKey` | string | Yes | R2 API token secret access key |
| `makeDefault` | boolean | No | Set as the default storage destination |

*Provide either `accountId` or `endpoint`. If you provide `accountId`, the endpoint is auto-generated as `https://{accountId}.r2.cloudflarestorage.com`.

## Setting a default provider

When you set a provider as default (`makeDefault: true`), all new jobs automatically route their outputs to that bucket. You can change the default at any time:

**cURL:**
```bash
curl -X PUT https://api.xora.sh/v1/settings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaultStorageProviderId": "01KSTORAGE1234ABCDEF"
  }'
```
**Node.js:**
```javascript
const response = await fetch('https://api.xora.sh/v1/settings', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    defaultStorageProviderId: '01KSTORAGE1234ABCDEF'
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
import requests

response = requests.put(
    "https://api.xora.sh/v1/settings",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "defaultStorageProviderId": "01KSTORAGE1234ABCDEF"
    }
)
data = response.json()
print(data)
```

Set to `null` to go back to Xora-hosted storage:

```json
{ "defaultStorageProviderId": null }
```

## Managing providers

### List all providers

**cURL:**
```bash
curl https://api.xora.sh/v1/settings/storage-providers \
  -H "Authorization: Bearer YOUR_API_KEY"
```
**Node.js:**
```javascript
const response = await fetch('https://api.xora.sh/v1/settings/storage-providers', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
import requests

response = requests.get(
    "https://api.xora.sh/v1/settings/storage-providers",
    headers={
        "Authorization": "Bearer YOUR_API_KEY"
    }
)
data = response.json()
print(data)
```

```json
{
  "providers": [
    {
      "id": "01KSTORAGE1234ABCDEF",
      "name": "My R2 Bucket",
      "type": "s3_compatible",
      "provider": "r2",
      "endpoint": "https://abc123.r2.cloudflarestorage.com",
      "bucket": "my-xora-outputs",
      "prefix": "transcoded/",
      "status": "active",
      "isDefault": true,
      "createdAt": "2026-06-01T10:00:00.000Z"
    }
  ],
  "defaultStorageProviderId": "01KSTORAGE1234ABCDEF"
}
```

### Update a provider

**cURL:**
```bash
curl -X PUT https://api.xora.sh/v1/settings/storage-providers/PROVIDER_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "provider": "r2",
    "accountId": "your-cloudflare-account-id",
    "bucket": "new-bucket-name",
    "accessKeyId": "your-r2-access-key"
  }'
```
**Node.js:**
```javascript
const response = await fetch('https://api.xora.sh/v1/settings/storage-providers/PROVIDER_ID', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Updated Name',
    provider: 'r2',
    accountId: 'your-cloudflare-account-id',
    bucket: 'new-bucket-name',
    accessKeyId: 'your-r2-access-key'
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
import requests

response = requests.put(
    "https://api.xora.sh/v1/settings/storage-providers/PROVIDER_ID",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Name",
        "provider": "r2",
        "accountId": "your-cloudflare-account-id",
        "bucket": "new-bucket-name",
        "accessKeyId": "your-r2-access-key"
    }
)
data = response.json()
print(data)
```

**Note:**
If you don't include `secretAccessKey` in an update, the existing encrypted secret is preserved. You only need to resend it if you're rotating credentials.

### Delete a provider

**cURL:**
```bash
curl -X DELETE https://api.xora.sh/v1/settings/storage-providers/PROVIDER_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```
**Node.js:**
```javascript
const response = await fetch('https://api.xora.sh/v1/settings/storage-providers/PROVIDER_ID', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
import requests

response = requests.delete(
    "https://api.xora.sh/v1/settings/storage-providers/PROVIDER_ID",
    headers={
        "Authorization": "Bearer YOUR_API_KEY"
    }
)
data = response.json()
print(data)
```

If the deleted provider was your default, the default is automatically cleared (reverts to Xora-hosted storage).

## Provider status

| Status | Meaning |
|--------|---------|
| `pending` | Just created, not yet tested |
| `active` | Connection test passed |
| `error` | Last test failed — check `lastError` for details |

**Tip:**
Run the test endpoint after creating or updating a provider to verify credentials. A provider in `pending` or `error` status will still be used if set as default — so always test first.

## Custom Output Path

When creating a job, you can optionally override the default output path (`outputs/<jobId>/result.<format>`) inside your bucket using the `outputPath` parameter on the job creation request or in the dashboard **New job** form.

### Requirements & Validation

- **Custom storage default**: This option is only supported when a default custom storage provider is configured.
- **Allowed characters**: `a-zA-Z0-9_-/.` (alphanumeric, hyphens, underscores, dots, and forward slashes). No path traversal (`../`) or leading/trailing slashes are allowed.
- **Extension match**: The extension in the `outputPath` must exactly match the job's output format (e.g. `path/to/my-video.mp4` for format `mp4`).
- **Scope restriction**: Not supported on multi-file `ffmpeg` mode jobs.

### Example Request

**cURL:**
```bash
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.mp4" },
    "output": { "format": "mp4" },
    "recipe": { "name": "compress" },
    "outputPath": "processed/2026/june/final-compress.mp4"
  }'
```
**Node.js:**
```javascript
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.mp4' },
    output: { format: 'mp4' },
    recipe: { name: 'compress' },
    outputPath: 'processed/2026/june/final-compress.mp4'
  })
});
const data = await response.json();
console.log(data);
```
**Python:**
```python
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.mp4" },
        "output": { "format": "mp4" },
        "recipe": { "name": "compress" },
        "outputPath": "processed/2026/june/final-compress.mp4"
    }
)
data = response.json()
print(data)
```

If your storage prefix is configured as `transcoded/`, the output will be saved at the key `transcoded/processed/2026/june/final-compress.mp4` in your R2 bucket.

## Security

- Your `secretAccessKey` is encrypted at rest using AES and never returned in API responses
- Credentials are only decrypted at job time to upload outputs to your bucket
- R2 API tokens should be scoped to the minimum required permission (Object Read & Write on a single bucket)

---

# Input Staging

Source: https://xora.sh/docs/guides/input-staging/

By default, Xora **stages** every input: it copies your file from the URL you provide into engine storage, then processes from that copy. This is reliable for any HTTPS origin.

For hosts that support **HTTP byte-range requests** (most CDNs, S3/R2 presigned URLs, and many file servers), you can set `stageInput: false` to **skip staging**. ffmpeg reads your original URL directly, which is often much faster for lightweight jobs like [extract audio](https://xora.sh/docs/recipes/extract-audio/) or [thumbnails](https://xora.sh/docs/recipes/thumbnail/).

## When to use `stageInput: false`

| Good candidates | Keep default (`true` or omit) |
|-----------------|-------------------------------|
| extractAudio, thumbnail, webReady, proxy | Unknown or flaky origins |
| Long transcodes from range-capable CDNs | Origins without `Accept-Ranges: bytes` |
| Large files you already host on S3/R2 | When you need a durable copy in engine storage |

**Note:**
If you set `stageInput: false` but the origin does not support byte ranges, Xora **automatically falls back to staging** — the job still completes.

**Tip:**
`stageInput` only affects inputs you pass as a URL. Files sent through
[direct uploads](https://xora.sh/docs/guides/direct-uploads/) already sit in the storage the
workers read from, so there is no staging step to skip.

## API usage

Add `stageInput: false` to any job body (recipe or ffmpeg):

**cURL:**
```bash
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://cdn.example.com/interview.mp4" },
    "output": { "format": "mp3" },
    "recipe": { "name": "extractAudio" },
    "stageInput": false
  }'
```
**Node.js:**
```javascript
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://cdn.example.com/interview.mp4' },
    output: { format: 'mp3' },
    recipe: { name: 'extractAudio' },
    stageInput: false,
  }),
});
```
**Python:**
```python
requests.post(
    "https://api.xora.sh/v1/jobs",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "mode": "recipe",
        "input": {"url": "https://cdn.example.com/interview.mp4"},
        "output": {"format": "mp3"},
        "recipe": {"name": "extractAudio"},
        "stageInput": False,
    },
)
```

## With presets

Store `stageInput` in the preset body, or override it when running the preset:

```json
{
  "presetId": "preset_abc123",
  "input": { "url": "https://cdn.example.com/video.mp4" },
  "stageInput": false
}
```

## Job pipeline effect

| `stageInput` | Origin supports ranges | Steps |
|--------------|------------------------|-------|
| `true` (default) | any | `probe` → `stage_input` → transcode |
| `false` | yes | `probe` → transcode (direct URL) |
| `false` | no | `probe` → `stage_input` → transcode (fallback) |

High-volume encoding pipelines also benefit: processing instances range-read your URL directly instead of copying it to local staging storage first.

## Related

- [Extract Audio](https://xora.sh/docs/recipes/extract-audio/) — common use case for `stageInput: false`
- [Direct Uploads](https://xora.sh/docs/guides/direct-uploads/) — local files, already staged on arrival
- [Job Lifecycle](https://xora.sh/docs/job-lifecycle/) — states and progress
- [Presets](https://xora.sh/docs/guides/presets/) — save `stageInput` in preset definitions