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.

Errors: 400 for an invalid body or an image that fails validation, with the reason in the message. 401 for a missing Authorization header. 403 for an invalid API key. 429 when the rate limit is exceeded. 5xx for transient internal failures. Retry 429 and 5xx with exponential backoff. Frame ingestion is idempotent, so a retried request that already succeeded is ignored. Do not retry other 4xx errors, they indicate a problem with the request.

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

frame_id: optional string

metadata: optional map[unknown]

Arbitrary key-value metadata to associate with this frame, at most 8192 bytes when serialized. If a violation is detected on this frame, the metadata is echoed back verbatim in the live_video.violation_detected webhook.

ReturnsExpand Collapse

requestId: string

status: "accepted"

Add frame

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,
          "frame_id": "YOUR_FRAME_ID",
          "metadata": {
            "vendor_gateway_id": "bar"
          }
        }'

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

Returns Examples

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