> ## Documentation Index
> Fetch the complete documentation index at: https://docs.screenframed.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://screenframed.com/dashboard/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
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 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 Python
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 login
screenframed 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

**Transparent asset**

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

```json
    {
      "url": "https://example.com",
      "aspect_ratio": "1:1",
      "background_preset": "aurora",
      "text_enabled": true,
      "text_content": "Now shipping",
      "text_autofit": true
    }
    ```
  **AI-styled shot**

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

```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.