# 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

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.

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

- [Custom FFmpeg args](https://xora.sh/docs/guides/ffmpeg): mode "ffmpeg" — raw argument arrays with {{in_1}}/{{out_1}} placeholders
- [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

- [Pricing](https://xora.sh/pricing): Free during private preview, no credit card. Published rates: compute minutes (encode-worker time, summed across parallel chunks) + delivery GB at cost; probes, staging, stream-copy I/O, rejected and failed jobs are never billed. Every completed job returns cost.totalUsd on the job record.
- [Blog](https://xora.sh/blog): Guides on FFmpeg workflows, n8n automation, encoding practices