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

# Parameter Reference

Complete public parameter reference for ScreenFramed capture requests.

This page groups the most important `POST /v1/capture` fields by job. For endpoint-level schema details, see [Create Capture](/api/capture).

## Source and page loading

| Field | Type | Notes |
|---|---|---|
| `url` | `string` | Required. Must be an `http` or `https` URL. Alias: `site`. |
| `viewport.width` / `viewport.height` | `number` | Browser viewport before composition. |
| `capture_dpr` | `number` | Browser capture DPR. Valid range: `1` to `4`. |
| `user_agent` | `string` | Browser user agent override, up to 500 characters. |
| `emulate_mobile` | `boolean` | Chromium mobile viewport emulation. Defaults from physical device frames. |
| `emulate_touch` | `boolean` | Chromium touch emulation. Defaults from physical device frames. |
| `wait_for` | `load` \| `networkidle` \| `domcontentloaded` \| number | Event or millisecond delay before capture. |
| `full_page` | `boolean` | Capture the full scrollable page instead of only the viewport. |
| `dark_mode` | `boolean` | Prefer dark-mode rendering where the page supports it. |
| `hide_selectors` | `string[]` | CSS selectors to hide before capture. |
| `block` | `string[]` | One or more of `cookie-banners`, `ads`, `chat-widgets`, `popups`. |
| `inject_css` | `string` | CSS applied before capture. |

## Project and auth

| Field | Type | Notes |
|---|---|---|
| `project_id` | `string` | Optional project scope, such as `prj_...`. |
| `auth_profile_id` | `string` | Optional authenticated browser state, such as `ap_...`. |

## Natural language and AI

| Field | Type | Notes |
|---|---|---|
| `prompt` | `string` | Natural-language request that resolves to normal capture params before validation. |
| `ai` | `boolean` | Enables bundled AI styling and copy behavior. |
| `ai_style` | `boolean` | Lets AI choose styling from page type, tone, and brand colors. |
| `ai_copy` | `boolean` | Lets AI generate title, subtitle, or badge copy from the captured page. |
| `show_resolved_params` | `boolean` | Include resolved params in the response for debugging. |

## Element capture

| Field | Type | Notes |
|---|---|---|
| `selector` | `string` | CSS selector for deterministic element capture. |
| `element` | `string` | Natural-language element description. Aliases: `component`, `componentPrompt`, `component_prompt`. |
| `inset` | `number` | Internal padding around captured element. Range: `0` to `100`. |
| `inset_balance` | `boolean` | Fill inset using detected component background when possible. |
| `auto_balance` | `boolean` | Let ScreenFramed choose helpful default styling when explicit style is omitted. |

## Devices and frames

| Field | Type | Values |
|---|---|---|
| `device` | `string` | `iphone-16-pro`, `macbook-pro-16`, `ipad-pro-m4`, `browser-macos`, `browser-windows` |
| `device_color` | `string` | Device-specific color variant. |
| `device_scale` | `number` | Range: `0.4` to `1.0`. |
| `frame_ratio` | `string` | `auto`, `16:9`, `4:3`, `1:1`, `3:2`, `9:16`, `21:9`. |
| `frame_scale` | `number` | Advanced frame scale multiplier. |

## Backgrounds

| Field | Type | Values |
|---|---|---|
| `background_style` | `string` | `gradient`, `solid`, `none`, `transparent`. |
| `background_preset` | `string` | `aurora`, `sunset`, `ocean`, `midnight`, `arctic`, `dusk`, `forest`, `ember`, `custom`. Aliases: `bg`, `bg_preset`. |
| `background_color` | `string` | CSS color. Alias: `bg_color`. |
| `background_gradient` | `string` | CSS gradient string. |
| `background` | `string` | Hosted ScreenFramed background reference, e.g. `fractal-glass-gradients/fractal-glass-34`. |
| `background_image_url` | `string` | Publicly reachable custom image URL. Overrides `background` when both are provided. |

`background_style: "transparent"` cannot be combined with `background`, `background_preset`, or `background_image_url`, and requires `png` or `webp` output.

## Layout, camera, and effects

| Field | Type | Values / range |
|---|---|---|
| `aspect_ratio` | `string` | `auto`, `16:9`, `4:3`, `1:1`, `3:2`, `9:16`, `21:9`. |
| `padding` | `number` | `0` to `200`. |
| `corner_radius` | `number` | `0` to `40`. |
| `camera_preset` | `string` | `hero`, `dashboard`, `flat`, `cinematic`, `detail`. |
| `layout` | `string` | `default`, `bottom-cropped`, `top-cropped`. |
| `perspective` | `string` | `none`, `tilt-left`, `tilt-right`, `tilt-up`, `tilt-down`, `tilt-left-strong`, `tilt-right-strong`, `iso-left`, `iso-right`. |
| `perspective_intensity` | `number` | `0` to `100`. |
| `tilt_x` / `tilt_y` / `roll` | `number` | `-30` to `30`. |
| `zoom` | `number` | `50` to `300`. |
| `offset_x` / `offset_y` | `number` | `-2000` to `2000`. |
| `compose_mode` | `string` | `satori` or `browser`. |

## Depth blur

| Field | Type | Values / range |
|---|---|---|
| `depth_blur` | `number` | `0` to `30`. |
| `depth_blur_type` | `string` | `dir`, `radial`, `tilt`, `lens`. |
| `depth_blur_direction` | `string` | `top`, `bottom`, `left`, `right`. |
| `depth_blur_angle` | `number` | `0` to `360`. |
| `depth_blur_position` | `number` | `0` to `1`. |
| `depth_blur_band` | `number` | `0` to `1`, for `tilt`. |
| `depth_blur_width` | `number` | `0` to `1`, for `lens`. |

## Shadows and borders

| Field | Type | Values / range |
|---|---|---|
| `shadow` | `string` | `none`, `soft`, `hard`, `glow`, `float`. |
| `shadow_color` | `string` | CSS color for shadow. |
| `shadow_blur` | `number` | `0` to `100`. Enables custom shadow mode. |
| `shadow_offset_x` / `shadow_offset_y` | `number` | `-100` to `100`. |
| `shadow_spread` | `number` | `-50` to `50`. |
| `shadow_opacity` | `number` | `0` to `1`. |
| `border` | `string` | `none`, `subtle`, `bold`, `glass`. |
| `border_color` | `string` | CSS color for border. |
| `border_width` | `number` | `0` to `20`. Enables custom border mode. |

## Structured text overlays

| Field | Type | Notes |
|---|---|---|
| `title`, `subtitle`, `badge` | `string` | Structured text overlay fields. |
| `title_position` | `string` | `above`, `below`, `bottom-left`, `top-left`, `overlay-bottom`. |
| `title_font`, `subtitle_font` | `string` | Font family. |
| `title_size`, `subtitle_size` | `number` | Font size. |
| `title_color`, `subtitle_color` | `string` | CSS color. |

## Free-form text overlays

| Field | Type | Notes |
|---|---|---|
| `text_enabled` | `boolean` | Enables free-form text overlay. |
| `text_content` | `string` | Max 500 characters. |
| `text_x` / `text_y` | `number` | Position as a fraction from `0` to `1`. |
| `text_size` | `number` | `8` to `1200`. |
| `text_weight` | `number` | `100` to `900`. |
| `text_font` | `string` | Font family. |
| `text_align` | `string` | `left`, `center`, `right`. |
| `text_color` | `string` | CSS color. |
| `text_gradient` | `string` | CSS gradient text fill. |
| `text_shadow` | `string` | CSS text shadow value. |
| `text_max_width` | `number` | `0.1` to `1`. |
| `text_line_height` | `number` | `0.8` to `2.5`. |
| `text_autofit` | `boolean` | Shrink text to fit a bounded box. |
| `text_fit_min` | `number` | `6` to `200`. |
| `text_box_h` | `number` | `0.05` to `1`. |
| `text_vertical_align` | `string` | `top`, `middle`, `bottom`. |

## Output

| Field | Type | Values / range |
|---|---|---|
| `output.format` | `string` | `png`, `webp`, `jpg`. |
| `output.width` / `output.height` | `number` | `1` to `6144`. |
| `output.quality` | `number` | Format-dependent quality setting. |
| `output.dpr` | `number` | `1`, `2`, or `3`. |
| `cache_ttl` | `number` | Cache reuse window in seconds. |
| `async` | `boolean` | Queue a job instead of waiting. |
| `webhook_url` | `string` | Optional webhook URL for async jobs. |

## Removed fields

| Field | Replacement |
|---|---|
| `template` | Compose with `aspect_ratio`, `device`, `background_*`, and camera controls. |
| `window_controls` | Use `device: "browser-macos"` or `device: "browser-windows"`. |