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 (free)
• An API key — create one in the dashboard

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

   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

   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

   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:

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

   curl https://api.xora.sh/v1/jobs/JOB_ID \
     -H "Authorization: Bearer YOUR_API_KEY"

   Node.js

   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

   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:

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

3. Download the output

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

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

   curl -o thumbnail.jpg "SIGNED_URL_HERE"

   Node.js

   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

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

Using a preset instead

If you’ve saved a preset in the dashboard, you can run a job with just its ID:

cURL

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

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

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 for details.

Receiving webhooks instead of polling

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

cURL

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

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

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.

What’s next?

• Recipes → — web-ready video, edit proxy, compress, transcode, resize, trim, extract audio, thumbnails, concat
• Custom FFmpeg → — full control with your own FFmpeg arguments
• Presets → — save and reuse job configurations
• Input Staging → — skip copying inputs when your URL supports byte ranges
• Storage Providers → — route outputs directly to your own Cloudflare R2 bucket
• Job lifecycle → — understand job states and progress
• API Reference → — full interactive API docs