Lumen Media API — Documentation

Quickstart

All requests are made over HTTPS to the base URL above. Responses are JSON encoded in UTF-8. The service exposes a health endpoint that requires no credentials.

# check service health
curl https://chees.skunkeu.win/v1/health

# response
{
  "status": "operational",
  "version": "1.4.2",
  "region": "eu-west"
}

Authentication

Authenticate with a bearer token issued per project. Tokens are scoped and may be restricted to specific media identifiers.

Authorization: Bearer <project_token>

Note. Session tokens used by the streaming transport are single-purpose and rotate independently of project tokens. They are embedded in the request path rather than the header to remain compatible with intermediate caches.

Media objects

A media object represents a single uploaded asset and its derived renditions.

GET/v1/catalog

Lists media objects available to the current project, most recent first.

GET/v1/media/{media_id}

Retrieves a single media object, including codec and rendition metadata.

POST/v1/media

Creates a media object and returns an ingest session for chunked upload.

DELETE/v1/media/{media_id}

Permanently removes a media object and all derived renditions.

{
  "id": "med_8f2a91c4",
  "type": "video",
  "title": "Product Overview",
  "duration_s": 184,
  "codec": "h264",
  "resolution": "1920x1080",
  "status": "ready"
}

Session streaming

The streaming transport carries media payloads for an active session. It is designed for long-lived, low-latency delivery and supports both chunked upload and continuous download over the same session identifier.

POST/v1/stream/{session_id}

Uploads media chunks for the session. Accepts a continuous request body or a sequence of discrete chunk requests. Each chunk must not exceed the configured maximum payload size.

GET/v1/stream/{session_id}

Opens a persistent downstream channel for the session. The response body is delivered incrementally as segments become available and remains open for the lifetime of the session.

Parameters

Name	Description
session_id required	Opaque session identifier returned when the session is created. Scoped to a single project and expires on close.
seq	Monotonic chunk sequence number. Used to reorder out-of-band deliveries.
Content-Type	`application/octet-stream` for binary payloads, `text/event-stream` for incremental delivery.

Keep-alive. Downstream channels are held open and may remain idle between segments. Clients should not treat idle periods as disconnects; the server emits periodic padding frames to keep intermediaries from closing the connection.

Limits

Property	Value
max_chunk_bytes	1000000
max_buffered_chunks	30
upstream_window_s	20–80
session_idle_timeout_s	300

Formats

Supported containers and codecs for transcoding targets. Retrieve the current matrix from /v1/formats.

Container	Video	Audio
mp4	h264, h265	aac, opus
webm	vp9, av1	opus
hls	h264	aac

Errors

The API uses conventional HTTP status codes. Failures return a JSON body describing the error.

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The requested endpoint does not exist."
  }
}

Status	Meaning
400	Malformed request or invalid parameters
401	Missing or invalid credentials
404	Resource or endpoint does not exist
413	Chunk exceeds max_chunk_bytes
429	Rate limit exceeded
5xx	Service error — retry with backoff

Rate limits

Requests are limited per project token. Streaming sessions are excluded from request-count limits and are governed by concurrent session quota instead.

Tier	Requests / min	Concurrent sessions
developer	120	4
standard	600	32
scale	3000	256

Media API Reference