Create Capture

Create a styled screenshot render from a URL with device frames, backgrounds, elements, text, AI styling, and output controls.

POST /v1/capture

Captures a URL, composes the requested styling, stores the image, and returns a CDN URL. Set `async` to `true` to queue a job instead.

Authentication

Bearer Token

Request Body required

application/json

url string (uri) REQUIRED

project_id string

auth_profile_id string

viewport object

width integer REQUIRED

height integer REQUIRED

capture_dpr number

user_agent string

emulate_mobile boolean

emulate_touch boolean

wait_for unknown

block string[]

Array of:

inject_css string

device string

Enum: iphone-16-pro, macbook-pro-16, ipad-pro-m4, browser-macos, browser-windows

device_color string

device_scale number

background_style string

Enum: gradient, solid, none, transparent

background_preset string

Enum: aurora, sunset, ocean, midnight, arctic, dusk, forest, ember, custom

background_color string

background_gradient string

background string

Hosted ScreenFramed background reference, e.g. fractal-glass-gradients/fractal-glass-34. Resolved to a render-sized image variant.

background_image_url string (uri)

Custom public image URL. Overrides background when both are provided.

padding number

corner_radius number

shadow string

Enum: none, soft, hard, glow, float

shadow_color string

shadow_blur number

shadow_offset_x number

shadow_offset_y number

shadow_spread number

shadow_opacity number

perspective string

Enum: none, tilt-left, tilt-right, tilt-up, tilt-down, tilt-left-strong, tilt-right-strong, iso-left, iso-right

perspective_intensity number

camera_preset string

Enum: hero, dashboard, flat, cinematic, detail

tilt_x number

tilt_y number

roll number

zoom number

offset_x number

offset_y number

frame_scale number

layout string

Enum: default, bottom-cropped, top-cropped

depth_blur number

depth_blur_type string

Enum: dir, radial, tilt, lens

depth_blur_direction string

Enum: top, bottom, left, right

depth_blur_angle number

depth_blur_position number

depth_blur_band number

depth_blur_width number

title string

title_font string

title_size number

title_color string

title_position string

Enum: above, below, bottom-left, top-left, overlay-bottom

subtitle string

subtitle_font string

subtitle_size number

subtitle_color string

badge string

text_enabled boolean

text_content string

text_x number

text_y number

text_size number

text_color string

text_gradient string

text_shadow string

text_weight number

text_font string

text_align string

Enum: left, center, right

text_max_width number

text_line_height number

text_autofit boolean

text_fit_min number

text_box_h number

text_vertical_align string

Enum: top, middle, bottom

ai boolean

ai_style boolean

ai_copy boolean

prompt string

element string

selector string

auto_balance boolean

inset number

inset_balance boolean

output object

format string

Enum: png, webp, jpg

width integer

height integer

quality integer

dpr integer

Enum: 1, 2, 3

cache_ttl number

show_resolved_params boolean

dark_mode boolean

full_page boolean

hide_selectors string[]

Array of:

border string

Enum: none, subtle, bold, glass

border_color string

border_width number

aspect_ratio string

Enum: auto, 16:9, 4:3, 1:1, 3:2, 9:16, 21:9

frame_ratio string

Enum: auto, 16:9, 4:3, 1:1, 3:2, 9:16, 21:9

watermark string

compose_mode string

Enum: satori, browser

async boolean

webhook_url string (uri)

Responses

201 Capture created

application/json

id string

url string (uri)

width integer

height integer

format string

duration_ms integer

credits_used integer

cached boolean

warnings string[]

Array of:

created_at string

resolved_params object

ai_decisions object

element_resolved object

202 Async capture queued

400 Error response

401 Error response

402 Error response

403 Error response

422 Error response

429 Error response

curl -X POST 'https://screenframed.com/v1/capture' \  -H 'Authorization: Bearer YOUR_API_TOKEN' \  -H 'Content-Type: application/json' \  -d '{  "url": "https://example.com",  "project_id": "string",  "auth_profile_id": "string",  "viewport": {    "width": 1,    "height": 1  },  "capture_dpr": 1,  "user_agent": "string",  "emulate_mobile": true,  "emulate_touch": true,  "wait_for": "load",  "block": [    "cookie-banners"  ],  "inject_css": "string",  "device": "iphone-16-pro",  "device_color": "string",  "device_scale": 0.4,  "background_style": "gradient",  "background_preset": "aurora",  "background_color": "string",  "background_gradient": "string",  "background": "string",  "background_image_url": "https://example.com",  "padding": 0,  "corner_radius": 0,  "shadow": "none",  "shadow_color": "string",  "shadow_blur": 0,  "shadow_offset_x": -100,  "shadow_offset_y": -100,  "shadow_spread": -50,  "shadow_opacity": 0,  "perspective": "none",  "perspective_intensity": 0,  "camera_preset": "hero",  "tilt_x": -30,  "tilt_y": -30,  "roll": -30,  "zoom": 50,  "offset_x": -2000,  "offset_y": -2000,  "frame_scale": 0,  "layout": "default",  "depth_blur": 0,  "depth_blur_type": "dir",  "depth_blur_direction": "top",  "depth_blur_angle": 0,  "depth_blur_position": 0,  "depth_blur_band": 0,  "depth_blur_width": 0,  "title": "string",  "title_font": "string",  "title_size": 24,  "title_color": "string",  "title_position": "above",  "subtitle": "string",  "subtitle_font": "string",  "subtitle_size": 0,  "subtitle_color": "string",  "badge": "string",  "text_enabled": true,  "text_content": "string",  "text_x": 0,  "text_y": 0,  "text_size": 8,  "text_color": "string",  "text_gradient": "string",  "text_shadow": "string",  "text_weight": 100,  "text_font": "string",  "text_align": "left",  "text_max_width": 0.1,  "text_line_height": 0.8,  "text_autofit": true,  "text_fit_min": 6,  "text_box_h": 0.05,  "text_vertical_align": "top",  "ai": true,  "ai_style": true,  "ai_copy": true,  "prompt": "string",  "element": "string",  "selector": "string",  "auto_balance": true,  "inset": 0,  "inset_balance": true,  "output": {    "format": "png",    "width": 1,    "height": 1,    "quality": 1,    "dpr": 1  },  "cache_ttl": 0,  "show_resolved_params": true,  "dark_mode": true,  "full_page": true,  "hide_selectors": [    "string"  ],  "border": "none",  "border_color": "string",  "border_width": 0,  "aspect_ratio": "auto",  "frame_ratio": "auto",  "watermark": "string",  "compose_mode": "satori",  "async": true,  "webhook_url": "https://example.com"}'

const response = await fetch('https://screenframed.com/v1/capture', {  method: 'POST',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN",      "Content-Type": "application/json"  },  body: JSON.stringify({    "url": "https://example.com",    "project_id": "string",    "auth_profile_id": "string",    "viewport": {      "width": 1,      "height": 1    },    "capture_dpr": 1,    "user_agent": "string",    "emulate_mobile": true,    "emulate_touch": true,    "wait_for": "load",    "block": [      "cookie-banners"    ],    "inject_css": "string",    "device": "iphone-16-pro",    "device_color": "string",    "device_scale": 0.4,    "background_style": "gradient",    "background_preset": "aurora",    "background_color": "string",    "background_gradient": "string",    "background": "string",    "background_image_url": "https://example.com",    "padding": 0,    "corner_radius": 0,    "shadow": "none",    "shadow_color": "string",    "shadow_blur": 0,    "shadow_offset_x": -100,    "shadow_offset_y": -100,    "shadow_spread": -50,    "shadow_opacity": 0,    "perspective": "none",    "perspective_intensity": 0,    "camera_preset": "hero",    "tilt_x": -30,    "tilt_y": -30,    "roll": -30,    "zoom": 50,    "offset_x": -2000,    "offset_y": -2000,    "frame_scale": 0,    "layout": "default",    "depth_blur": 0,    "depth_blur_type": "dir",    "depth_blur_direction": "top",    "depth_blur_angle": 0,    "depth_blur_position": 0,    "depth_blur_band": 0,    "depth_blur_width": 0,    "title": "string",    "title_font": "string",    "title_size": 24,    "title_color": "string",    "title_position": "above",    "subtitle": "string",    "subtitle_font": "string",    "subtitle_size": 0,    "subtitle_color": "string",    "badge": "string",    "text_enabled": true,    "text_content": "string",    "text_x": 0,    "text_y": 0,    "text_size": 8,    "text_color": "string",    "text_gradient": "string",    "text_shadow": "string",    "text_weight": 100,    "text_font": "string",    "text_align": "left",    "text_max_width": 0.1,    "text_line_height": 0.8,    "text_autofit": true,    "text_fit_min": 6,    "text_box_h": 0.05,    "text_vertical_align": "top",    "ai": true,    "ai_style": true,    "ai_copy": true,    "prompt": "string",    "element": "string",    "selector": "string",    "auto_balance": true,    "inset": 0,    "inset_balance": true,    "output": {      "format": "png",      "width": 1,      "height": 1,      "quality": 1,      "dpr": 1    },    "cache_ttl": 0,    "show_resolved_params": true,    "dark_mode": true,    "full_page": true,    "hide_selectors": [      "string"    ],    "border": "none",    "border_color": "string",    "border_width": 0,    "aspect_ratio": "auto",    "frame_ratio": "auto",    "watermark": "string",    "compose_mode": "satori",    "async": true,    "webhook_url": "https://example.com"  })});const data = await response.json();console.log(data);

import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.post('https://screenframed.com/v1/capture', headers=headers, json={  "url": "https://example.com",  "project_id": "string",  "auth_profile_id": "string",  "viewport": {    "width": 1,    "height": 1  },  "capture_dpr": 1,  "user_agent": "string",  "emulate_mobile": true,  "emulate_touch": true,  "wait_for": "load",  "block": [    "cookie-banners"  ],  "inject_css": "string",  "device": "iphone-16-pro",  "device_color": "string",  "device_scale": 0.4,  "background_style": "gradient",  "background_preset": "aurora",  "background_color": "string",  "background_gradient": "string",  "background": "string",  "background_image_url": "https://example.com",  "padding": 0,  "corner_radius": 0,  "shadow": "none",  "shadow_color": "string",  "shadow_blur": 0,  "shadow_offset_x": -100,  "shadow_offset_y": -100,  "shadow_spread": -50,  "shadow_opacity": 0,  "perspective": "none",  "perspective_intensity": 0,  "camera_preset": "hero",  "tilt_x": -30,  "tilt_y": -30,  "roll": -30,  "zoom": 50,  "offset_x": -2000,  "offset_y": -2000,  "frame_scale": 0,  "layout": "default",  "depth_blur": 0,  "depth_blur_type": "dir",  "depth_blur_direction": "top",  "depth_blur_angle": 0,  "depth_blur_position": 0,  "depth_blur_band": 0,  "depth_blur_width": 0,  "title": "string",  "title_font": "string",  "title_size": 24,  "title_color": "string",  "title_position": "above",  "subtitle": "string",  "subtitle_font": "string",  "subtitle_size": 0,  "subtitle_color": "string",  "badge": "string",  "text_enabled": true,  "text_content": "string",  "text_x": 0,  "text_y": 0,  "text_size": 8,  "text_color": "string",  "text_gradient": "string",  "text_shadow": "string",  "text_weight": 100,  "text_font": "string",  "text_align": "left",  "text_max_width": 0.1,  "text_line_height": 0.8,  "text_autofit": true,  "text_fit_min": 6,  "text_box_h": 0.05,  "text_vertical_align": "top",  "ai": true,  "ai_style": true,  "ai_copy": true,  "prompt": "string",  "element": "string",  "selector": "string",  "auto_balance": true,  "inset": 0,  "inset_balance": true,  "output": {    "format": "png",    "width": 1,    "height": 1,    "quality": 1,    "dpr": 1  },  "cache_ttl": 0,  "show_resolved_params": true,  "dark_mode": true,  "full_page": true,  "hide_selectors": [    "string"  ],  "border": "none",  "border_color": "string",  "border_width": 0,  "aspect_ratio": "auto",  "frame_ratio": "auto",  "watermark": "string",  "compose_mode": "satori",  "async": true,  "webhook_url": "https://example.com"})print(response.json())

201 Response

{  "id": "<string>",  "url": "<uri>",  "width": 123,  "height": 123,  "format": "<string>",  "duration_ms": 123,  "credits_used": 123,  "cached": true,  "warnings": [    "<string>"  ],  "created_at": "<string>",  "resolved_params": "<object>",  "ai_decisions": "<object>",  "element_resolved": "<object>"}

202 Response

{  "job_id": "<string>",  "status": "pending"}

400 Response

{  "error": {    "code": "<string>",    "message": "<string>",    "details": "<object>",    "retry_after": 123  }}

401 Response

{  "error": {    "code": "<string>",    "message": "<string>",    "details": "<object>",    "retry_after": 123  }}

402 Response

{  "error": {    "code": "<string>",    "message": "<string>",    "details": "<object>",    "retry_after": 123  }}

403 Response

{  "error": {    "code": "<string>",    "message": "<string>",    "details": "<object>",    "retry_after": 123  }}

422 Response

{  "error": {    "code": "<string>",    "message": "<string>",    "details": "<object>",    "retry_after": 123  }}

429 Response

{  "error": {    "code": "<string>",    "message": "<string>",    "details": "<object>",    "retry_after": 123  }}

POST /v1/capture

Base URL

Bearer Token

Request Body required application/json

{
  "url": "https://example.com",
  "project_id": "string",
  "auth_profile_id": "string",
  "viewport": {
    "width": 0,
    "height": 0
  },
  "capture_dpr": 0,
  "user_agent": "string",
  "emulate_mobile": true,
  "emulate_touch": true,
  "wait_for": null,
  "block": [
    "cookie-banners"
  ],
  "inject_css": "string",
  "device": "iphone-16-pro",
  "device_color": "string",
  "device_scale": 0,
  "background_style": "gradient",
  "background_preset": "aurora",
  "background_color": "string",
  "background_gradient": "string",
  "background": "string",
  "background_image_url": "https://example.com",
  "padding": 0,
  "corner_radius": 0,
  "shadow": "none",
  "shadow_color": "string",
  "shadow_blur": 0,
  "shadow_offset_x": 0,
  "shadow_offset_y": 0,
  "shadow_spread": 0,
  "shadow_opacity": 0,
  "perspective": "none",
  "perspective_intensity": 0,
  "camera_preset": "hero",
  "tilt_x": 0,
  "tilt_y": 0,
  "roll": 0,
  "zoom": 0,
  "offset_x": 0,
  "offset_y": 0,
  "frame_scale": 0,
  "layout": "default",
  "depth_blur": 0,
  "depth_blur_type": "dir",
  "depth_blur_direction": "top",
  "depth_blur_angle": 0,
  "depth_blur_position": 0,
  "depth_blur_band": 0,
  "depth_blur_width": 0,
  "title": "string",
  "title_font": "string",
  "title_size": 0,
  "title_color": "string",
  "title_position": "above",
  "subtitle": "string",
  "subtitle_font": "string",
  "subtitle_size": 0,
  "subtitle_color": "string",
  "badge": "string",
  "text_enabled": true,
  "text_content": "string",
  "text_x": 0,
  "text_y": 0,
  "text_size": 0,
  "text_color": "string",
  "text_gradient": "string",
  "text_shadow": "string",
  "text_weight": 0,
  "text_font": "string",
  "text_align": "left",
  "text_max_width": 0,
  "text_line_height": 0,
  "text_autofit": true,
  "text_fit_min": 0,
  "text_box_h": 0,
  "text_vertical_align": "top",
  "ai": true,
  "ai_style": true,
  "ai_copy": true,
  "prompt": "string",
  "element": "string",
  "selector": "string",
  "auto_balance": true,
  "inset": 0,
  "inset_balance": true,
  "output": {
    "format": "png",
    "width": 0,
    "height": 0,
    "quality": 0,
    "dpr": 1
  },
  "cache_ttl": 0,
  "show_resolved_params": true,
  "dark_mode": true,
  "full_page": true,
  "hide_selectors": [
    "string"
  ],
  "border": "none",
  "border_color": "string",
  "border_width": 0,
  "aspect_ratio": "auto",
  "frame_ratio": "auto",
  "watermark": "string",
  "compose_mode": "satori",
  "async": true,
  "webhook_url": "https://example.com"
}

Response

Was this page helpful?

Previous API Reference

Next Capture a raw PNG screenshot