# SteamWebAPI Screenshot API

[Visual guide and image examples](https://www.steamwebapi.com/cs2-screenshot-api)

Render CS2 items from an inspect link using your existing SteamWebAPI API key.
The default response is an AVIF image showing both sides with float information
on the [default background image](https://cs2screen.com/assets/cs2screenbg.png),
aligned to the top. Front, back, transparent cutouts, solid background colors
and custom labels are also supported.

**Availability:** included at no extra cost in every package, including Free and
Free+, subject to the package limits.

## Authentication

Send your SteamWebAPI key in the `X-Api-Key` header. The `Key` header and `key`
query parameter are also accepted. Conflicting credentials are rejected.
Screenshot-specific package limits take precedence. If your package does not
define them, its Global limits apply. Explicit zero day/month quotas block access.
First use may take longer while access is initialized.

## Render a screenshot

`GET https://www.steamwebapi.com/steam/api/screenshot`

Send options as query parameters. `game` defaults to `cs2`.

| Parameter | Default | Accepted values |
| --- | --- | --- |
| `url` | Required | Full URL-encoded `steam://` CS2 inspect link, at most 16384 bytes |
| `game` | `cs2` | `cs2` |
| `mode` | `both` | `front`, `back`, `both`; defaults to `front` when `view=transparent` is supplied without a mode |
| `width` | `1920` | Integer from 256 to 2048; height scales proportionally. Below 960, use `with_float=false`. |
| `view` | Omitted (default background image) | `transparent` for a cutout; requires `front` or `back` and disables the default background and float information |
| `background_color` | Omitted (default background image) | Solid hex color `#RRGGBB` instead of the background image; URL-encode `#` as `%23` |
| `with_float` | `true`; `false` for transparent cutouts | `true`, `false`, `1`, `0`; enabling it requires `width` of at least 960 and cannot be combined with `view=transparent` |
| `item_name` | Original item name | Custom label, at most 64 characters |
| `paint_name` | Original finish name | Custom label, at most 64 characters |
| `format` | `screen` | `screen`, `download`, `base64` |
| `idempotency_key` | Generated | 1–128 ASCII letters, digits, `.`, `_`, `:`, `-`; alternatively send `Idempotency-Key` |

Use `mode=both` for both sides. `bothsides` is not a mode value.
`view=transparent` cannot be combined with `mode=both`, `background_color` or
`with_float=true`. It automatically omits the background and float information.
Unknown and repeated query parameters return HTTP 422.

### Default: both sides, background image and float information

```bash
curl --get 'https://www.steamwebapi.com/steam/api/screenshot' \
  --header 'X-Api-Key: YOUR_STEAMWEBAPI_KEY' \
  --header 'Idempotency-Key: YOUR_UNIQUE_REQUEST_ID' \
  --data-urlencode 'url=YOUR_FULL_INSPECT_LINK' \
  --max-time 100 --dump-header screenshot-headers.txt --output screenshot-response
```

No styling parameters are required for this default. The background image and
its top alignment are selected automatically; custom background-image URLs and
alignment parameters are not public query options. Use `with_float=false` to
hide float information, or `background_color` to use a solid color instead.

### Front with a transparent background

```bash
curl --get 'https://www.steamwebapi.com/steam/api/screenshot' \
  --header 'X-Api-Key: YOUR_STEAMWEBAPI_KEY' \
  --header 'Idempotency-Key: YOUR_UNIQUE_REQUEST_ID' \
  --data-urlencode 'url=YOUR_FULL_INSPECT_LINK' \
  --data-urlencode 'mode=front' \
  --data-urlencode 'view=transparent' \
  --data-urlencode 'width=1920' \
  --max-time 100 --dump-header screenshot-headers.txt --output screenshot-response
```

For the reverse side, change `mode=front` to `mode=back`.
Check the HTTP status and Content-Type before treating the saved response as
an image: an unfinished render returns JSON with HTTP 202.

### Both sides with a solid background and float information

```bash
curl --get 'https://www.steamwebapi.com/steam/api/screenshot' \
  --header 'X-Api-Key: YOUR_STEAMWEBAPI_KEY' \
  --header 'Idempotency-Key: ANOTHER_UNIQUE_REQUEST_ID' \
  --data-urlencode 'url=YOUR_FULL_INSPECT_LINK' \
  --data-urlencode 'mode=both' \
  --data-urlencode 'background_color=#18324B' \
  --data-urlencode 'with_float=true' \
  --data-urlencode 'width=1920' \
  --data-urlencode 'format=download' \
  --max-time 100 --dump-header screenshot-headers.txt --output screenshot-response
```

Add `item_name` and `paint_name` to customize the labels. To receive JSON
instead of binary image bytes, use `format=base64`.

## Responses and pending renders

| Status | Response |
| --- | --- |
| `200`, `format=screen` | `Content-Type: image/avif`; binary image, displayed inline |
| `200`, `format=download` | `image/avif`; `Content-Disposition: attachment; filename="screenshot.avif"` |
| `200`, `format=base64` | JSON `{"status":"success","image":"data:image/avif;base64,..."}` |
| `202` | JSON `{"status":"pending","job_id":"...","idempotency_key":"..."}` and `Retry-After` |

Accepted requests return the `Idempotency-Key` response header. Responses use
`Cache-Control: private, no-store`.

After HTTP 202, wait for `Retry-After`, then retrieve the result through the
same endpoint and with the same customer key:

```bash
curl --get 'https://www.steamwebapi.com/steam/api/screenshot' \
  --header 'X-Api-Key: YOUR_STEAMWEBAPI_KEY' \
  --data-urlencode 'job_id=JOB_ID_FROM_THE_202_RESPONSE' \
  --data-urlencode 'format=download' \
  --max-time 100 --dump-header screenshot-headers.txt --output screenshot-response
```

`job_id` accepts 1–128 ASCII letters, digits, `_` or `-`. Supply it without
`url` or render options. Only authentication, `game`, `format` and
`idempotency_key` may accompany it. A still-running job returns HTTP 202 again.
Completed results expire after three hours; save the returned image yourself
if you need it longer. A job ID alone does not grant image access.

## Retries and errors

Choose an idempotency key before the first render and reuse it with unchanged
render options after a timeout. Reusing the same key avoids creating another
job, but each authenticated request still counts towards the screenshot
quota. Use a new idempotency key for a deliberately new request. A single
request has a maximum processing budget of 95 seconds.

Errors return JSON with `status`, `code` and `message`:

```json
{"status":"error","code":"invalid_request","message":"Transparent screenshots require mode=front or mode=back."}
```

| HTTP status | Meaning / action |
| --- | --- |
| `401` | Missing or invalid SteamWebAPI key |
| `402` | Current package does not allow screenshot registration |
| `403` | Screenshot access is disabled |
| `404` | Result does not exist or is not owned by this key |
| `405` | Unsupported method; use GET |
| `406` | Inspect-link format is not supported |
| `409` | Registration or idempotency conflict; check the message and render options |
| `410` | Stored result expired; request a new render |
| `422` | Invalid parameters or incompatible options |
| `429` | Quota, capacity or access-initialization limit; respect `Retry-After` |
| `502` | Invalid screenshot response; retry with the same idempotency key |
| `503` | Endpoint disabled or temporarily unavailable; respect `Retry-After` when present |

## Screenshot usage

`GET https://www.steamwebapi.com/steam/api/screenshot/usage`

Use the same authentication as for rendering. This endpoint initializes access
for an eligible key if necessary. Load usage on demand; do not poll it for
every screenshot. Respect `Retry-After` if it returns HTTP 429.

```json
{
  "status": "success",
  "active": true,
  "limits": {"minute": 100, "day": 1000, "month": 10000},
  "usage": {"minute": 1, "day": 25, "month": 240, "total": 500, "blocked": 0},
  "timezone": "UTC",
  "period": "calendar",
  "unit": "authenticated_requests"
}
```

These numbers are examples; actual limits depend on your configured screenshot
quota. A `null` limit means unlimited. Day and month counters reset at UTC
calendar boundaries. Result retrieval and render retries also count.
`total` covers the retained usage history, not necessarily lifetime usage.
These counters are separate from the ordinary SteamWebAPI credit balance.

## Existing integrations

`GET /steam/api/float/screenshot` is the deprecated legacy PNG endpoint. It
continues to support its existing parameters and billing behavior. Its logo,
background-image and named-color options are specific to that endpoint.
The new route supports only the parameters listed above and returns AVIF.
Migration is explicit; existing clients are not redirected.