Screenshot API

The Screenshot API allows you to capture high-quality screenshots and PDFs of any website. The API provides asynchronous processing with job status polling, multiple output formats, device emulation, and advanced optimization options.

The Screenshot Process

The screenshot generation process is asynchronous and follows these steps:

  1. Submit a screenshot job via POST /screenshot
  2. Receive a job ID and status URL for polling
  3. Poll the status via GET /screenshot/status/{jobId}
  4. Retrieve the result when the job is completed
POST/screenshot

Create Screenshot Job

This endpoint creates a new screenshot job and returns a job ID for status polling. The request is processed asynchronously, allowing you to handle multiple screenshots simultaneously.

Required parameters

  • Name
    url
    Type
    string
    Description

    The URL of the website to capture. Must be a valid HTTP or HTTPS URL.

  • Name
    viewport
    Type
    object
    Description

    Viewport configuration for the browser.

    • Name
      width
      Type
      integer
      Description

      Viewport width in pixels (minimum: 100)

    • Name
      height
      Type
      integer
      Description

      Viewport height in pixels (minimum: 100). Optional when fullPage is true.

    • Name
      deviceScaleFactor
      Type
      number
      Description

      Device pixel ratio (1-3, default: 1)

Optional parameters

  • Name
    outputType
    Type
    string
    Description

    Output format: screenshot or pdf (default: screenshot)

  • Name
    fullPage
    Type
    boolean
    Description

    Capture full page height (default: false)

  • Name
    format
    Type
    string
    Description

    Image format: png, jpeg, webp, or avif (default: png)

  • Name
    quality
    Type
    integer
    Description

    Image quality for lossy formats (1-100, default: 80)

  • Name
    timeoutMs
    Type
    integer
    Description

    Page load timeout in milliseconds (5000-60000, default: 30000)

  • Name
    deviceEmulation
    Type
    string|object
    Description

    Predefined device name or custom device configuration

  • Name
    deviceOrientation
    Type
    string
    Description

    Device orientation: portrait or landscape (default: portrait)

  • Name
    headers
    Type
    object
    Description

    Custom HTTP headers (max 20 headers)

  • Name
    cookies
    Type
    array
    Description

    Array of cookie objects (max 20 cookies)

  • Name
    userAgent
    Type
    string
    Description

    Custom user agent string (max 500 characters)

  • Name
    pdfOptions
    Type
    object
    Description

    PDF-specific options (when outputType is pdf)

  • Name
    optimizationOptions
    Type
    object
    Description

    Format-specific optimization settings

  • Name
    cacheControl
    Type
    object
    Description

    Cache control settings

    • Name
      bypass
      Type
      boolean
      Description

      Bypass cache (default: false)

    • Name
      ttl
      Type
      integer
      Description

      Custom TTL in seconds (60-86400)

Request

POST
/screenshot
curl -X POST https://api.webcapture.ai/screenshot \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "viewport": {
      "width": 1200,
      "height": 800
    }
  }'

Response

{
  "message": "Screenshot job created",
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "statusUrl": "/screenshot/status/550e8400-e29b-41d4-a716-446655440000"
}
GET/screenshot/status/:jobId

Check Job Status

This endpoint allows you to check the status of a screenshot job. Poll this endpoint to monitor job progress and retrieve the result when completed.

Path parameters

  • Name
    jobId
    Type
    string
    Description

    The unique job ID returned from the screenshot creation request.

Response statuses

  • Name
    pending
    Description

    Job is queued and waiting to be processed.

  • Name
    processing
    Description

    Job is currently being processed.

  • Name
    completed
    Description

    Job completed successfully, result available.

  • Name
    failed
    Description

    Job failed, error details included.

Request

GET
/screenshot/status/550e8400-e29b-41d4-a716-446655440000
curl https://api.webcapture.ai/screenshot/status/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: your_api_key"

Pending Job

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "createdAt": "2023-12-07T10:30:00Z",
  "statusUrl": "https://api.webcapture.ai/screenshot/status/550e8400-e29b-41d4-a716-446655440000"
}

Completed Job

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "createdAt": "2023-12-07T10:30:00Z",
  "completedAt": "2023-12-07T10:30:15Z",
  "result": {
    "url": "https://example.com",
    "format": "png",
    "resultUrl": "/screenshot/files/550e8400-e29b-41d4-a716-446655440000.png",
    "fileSize": 245760,
    "dimensions": {
      "width": 1200,
      "height": 800
    }
  },
  "directUrl": "https://api.webcapture.ai/screenshot/files/550e8400-e29b-41d4-a716-446655440000.png",
  "viewHtml": "<img src=\"https://api.webcapture.ai/screenshot/files/550e8400-e29b-41d4-a716-446655440000.png\" alt=\"Screenshot 550e8400-e29b-41d4-a716-446655440000\" style=\"max-width:100%;height:auto;border:1px solid #ddd;\" />"
}

Failed Job

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "createdAt": "2023-12-07T10:30:00Z",
  "failedAt": "2023-12-07T10:30:10Z",
  "error": {
    "code": "NAVIGATION_FAILED",
    "message": "Failed to navigate to URL",
    "details": "Timeout waiting for page load"
  }
}
GET/screenshot/devices

List Available Devices

This endpoint returns a list of predefined device configurations available for device emulation. These devices can be used with the deviceEmulation parameter.

Note: This endpoint does not require authentication.

Request

GET
/screenshot/devices
curl https://api.webcapture.ai/screenshot/devices

Response

{
  "devices": [
    "iPhone X",
    "iPhone 12",
    "iPhone 12 Pro Max",
    "iPad Pro",
    "iPad Mini",
    "Pixel 5",
    "Samsung Galaxy S21",
    "Samsung Galaxy Tab S7"
  ]
}

Device Emulation

You can emulate specific devices using either predefined device names or custom device configurations.

Predefined Devices

Use any device name from the /screenshot/devices endpoint:

{
  "deviceEmulation": "iPhone X",
  "deviceOrientation": "portrait"
}

Custom Device Configuration

Define your own device characteristics:

{
  "deviceEmulation": {
    "name": "Custom Mobile",
    "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X)...",
    "viewport": {
      "width": 375,
      "height": 812,
      "deviceScaleFactor": 3,
      "isMobile": true,
      "hasTouch": true,
      "isLandscape": false
    }
  }
}

PDF Generation

When outputType is set to pdf, you can customize the PDF output:

{
  "outputType": "pdf",
  "pdfOptions": {
    "format": "A4",
    "landscape": false,
    "printBackground": true,
    "margin": {
      "top": "0.4in",
      "right": "0.4in", 
      "bottom": "0.4in",
      "left": "0.4in"
    },
    "scale": 1,
    "displayHeaderFooter": false
  }
}

Image Optimization

Control image compression and optimization for different formats:

{
  "format": "jpeg",
  "quality": 85,
  "optimizationOptions": {
    "progressive": true,
    "mozjpeg": true
  }
}

Format-Specific Options

  • Name
    PNG
    Description

    compressionLevel (0-9), adaptiveFiltering

  • Name
    JPEG
    Description

    progressive, optimizeScans, mozjpeg

  • Name
    WebP
    Description

    lossless, nearLossless, smartSubsample

  • Name
    AVIF
    Description

    effort (0-9)

Was this page helpful?