Quickstart

Make your first styled ScreenFramed render with cURL, JavaScript, Python, or the CLI.

This guide creates one polished screenshot from a public URL and returns a CDN URL you can use immediately.

Create an API key

Open API Keys, create a live or test key, and store it as an environment variable.

bash
export SCREENFRAMED_API_KEY="sf_live_..."

Render a screenshot

Send a POST /v1/capture request with a URL and a few visual controls.

Use the CDN URL

The response includes url, width, height, format, credits_used, and cache status.

First render

curl -X POST "https://screenframed.com/v1/capture" \
  -H "Authorization: Bearer $SCREENFRAMED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://screenframed.com",
    "device": "browser-macos",
    "background_preset": "midnight",
    "shadow": "float",
    "padding": 72,
    "aspect_ratio": "16:9",
    "output": {
      "format": "png"
    }
  }'

const response = await fetch("https://screenframed.com/v1/capture", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCREENFRAMED_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://screenframed.com",
    device: "browser-macos",
    background_preset: "midnight",
    shadow: "float",
    padding: 72,
    aspect_ratio: "16:9",
    output: { format: "png" },
  }),
});

const render = await response.json();
console.log(render.url);

import os
import requests

response = requests.post(
    "https://screenframed.com/v1/capture",
    headers={
        "Authorization": f"Bearer {os.environ['SCREENFRAMED_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://screenframed.com",
        "device": "browser-macos",
        "background_preset": "midnight",
        "shadow": "float",
        "padding": 72,
        "aspect_ratio": "16:9",
        "output": {"format": "png"},
    },
)

render = response.json()
print(render["url"])

Response

json
{  "id": "cap_01KNS1WNPW9FCHZSK4XNTHMB0H",  "url": "https://cdn.screenframed.com/r/cap_01KNS1WNPW9FCHZSK4XNTHMB0H.png",  "width": 1600,  "height": 900,  "format": "png",  "duration_ms": 1842,  "credits_used": 3,  "cached": false,  "warnings": [],  "created_at": "2026-04-27T15:00:00.000Z"}

Try the CLI

bash
npx @screenframed/cli loginscreenframed capture https://screenframed.com \  --device browser-macos \  --background midnight \  --output screenframed.png

The CLI is best when you want a local file. The API is best when your product needs the hosted render URL.

Common next changes

json
{  "url": "https://example.com",  "selector": ".feature-card",  "background_style": "transparent",  "output": { "format": "png" }}

json
{  "url": "https://example.com",  "aspect_ratio": "1:1",  "background_preset": "aurora",  "text_enabled": true,  "text_content": "Now shipping"}

json
{  "url": "https://example.com/dashboard",  "async": true,  "webhook_url": "https://example.com/webhooks/screenframed"}

Troubleshooting

Quickstart troubleshooting

Use a full URL

Use a complete http:// or https:// URL.

Send bearer auth

Use Authorization: Bearer ...; query-string API keys are supported but not recommended.

Queue slow jobs

Use async: true for long pages, authenticated dashboards, or batch automation.

Choose a transparent-safe format

For transparent output, use png or webp; JPG cannot preserve alpha.

Was this page helpful?

Previous Introduction

Next Installation