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.

ScreenFramed home page captured with a polished gradient background

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, cached, and warnings.

First render

bash
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"    }  }'

javascript
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);

python
import osimport requestsresponse = 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 \  --shadow \  --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",  "text_autofit": true}

json
{  "url": "https://example.com",  "ai_style": true,  "ai_copy": true,  "aspect_ratio": "16:9"}

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. site is accepted as an alias for 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