Introduction

Getting Started

The Screenshot API lets you capture pixel-perfect screenshots of any public web page with a single POST request. No browser automation code, no headless setup — just a URL and your API key.

Quick start: Send a POST request to /api/v1/screenshot with a JSON body containing url and the x-api-key header. That's it.

Your first screenshot

Replace YOUR_API_KEY with your key and run this in your terminal:

bash

curl -X POST https://mohammedsayed.com/api/v1/screenshot \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"url": "https://example.com"}' \
  --output screenshot.png

The API will respond with a binary PNG image saved to screenshot.png. Don't have an API key yet? Request access →

Authentication

Every request must include your API key in the x-api-key HTTP header. Keys are associated with a request quota — you can check your remaining usage at any time.

http

POST /api/v1/screenshot HTTP/1.1
Host: mohammedsayed.com
Content-Type: application/json
x-api-key: YOUR_API_KEY

Keep your API key secret. Never expose it in client-side JavaScript or commit it to version control. Use environment variables.

Need a key? Request API access →

Making a Request

There is a single endpoint. Send a POST request with a JSON body.

POSThttps://mohammedsayed.com/api/v1/screenshot

All options are passed as JSON in the request body. The only required field is url.

Parameters

Pass these as a JSON object in the POST body.

Parameter	Type	Default	Description
`url` required	string	—	The fully-qualified URL to screenshot. Must start with `http://` or `https://`.
`width`	number	1280	Viewport width in pixels. Range: 320–2560.
`height`	number	720	Viewport height in pixels. Range: 240–2160.
`fullPage`	boolean	false	When `true`, captures the full scrollable page, not just the viewport.
`format`	string	"png"	Image format. One of: `png`, `jpeg`, `webp`.
`delay`	number	0	Milliseconds to wait after page load before capturing. Max: 10000. Useful for animations or lazy-loaded content.
`responseFormat`	string	"binary"	`binary` returns raw image bytes. `json` returns `{"image": "<base64>"}` — ideal for AI agents.

Response

Binary (default)

When responseFormat is "binary" (the default), the API returns raw image bytes with the appropriate Content-Type header (image/png, image/jpeg, or image/webp). You can pipe this directly to a file.

JSON

When responseFormat is "json", the API returns a JSON object with a single image field containing the base64-encoded image. This is the recommended mode for AI agents that cannot handle raw binary HTTP responses.

json

{
  "image": "iVBORw0KGgoAAAANSUhEUgAA..."
}

Error Handling

The API uses standard HTTP status codes. When a request fails, the response body is always JSON with a single error field describing the problem.

json

{
  "error": "Invalid API key."
}

Status	Meaning
400	Bad request — invalid or missing parameters (e.g., no `url`, unsupported format).
401	Unauthorised — `x-api-key` header is missing.
403	Forbidden — the API key is invalid or has been revoked.
429	Too many requests — you've reached your request quota. Contact us to upgrade.
500	Server error — something went wrong on our end. Try again or contact support.

Code Examples

cURL

Binary response (save to file)

bash

curl -X POST https://mohammedsayed.com/api/v1/screenshot \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"url": "https://example.com"}' \
  --output screenshot.png

JSON response (base64)

bash

curl -X POST https://mohammedsayed.com/api/v1/screenshot \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"url": "https://example.com", "responseFormat": "json"}' | jq -r '.image' | base64 -d > screenshot.png

JavaScript / TypeScript

Works in Node.js, Deno, Bun, and any environment that supports the Fetch API.

typescript

const response = await fetch('https://mohammedsayed.com/api/v1/screenshot', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.SCREENSHOT_API_KEY,
  },
  body: JSON.stringify({
    url: 'https://example.com',
    width: 1280,
    height: 720,
    format: 'png',
    responseFormat: 'json',
  }),
});

const { image } = await response.json();
// image is a base64-encoded PNG string

Python

Uses the requests library. Install it with pip install requests.

python

import requests, base64

response = requests.post(
    'https://mohammedsayed.com/api/v1/screenshot',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY',
    },
    json={
        'url': 'https://example.com',
        'width': 1280,
        'height': 720,
        'format': 'png',
        'responseFormat': 'json',
    }
)

data = response.json()
image_bytes = base64.b64decode(data['image'])
with open('screenshot.png', 'wb') as f:
    f.write(image_bytes)

AI Agents

The responseFormat: "json" mode is built for AI workflows. The base64 image can be passed directly to vision models (GPT-4o, Claude, Gemini) as an inline data URL — no file storage or CDN required.

typescript

// AI agents: use responseFormat "json" to get base64 you can pass directly
// to vision models like GPT-4o, Claude, or Gemini.

const { image } = await fetch('/api/v1/screenshot', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'x-api-key': key },
  body: JSON.stringify({ url, responseFormat: 'json' }),
}).then(r => r.json());

// Pass to OpenAI vision
const result = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{
    role: 'user',
    content: [
      { type: 'image_url', image_url: { url: `data:image/png;base64,${image}` } },
      { type: 'text', text: 'Describe what you see on this website.' },
    ],
  }],
});

An OpenAI-compatible plugin manifest is available at /.well-known/ai-plugin.json and an OpenAPI spec at /api/openapi.json.