Shotium

https://shotium.com/docs
Admin
Shotium is an API service for capturing website screenshots and generating dynamic Open Graph images...
Tokens:3,939
Snippets:25
Trust Score:3.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### GET /v1/me

Source: https://shotium.com/docs

Verifies an API key without spending a render. Returns 200 with your key's prefix and name.

```APIDOC
## GET /v1/me

### Description
Verifies an API key without spending a render. Returns 200 with your key's prefix and name.

### Method
GET

### Endpoint
/v1/me

### Authentication
Bearer token (API key).

### Response
#### Success Response (200)
Returns your key's prefix and name.

#### Response Example
{
  "prefix": "sk_live_…",
  "name": "My Key"
}
```

--------------------------------

### Sign GET /v1/og-image URL in Python

Source: https://shotium.com/docs

Builds a signed URL for GET /v1/og-image in Python. It canonicalizes query parameters (sorted, RFC 3986-encoded) and signs them with HMAC-SHA256 using the SIGNING_SECRET variable. The signature is valid only for that exact parameter set.

```python
# Python
import hashlib, hmac, urllib.parse

params = {"template": "minimal", "title": "Less, but better.", "uid": "YOUR-UID"}
canonical = "&".join(
    f"{urllib.parse.quote(k, safe='')}={urllib.parse.quote(v, safe='')}"
    for k, v in sorted(params.items())
)
sig = hmac.new(SIGNING_SECRET.encode(), canonical.encode(), hashlib.sha256).hexdigest()
url = f"https://api.shotium.com/v1/og-image?{canonical}&sig={sig}"
```

--------------------------------

### Quick start screenshot with curl

Source: https://shotium.com/docs

Takes a screenshot of a public URL using the default parameters (1280x800 PNG). Requires an API key sent as a Bearer token; the response is saved to shot.png.

```bash
curl -H "Authorization: Bearer sk_live_…" \
  "https://api.shotium.com/v1/screenshot?url=https://example.com" \
  -o shot.png
```

--------------------------------

### Sign GET /v1/og-image URL in Node.js

Source: https://shotium.com/docs

Builds a signed URL for GET /v1/og-image in Node.js. It canonicalizes query parameters (sorted, RFC 3986-encoded) and signs them with HMAC-SHA256 using the SHOTIUM_SIGNING_SECRET environment variable. The signature is valid only for that exact parameter set.

```javascript
// Node.js
import { createHmac } from 'node:crypto'

// RFC 3986: percent-encode the !'()* characters encodeURIComponent leaves bare
const rfc3986 = s => encodeURIComponent(s)
  .replace(/[!'()*]/g, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)

const params = {
  template: 'minimal',
  title: 'Less, but better.',
  uid: 'YOUR-UID',
}
const canonical = Object.entries(params)
  .sort(([a], [b]) => (a < b ? -1 : 1))
  .map(([k, v]) => `${rfc3986(k)}=${rfc3986(v)}`)
  .join('&')
const sig = createHmac('sha256', process.env.SHOTIUM_SIGNING_SECRET)
  .update(canonical).digest('hex')

const url = `https://api.shotium.com/v1/og-image?${canonical}&sig=${sig}`
```

--------------------------------

### GET /v1/screenshot

Source: https://shotium.com/docs

Renders any public URL to an image. Responses are cached for 24 hours — identical parameter sets return the cached artifact (and are billed as a render).

```APIDOC
## GET /v1/screenshot

### Description
Renders any public URL to an image. Responses are cached for 24 hours — identical parameter sets return the cached artifact (and are billed as a render).

### Method
GET

### Endpoint
/v1/screenshot

### Parameters
#### Query Parameters
- **url** (string) - Required - http(s) URL, ≤2048 chars. Fragments are ignored.
- **width** (int) - Optional - Viewport width, 1–3840. Default: 1280.
- **height** (int) - Optional - Viewport height, 1–2160. Default: 800.
- **full_page** (bool) - Optional - Capture full scroll height (≤20,000px). Default: false.
- **format** (enum) - Optional - `png` | `jpeg` | `webp`. Default: png.
- **quality** (int) - Optional - 1–100; lossy formats only, ignored for png. Default: 80.

### Request Example
```
# full-page WebP at 90 quality
curl -H "Authorization: Bearer sk_live_…" \
  "https://api.shotium.com/v1/screenshot?url=https://news.ycombinator.com&full_page=true&format=webp&quality=90" \
  -o page.webp
```

### Response
#### Success Response (200)
Returns image bytes on success.

#### Response Example
Image bytes (e.g., PNG, JPEG, or WebP).
```

--------------------------------

### quota_exceeded error response example

Source: https://shotium.com/docs

Example error response body for the quota_exceeded error type. Use this to handle the 429 status when both monthly quota and credits are exhausted. The response follows RFC 9457 problem+json format with a stable type field for branching.

```json
{
  "type": "quota_exceeded",
  "title": "Monthly quota exceeded",
  "status": 429,
  "detail": "monthly quota and credits exhausted; upgrade or buy credits at https://shotium.com/pricing"
}
```

--------------------------------

### GET /v1/og-image

Source: https://shotium.com/docs

Generates an Open Graph image. The signed-URL form uses an HMAC signature instead of a Bearer token — no key in the URL, safe to embed publicly.

```APIDOC
## GET /v1/og-image

### Description
Generates an Open Graph image. The signed-URL form uses an HMAC signature instead of a Bearer token — no key in the URL, safe to embed publicly.

### Method
GET

### Endpoint
/v1/og-image

### Authentication
HMAC signature (signed URL) instead of Bearer token.

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL to generate an OG image for.

### Response
#### Success Response (200)
Returns image bytes on success.
```

--------------------------------

### GET /v1/og-image — signed URLs

Source: https://shotium.com/docs

Embed OG images directly in your HTML `<head>`. The URL carries an HMAC signature instead of your API key, and responses are served with `Cache-Control: public, max-age=86400, immutable` so Cloudflare's edge absorbs crawler traffic.

```APIDOC
## GET /v1/og-image — signed URLs

### Description
Embed OG images directly in your HTML `<head>`. The URL carries an HMAC signature instead of your API key, and responses are served with `Cache-Control: public, max-age=86400, immutable` so Cloudflare's edge absorbs crawler traffic.

### Method
GET

### Endpoint
/v1/og-image

### Parameters
#### Query Parameters
- **template** (string) - Required - The template id.
- **uid** (string) - Required - Your user id.
- **sig** (string) - Required - HMAC signature.
- **template params** (various) - Required - Template-specific parameters.

### Request Example
```
// Node.js
import { createHmac } from 'node:crypto'

// RFC 3986: percent-encode the !'()* characters encodeURIComponent leaves bare
const rfc3986 = s => encodeURIComponent(s)
  .replace(/[!'()*]/g, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)

const params = {
  template: 'minimal',
  title: 'Less, but better.',
  uid: 'YOUR-UID',
}
const canonical = Object.entries(params)
  .sort(([a], [b]) => (a < b ? -1 : 1))
  .map(([k, v]) => `${rfc3986(k)}=${rfc3986(v)}`)
  .join('&')
const sig = createHmac('sha256', process.env.SHOTIUM_SIGNING_SECRET)
  .update(canonical).digest('hex')

const url = `https://api.shotium.com/v1/og-image?${canonical}&sig=${sig}`
```

```
# Python
import hashlib, hmac, urllib.parse

params = {"template": "minimal", "title": "Less, but better.", "uid": "YOUR-UID"}
canonical = "&".join(
    f"{urllib.parse.quote(k, safe='')}={urllib.parse.quote(v, safe='')}"
    for k, v in sorted(params.items())
)
sig = hmac.new(SIGNING_SECRET.encode(), canonical.encode(), hashlib.sha256).hexdigest()
url = f"https://api.shotium.com/v1/og-image?{canonical}&sig={sig}"
```

### Response
#### Success Response (200)
Returns the generated image file with `Cache-Control: public, max-age=86400, immutable`.

#### Response Example
(Image file)

```

--------------------------------

### POST /v1/og-image

Source: https://shotium.com/docs

Renders a 1200×630 Open Graph image from one of five templates. Best for build-time generation.

```APIDOC
## POST /v1/og-image

### Description
Renders a 1200×630 Open Graph image from one of five templates. Best for build-time generation.

### Method
POST

### Endpoint
/v1/og-image

### Parameters
#### Request Body
- **template** (string) - Required - The template id.
- **params** (object) - Required - Template-specific parameters (see /og-templates).
- **format** (string) - Optional - Output format: `png` (default) or `jpeg`.

### Request Example
```
curl -X POST https://api.shotium.com/v1/og-image \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "blog",
    "params": { "title": "Shipping fast without breaking things", "author": "Ada L." },
    "format": "png"
  }' -o og.png
```

### Response
#### Success Response (200)
Returns the generated image file.

#### Response Example
(Image file)

```

--------------------------------

### Node.js fetch screenshot with format=jpeg

Source: https://shotium.com/docs

Fetches a JPEG screenshot in Node.js using the SHOTIUM_KEY environment variable. The response is converted to a Buffer for further processing.

```javascript
// Node.js
const res = await fetch(
  'https://api.shotium.com/v1/screenshot?url=https://example.com&format=jpeg',
  { headers: { Authorization: `Bearer ${process.env.SHOTIUM_KEY}` } },
)
const image = Buffer.from(await res.arrayBuffer())
```

--------------------------------

### POST /v1/og-image with curl

Source: https://shotium.com/docs

Generates a 1200×630 Open Graph image by POSTing to /v1/og-image. The body requires a template id and template-specific params; format defaults to png and can be set to jpeg. The response is saved to og.png.

```bash
curl -X POST https://api.shotium.com/v1/og-image \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "blog",
    "params": { "title": "Shipping fast without breaking things", "author": "Ada L." },
    "format": "png"
  }' -o og.png
```

--------------------------------

### Full-page WebP screenshot with curl

Source: https://shotium.com/docs

Renders a full-page WebP screenshot at quality 90. The full_page parameter captures the entire scroll height (up to 20,000px) and quality is only applied to lossy formats.

```bash
curl -H "Authorization: Bearer sk_live_…" \
  "https://api.shotium.com/v1/screenshot?url=https://news.ycombinator.com&full_page=true&format=webp&quality=90" \
  -o page.webp
```
Tokens:
Raw