Formats and Response

Output Formats

Pageshot supports both image and video formats:

Image Formats: png, jpeg, webp, pdf

Video Formats: mp4, gif, webm

{
  "format": "webp",
  "quality": 80
}

Image Formats

PNG (default)

• Best quality
• Lossless compression
• Supports transparency
• Larger file sizes

{
  "format": "png",
  "omit_background": true
}

JPEG

• Smaller file sizes
• Lossy compression
• Quality control (1-100)
• No transparency support

{
  "format": "jpeg",
  "quality": 85
}

WebP

• Modern format
• Good compression
• Supports transparency
• Smaller than PNG, better quality than JPEG

{
  "format": "webp",
  "quality": 80,
  "omit_background": true
}

PDF

• Multi-page documents
• Print-friendly
• Vector text when possible

{
  "format": "pdf"
}

Video Formats

MP4

• Standard video format
• Excellent compatibility
• H.264 codec
• Quality control via CRF (0-63, lower = better)

{
  "format": "mp4",
  "motion": {
    "type": "still",
    "duration": 5
  },
  "video": {
    "fps": 30,
    "quality": 30
  }
}

GIF

• Animated GIF format
• Perfect for social media
• Smaller file sizes
• Lower FPS recommended (15-20)

{
  "format": "gif",
  "motion": {
    "type": "scroll",
    "duration": 5
  },
  "video": {
    "fps": 20,
    "scale": 0.5
  }
}

WebM

• Native Playwright output
• Fastest (no conversion)
• VP8/VP9 codec
• Good compression

{
  "format": "webm",
  "motion": {
    "type": "still",
    "duration": 3
  }
}

Motion Types

When using video formats, you must specify a motion type:

Still Video

Records a static video for a specified duration:

{
  "motion": {
    "type": "still",
    "duration": 5
  }
}

Options:

• duration - Length in seconds (1-30, default: 5)

Scroll Video

Creates a smooth scrolling animation:

{
  "motion": {
    "type": "scroll",
    "duration": 10,
    "scroll_by": 800,
    "scroll_delay": 500,
    "scroll_duration": 1500,
    "easing": "ease_in_out"
  }
}

Options:

• duration - Total video length in seconds (1-30, default: 10)
• scroll_by - Pixels per scroll step (100-5000, default: 1000)
• scroll_delay - Pause between scrolls in ms (0-5000, default: 500)
• scroll_duration - Duration of each scroll animation in ms (100-5000, default: 1500)
• easing - Animation curve: "linear" or "ease_in_out" (default: "linear")

Video Quality Options

Fine-tune video output with the video parameter:

{
  "video": {
    "fps": 30,
    "quality": 30,
    "scale": 1.0,
    "speed": 1.0
  }
}

Options:

• fps - Frames per second (10-60, default: 30 for MP4/WebM, 20 for GIF)
• quality - CRF value for MP4 (0-63, lower = better, default: 30)
• scale - Output scaling multiplier (0.1-2.0, default: 1.0)
• speed - Playback speed multiplier (0.5-2.0, default: 1.0)

Image Quality Settings

For jpeg and webp, control the quality vs file size tradeoff:

Response Type

The API always returns binary data in the response body:

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 245678

<binary image/video data>

The Content-Type header matches your requested format:

Images:

• PNG: image/png
• JPEG: image/jpeg
• WebP: image/webp
• PDF: application/pdf

Videos:

• MP4: video/mp4
• GIF: image/gif
• WebM: video/webm

Common Patterns

{
  "url": "https://yoursite.com",
  "format": "gif",
  "viewport": { "width": 600, "height": 400 },
  "motion": {
    "type": "scroll",
    "duration": 3
  },
  "video": {
    "fps": 15,
    "scale": 0.5
  }
}

{
  "url": "https://yourapp.com/demo",
  "format": "mp4",
  "motion": {
    "type": "still",
    "duration": 10
  },
  "video": {
    "fps": 30,
    "quality": 25
  }
}

{
  "url": "https://portfolio.com",
  "format": "webm",
  "motion": {
    "type": "scroll",
    "duration": 15,
    "scroll_by": 600,
    "easing": "ease_in_out"
  }
}

{
  "url": "https://example.com",
  "format": "mp4",
  "viewport": { "width": 1920, "height": 1080 },
  "motion": {
    "type": "still",
    "duration": 5
  },
  "video": {
    "fps": 60,
    "quality": 20
  }
}

Performance Considerations

• Video captures take longer than screenshots (5-30s typical)
• MP4 and GIF require FFmpeg for conversion (adds 2-5s)
• WebM is fastest (no conversion needed)
• Higher FPS and quality increase processing time and file size
• GIF files are typically larger than MP4 for the same content