Generate 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 -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
    }
  }'

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);

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

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

Output format options

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

Examples

Capture at 5 seconds

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

Capture as PNG (lossless)

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

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

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