API Reference

Streams

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Add frame

POST/v1/streams/{namespace}/frames

Ingest a single livestream frame as an image data URI plus relative timestamp in milliseconds. The stream does not need to be created beforehand. Only image/jpeg, image/png, and image/webp are accepted. The decoded bytes must match the declared mime type, decode as a valid image, stay within 5 MB, and stay within 4096x4096 / 16,000,000 total pixels. Timestamps are relative milliseconds from stream start and must be unique and strictly increasing within a stream. Duplicate or out-of-order frame timestamps are accepted at the API boundary but ignored by downstream processing. This method returns immediately after the frame has been accepted for processing.

Path ParametersExpand Collapse

namespace: string

The namespace to ingest stream data into

Body ParametersJSONExpand Collapse

image_data_uri: string

A data URI containing a base64-encoded frame image. Only image/jpeg, image/png, and image/webp are accepted. The decoded bytes must match the declared mime type, decode as a valid image, stay within 5 MB, and stay within 4096x4096 / 16,000,000 total pixels.

stream_id: string

timestamp: number

minimum0

ReturnsExpand Collapse

requestId: string

status: "accepted"

Add frame

HTTP

HTTP

TypeScript

Python

curl https://api.safetykit.com/v1/streams/$NAMESPACE/frames \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $SAFETYKIT_API_KEY" \
    -d '{
          "image_data_uri": "data:image/webp;base64,UklGRiIAAABXRUJQVlA4IBYAAAAwAQCdASoQABAAPm02mUmkIyIh...",
          "stream_id": "YOUR_STREAM_ID",
          "timestamp": 1000
        }'

200 example

{
  "requestId": "req_01h2m7qdmdjckc30e1mnq6xqfd",
  "status": "accepted"
}

Returns Examples

200 example

{
  "requestId": "req_01h2m7qdmdjckc30e1mnq6xqfd",
  "status": "accepted"
}