Screenshot API

Endpoint

Send a JSON body with Content-Type: application/json. POST is the only method this endpoint accepts.

Authentication

Pass your API key as a Bearer token. Keys are created in Dashboard → API once your account is on Pro — see Authentication.

1Authorization: Bearer sk_your_api_key

Request Body

1{
2  "postUrl": "https://x.com/postcaboron/status/1924847327370461555",
3  "settings": {
4    "global": {
5      "theme": "dark",
6      "platformConfig": "format:portrait",
7      "padding": 60,
8      "cardStyle": "glass",
9      "showWatermark": false
10    },
11    "twitter": {
12      "showFollowerCount": false,
13      "showViewCount": false
14    }
15  }
16}

Platform Detection

The platform comes from the postUrl domain and decides which settings group applies. A URL that matches none of these is rejected with unsupported_platform.

Settings

Every field below is optional; anything you omit uses the default in the table. Each group is strict, so a misspelled field is a 400 instead of being silently ignored. Send only the group that matches the post you are capturing: the platform groups share field names such as showLikeCount, and sending several at once lets them collide.

settings.global

Canvas, background and typography — these apply to every platform.

settings.twitter

settings.bluesky

settings.youtube

settings.tiktok

Response

JSON (default)

The render is uploaded and you get back its URL plus metadata and your remaining quota.

1{
2  "url": "https://screenshots-cdn.postcapture.com/api-renders/hK3q…/1924847327370461555-2026-07-25-11-04-12-a9f2.png",
3  "expiresAt": "2026-07-25T12:04:12.918Z",
4  "width": 2400,
5  "height": 1350,
6  "contentType": "image/png",
7  "platform": "twitter",
8  "historyId": "cm9f3k2p10001v8m2v0k4a1bd",
9  "credits": {
10    "remaining": 2989,
11    "limit": 3000,
12    "used": 11,
13    "resetsAt": "2026-08-01T00:00:00.000Z",
14    "platforms": {
15      "twitter": { "used": 11, "limit": 1000, "remaining": 989 },
16      "bsky":    { "used": 0,  "limit": 1000, "remaining": 1000 },
17      "youtube": { "used": 0,  "limit": 1000, "remaining": 1000 },
18      "tiktok":  { "used": 0,  "limit": 1000, "remaining": 1000 }
19    }
20  }
21}

Raw image

Send "response": "image" to get the PNG bytes in the response body instead. Nothing is uploaded, so there is no URL and no expiry to worry about — but you also get no quota metadata back.

Errors

Every error is JSON with a human-readable error and a stable code to branch on.

Validation failures name every problem at once, so you can fix a payload in one pass:

1{
2  "error": "Invalid request body",
3  "code": "invalid_request",
4  "issues": [
5    { "path": "settings.global.widht", "message": "Unrecognized key(s) in object: 'widht'" },
6    { "path": "settings.global.scaleFactor", "message": "Number must be less than or equal to 4" }
7  ]
8}

Credits & Plan Limits

• •One credit per successful call. Nothing is charged for rejected requests, and nothing is charged when rendering or storing the image fails. The quota resets on the 1st of each month.
• •The watermark is forced on for free accounts. Sending settings.global.showWatermark: false is accepted but has no effect until you upgrade — the server sets it back on before rendering.
• •Pro unlocks the premium looks. Premium card styles and post layouts, custom image backgrounds, and custom fonts and colours are part of the Pro plan.
• •10 requests per minute. Shared across all of your API keys, and across v1 and the legacy endpoint — see Rate Limits.

Examples

The smallest request that works — a post URL and your key:

1curl -X POST https://postcapture.com/api/v1/screenshot \
2  -H "Authorization: Bearer $POSTCAPTURE_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "postUrl": "https://x.com/postcaboron/status/1924847327370461555"
6  }'

The same call with a portrait canvas, a dark glass card and a couple of counters hidden:

1curl -X POST https://postcapture.com/api/v1/screenshot \
2  -H "Authorization: Bearer $POSTCAPTURE_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "postUrl": "https://x.com/postcaboron/status/1924847327370461555",
6    "settings": {
7      "global": {
8        "theme": "dark",
9        "platformConfig": "format:portrait",
10        "padding": 60,
11        "cardStyle": "glass",
12        "showWatermark": false
13      },
14      "twitter": {
15        "showFollowerCount": false,
16        "showViewCount": false
17      }
18    }
19  }'

More patterns — batching, retries and every platform — are in Code Examples.

Moving from the legacy endpoint

The legacy GET /api/screenshot endpoint keeps working, but it is no longer documented. What changes when you move:

• •GET /api/screenshot with query params becomes POST /api/v1/screenshot with a JSON body — no more URL-length ceiling on your settings.
• •The apiKey query param becomes an Authorization: Bearer header, so keys stop showing up in URLs and logs.
• •Flat settings become grouped: &showLikeCount=false becomes settings.twitter.showLikeCount: false.
• •Typos are errors now. The legacy endpoint forwarded unknown params and quietly ignored them; v1 rejects them with invalid_request.
• •You get JSON by default instead of PNG bytes. Keep the old behaviour with "response": "image".