# glbshot

Base URL: https://glbshot.com

glbshot renders screenshots from remote `.glb` files and returns the image bytes directly.

## Endpoint

`GET https://glbshot.com/api/v1/screenshot/{args}/{url}`

- `args` is a comma-separated list of `key:value` pairs.
- Use `-` or `_` for default args.
- `url` must be an `http://` or `https://` URL to a remote `.glb` file.
- Remote source models must be `100MB` or smaller.
- Output `width` and `height` must each be `2048` pixels or smaller.
- The response body is the rendered image itself, not JSON.

## Argument Reference

| Short | Long | Type | Default | Notes |
| --- | --- | --- | --- | --- |
| `t` | `timeout` | integer milliseconds | `120000` | Maximum render time before failure |
| `w` | `width` | integer pixels | `1024` | Output image width, max `2048` |
| `h` | `height` | integer pixels | `1024` | Output image height, max `2048` |
| `c` | `color` | CSS color string | white for JPEG, transparent otherwise | Background color |
| `@` | `model_viewer_version` | string | latest | Pinned `model-viewer` version such as `1.9` |
| `m` | `model_viewer_attributes` | URL query string | none | Pass `<model-viewer>` attributes encoded like a query string |
| `o` | none | string | `0deg 75deg 105%` | Full `camera-orbit` value as `$theta $phi $radius` |
| `ot` | none | string | `0deg` | Override only camera-orbit theta |
| `op` | none | string | `75deg` | Override only camera-orbit phi |
| `or` | none | string | `105%` | Override only camera-orbit radius |
| `r` | none | string | `0deg` | Override only orientation roll |
| `p` | none | string | `0deg` | Override only orientation pitch |
| `y` | none | string | `0deg` | Override only orientation yaw |
| `q` | `image_quality` | number `0-100` or `0-1` | `0.92` | JPEG/WebP quality. Ignored for PNG |
| `f` | `format` | `png`, `jpg`, `jpeg`, `webp` | `jpg` | Output image format |

## Response

- Success: `200 OK` with `Content-Type: image/jpeg`, `image/png`, or `image/webp`
- Failure: JSON like `{"error":"..."}` with a `4xx` or `5xx` status
- Oversized width or height returns `400`
- Oversized source GLB returns `413`

## Usage Notes For LLMs

- Prefer `f:png` when you need transparency.
- Prefer `f:jpeg` or `f:webp` for smaller preview images.
- Keep preview requests modest, such as `w:240,h:240` or `w:512,h:512`.
- If `m` contains `&`, `=`, spaces, or other reserved characters, percent-encode the entire attribute string inside the path segment.
- The source model URL can usually be used directly if it is a normal HTTPS URL. If it contains reserved path characters, percent-encode it.
- Orbit merge priority is: `ot` / `op` / `or` > `o` > nested `m` `camera-orbit` > defaults.
- Missing orbit components are filled from lower-priority sources, then from the default `camera-orbit` value `0deg 75deg 105%`.
- Orientation merge priority is: `r` / `p` / `y` > nested `m` `orientation` > defaults.
- Missing orientation components are filled from lower-priority sources, then from the default `orientation` value `0deg 0deg 0deg`.

## Examples

### 1. 240x240 JPEG Preview

`https://glbshot.com/api/v1/screenshot/w:240,h:240,q:90,f:jpeg/https://github.com/KhronosGroup/glTF-Sample-Models/raw/refs/heads/main/2.0/Duck/glTF-Binary/Duck.glb`

### 2. Default Settings

`https://glbshot.com/api/v1/screenshot/-/https://github.com/KhronosGroup/glTF-Sample-Models/raw/refs/heads/main/2.0/Avocado/glTF-Binary/Avocado.glb`

### 3. Transparent PNG

`https://glbshot.com/api/v1/screenshot/w:512,h:512,f:png/https://github.com/KhronosGroup/glTF-Sample-Models/raw/refs/heads/main/2.0/DamagedHelmet/glTF-Binary/DamagedHelmet.glb`

### 4. WebP With model-viewer Attributes

`https://glbshot.com/api/v1/screenshot/w:512,h:512,f:webp,m:auto-rotate%3Dtrue%26camera-controls%3Dtrue/https://github.com/KhronosGroup/glTF-Sample-Models/raw/refs/heads/main/2.0/Duck/glTF-Binary/Duck.glb`

### 5. Set Full Camera Orbit

`https://glbshot.com/api/v1/screenshot/w:512,h:512,o:180deg%2060deg%20120%25/https://github.com/KhronosGroup/glTF-Sample-Models/raw/refs/heads/main/2.0/Duck/glTF-Binary/Duck.glb`

### 6. Override Only Orbit Theta

`https://glbshot.com/api/v1/screenshot/w:512,h:512,ot:180deg/https://github.com/KhronosGroup/glTF-Sample-Models/raw/refs/heads/main/2.0/Duck/glTF-Binary/Duck.glb`

### 7. Merge Orbit With Nested model-viewer Attributes

`https://glbshot.com/api/v1/screenshot/w:512,h:512,m:camera-orbit%3D45deg+auto+150%2526camera-controls%3Dtrue,op:80deg/https://github.com/KhronosGroup/glTF-Sample-Models/raw/refs/heads/main/2.0/Duck/glTF-Binary/Duck.glb`

### 8. Merge Orientation With Nested model-viewer Attributes

`https://glbshot.com/api/v1/screenshot/w:512,h:512,m:orientation%3D15deg+10deg+5deg%26camera-controls%3Dtrue,p:-20deg,y:180deg/https://github.com/KhronosGroup/glTF-Sample-Models/raw/refs/heads/main/2.0/Duck/glTF-Binary/Duck.glb`