> For the complete documentation index, see [llms.txt](https://docs.eyepop.ai/developer-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eyepop.ai/developer-documentation/platform/response-format.md).

# Response Format

The JSON documents a Pop returns, whichever way you call it

Whether you call EyePop from the Python or Node SDK, the CLI or plain HTTP, a Pop answers in the same JSON. A response is a sequence of **predictions**. A prediction says what the Pop found in one image, or in one frame of a video: the people, the text, the classification, and where each one is. A single image gets one prediction; a video gets one for every frame the Pop processed.

### A first look

The Pop below runs `eyepop.person:latest` on one image of a person standing in a lobby. Its whole response is one prediction:

<figure><img src="https://1956543008-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2tRktyRCGgE1tPlAfT4h%2Fuploads%2Fgit-blob-62c52ed31e70274d3f41cb6ed145ae800cb36130%2Fresponse-format-lobby.jpg?alt=media" alt="A person in a dark coat and a red scarf stands in the middle of an office lobby, with a box drawn around her"><figcaption><p>The image, 1280 × 720 pixels, with the one object the Pop found. The person is generated.</p></figcaption></figure>

```json
{
  "source_id": "0336f945-d4a7-11f1-9dc3-4e4f5a7da4bd",
  "source_width": 1280,
  "source_height": 720,
  "timestamp": 0,
  "seconds": 0,
  "objects": [
    {
      "classLabel": "person",
      "confidence": 0.9775,
      "x": 503.281,
      "y": 251.718,
      "width": 166.562,
      "height": 464.765,
      "orientation": 0
    }
  ]
}
```

Read it from the outside in:

1. `source_id`, `source_width` and `source_height` say which media this is about and how big it is: every position in the prediction is measured in this 1280 × 720 frame.
2. `timestamp` and `seconds` say *when* in the media: the start, since an image has only one moment.
3. `objects` lists what was found. Here one person, 97.75 % certain, whose box starts 503 pixels from the left and 251 pixels from the top of the image.

### What this section covers

* [Spatial Attributes](https://docs.eyepop.ai/developer-documentation/platform/response-format/spatial-attributes.md) — how positions, sizes, outlines and masks are expressed
* [Temporal Attributes](https://docs.eyepop.ai/developer-documentation/platform/response-format/temporal-attributes.md) — `timestamp`, `duration` and `captured_at`, and which to use for what
* [Predictions](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions.md) — the prediction document, from its top-level fields down to each kind of result

### Conventions

A few rules hold for every prediction:

* **Absent, not null.** A key with nothing to report is left out. A prediction with nothing found has no `objects` key at all rather than an empty list. Treat every key as optional except `source_width`, `source_height` and `timestamp`.
* **Names.** Most keys are camelCase (`classLabel`, `trackId`, `keyPoints`), a few older ones snake\_case (`source_width`, `captured_at`, `track_events`). Both are part of the format.
* **Units.** Positions are in pixels of the source, times in nanoseconds, angles in radians and confidences between 0 and 1. The pages that follow say where something differs.

### Where you receive it

The predictions are the same everywhere; what differs is how they are handed to you.

|                | Predictions                                                                                    |
| -------------- | ---------------------------------------------------------------------------------------------- |
| **Python SDK** | `job.predict()` returns one prediction at a time, as a `dict`                                  |
| **Node SDK**   | The result stream yields one `Prediction` at a time                                            |
| **CLI**        | `eyepop run --json` prints one line per prediction, as `{"file": …, "response": <prediction>}` |
| **HTTP**       | One prediction per line with `Accept: application/jsonl`                                       |

Over HTTP, ask for this format with `version=3`. The [on-premise instance](https://docs.eyepop.ai/developer-documentation/cli/on-premise.md) takes the same request at `http://127.0.0.1:8080`:

```bash
PIPELINE_ID=$(curl -sS http://127.0.0.1:8080/pipelines | jq -r '.[0].id')

curl -sS -X POST \
  "http://127.0.0.1:8080/pipelines/$PIPELINE_ID/source?mode=queue&processing=sync&version=3" \
  -H 'Content-Type: image/jpeg' \
  -H 'Accept: application/jsonl' \
  --data-binary @image.jpg
```

The SDKs always ask for `version=3` on their own.

### Next steps

* [Spatial Attributes](https://docs.eyepop.ai/developer-documentation/platform/response-format/spatial-attributes.md) — where in the frame
* [Temporal Attributes](https://docs.eyepop.ai/developer-documentation/platform/response-format/temporal-attributes.md) — when in the media
* [Predictions](https://docs.eyepop.ai/developer-documentation/platform/response-format/predictions.md) — every field of a prediction
