Desktop ›

Get desktop screenshot

GET/v1/sandboxes/{id}/desktop/screenshot

A picture of the sandbox's screen as it is now. It is a PNG of all of the screen at its size, with the pointer on it, unless the query asks for a JPEG, a part of the screen, a smaller picture or no pointer: each of those makes it cheaper to send and for a model to read. It is the picture as bytes. With encoding=base64 it is JSON that holds the same bytes in base64, with the picture's width and height and the part of the screen it shows, for a caller that is to hand it to a model. It changes nothing.

RequestTypeScript

import { Agental } from "agental-sdk";
const agental = new Agental();
const sandbox = await agental.sandboxes.get("sbx_2a9a47e50daec64a");
const png = await sandbox.desktop.screenshot();

Answer200 OK · DesktopScreenshot

{
"mediaType": "image/png" | "image/jpeg",
"width": integer,
"height": integer,
"region": {
"x": integer,
"y": integer,
"width": integer,
"height": integer,
},
"base64": string,
}

The picture: image/png or image/jpeg, or with encoding=base64 the JSON below.

Path

idrequired

string

e.g. "sbx_0123456789abcdef"

Query

`encoding` "base64"	base64 for JSON that holds the picture. Left out, the answer is the picture itself.
`format` "png" \| "jpeg"	png, which is the default, or jpeg, which is several times smaller for a screen with photos or gradients on it.
`quality` integer	For format=jpeg, from 1 to 100. 75 when it is left out. e.g. `60`
`x` integer or null	Pixels from the left edge of the screen to the part to take. With x, y, width and height, which go together, the picture is of that part of the screen.
`y` integer or null	Pixels from the top edge of the screen to the part to take. With x, y, width and height, which go together, the picture is of that part of the screen.
`width` integer	The width of the part to take. With x, y, width and height, which go together, the picture is of that part of the screen.
`height` integer	The height of the part to take. With x, y, width and height, which go together, the picture is of that part of the screen.
`scale` number	How much smaller than what is taken the picture is made, from 0.1 to 1: 0.5 is half as wide and half as high. A point of the picture is then at region.x + x / scale on the screen. e.g. `0.5`
`cursor` "true" \| "false"	false leaves the pointer out of the picture. It is in it when this is left out.

Headers

Authorizationrequired

Bearer key

An API key that may make this call.

Returns

200 The picture: image/png or image/jpeg, or with encoding=base64 the JSON below.

DesktopScreenshot5 fields

mediaType

image/pngimage/jpeg

width

integer

The width of the picture, which is the region's times scale.

height

integer

The height of the picture.

region

DesktopRegion4 fields

The part of the screen the picture shows, in pixels of the screen: all of it unless a part was asked for.

x

integer

y

integer

width

integer

height

integer

base64

string

The picture, in base64.

Errors and other answers

400	`invalid_request` x, y, width and height are not all given, the part is not on the screen, or quality was given for a PNG. The message says which.
404	Not found.
409	sandbox_not_running, or
409	`desktop_not_running` no desktop is turned on for the sandbox, or it is turned on and is not running yet, as in the moments after a start. PUT /v1/sandboxes/{id}/desktop turns it on, and starts one that ended.
501	`desktop_not_configured` sandboxes here have no desktop. GET /v1/policy says so as desktop.

Every error answers { "error": { "code", "message" } }; a key without the action a call needs answers 403 key_action_forbidden, naming it.

← Disable desktop Get desktop clipboard →