# POST /capture

> Talos next · Since 0.6

## Request

#### Request body: `CaptureRequest`

`POST /capture` request. The `kind` field picks the variant.

| Value | Meaning |
|---|---|
| `frame` | One frame from the scene's active camera. `argus_capture::frame`. |
| `clip` | A run of frames. `argus_capture::clip`. |
| `at` | One frame from an arbitrary eye point. `argus_capture::at`. |
| `views` | The four canonical views of one entity: front, side, top, iso. `argus_capture::views`. |
| `material` | One material on a preview shape under the scene's sky, sun and look, without placing it. |

## Response

#### Response: `CaptureResponse`

`POST /capture` JSON response: one or more frames.

| Field | Type | Present | Description |
|---|---|---|---|
| `kind` | `string` | always | Which request kind produced this: `frame`, `clip`, `at`, or `views`. |
| `frames` | `CapturedFrame[]` | always | The captured frames, in capture order. |
| `elapsed_ms` | `number` | always | Wall-clock milliseconds the whole capture took, measured on the sim thread. |

#### Response: `CapturedFrame`

One captured frame.

| Field | Type | Present | Description |
|---|---|---|---|
| `frame_index` | `integer` | always | The frame this image was rendered at. |
| `view` | `string` | sometimes | Which of the four canonical views this is, for a `views` capture: `front`, `side`, `top`, `iso`. Absent for every other kind. |
| `width` | `integer` | always | Image width in pixels. |
| `height` | `integer` | always | Image height in pixels. |
| `png` | `string` | always | The colour buffer, PNG, base64 (standard alphabet, padded). |
| `depth` | `string` | sometimes | Linear depth, `0` at the near plane and `1` at the far plane: base64 of `width * height` little-endian `f32`s, row-major. Present only when `buffers.depth` was set. |
| `ids` | `string` | sometimes | The entity id buffer: base64 of `width * height` little-endian `u32`s, row-major. Present only when `buffers.ids` was set. |
| `camera` | `CameraView` | always | The camera this frame was taken through. |
| `perf` | `CapturePerf` | always | What this capture cost. |

#### Response: `CameraView`

The camera a frame was taken through.

| Field | Type | Present | Description |
|---|---|---|---|
| `eye` | `number[3]` | always | Eye position in world space. |
| `target` | `number[3]` | always | The point the camera looks at. |
| `up` | `number[3]` | always | The camera's up vector. |
| `fovY` | `number` | always | Vertical field of view in radians. |
| `near` | `number` | always | Near clip distance in metres. |
| `far` | `number` | always | Far clip distance in metres. |
| `ortho` | `number` | sometimes | Set when the frame was orthographic: half the view's height in world units. Every ray is then parallel to the view direction and `fovY` does not apply; absent for a perspective frame. |
| `arm` | `CameraArmView` | sometimes | A third-person or orbit rig's boom when the frame was taken through one: its length, whether a wall collapsed it and the character fade. On a `frame` capture of the live camera only — absent from `at`, `views` and `clip` frames, and whenever no arm rig is active. |

#### Response: `CapturePerf`

What one capture cost. Mirrors `argus_capture::FramePerf`.

| Field | Type | Present | Description |
|---|---|---|---|
| `render_ms` | `number` | always | Time submitting the render passes. |
| `readback_ms` | `number` | always | Time reading the buffers back off the GPU. |
| `encode_ms` | `number` | always | Time encoding the PNG. |
| `total_ms` | `number` | always | Total for this frame: render plus readback plus encode. |
| `draw_calls` | `integer` | always | Draw calls submitted for this capture, overlay passes included. |
| `instances` | `integer` | always | Instances submitted in the opaque pass. |
| `triangles` | `integer` | always | Triangles submitted in the opaque pass. |
| `overlay_vertices` | `integer` | always | Vertices submitted by the overlay passes. |

## Example

```sh
curl -X POST "http://127.0.0.1:7700/capture" --json @body.json
```

Start a server with `argus run --serve`; the port is `--port` (7700 by default). The request and response fields are in the query API guide.