NeonDB Media API — Developer Portal

Authentication

REQUIRED

All API requests must include a valid API key. Pass it as a Bearer token in the Authorization header, or as the X-Playback-Token header for media session requests.

curl

curl https://api.neondbmain.ru/api/v2/media?offset=0 \
  -H "Authorization: Bearer ndb_live_4kXp92mNqR..." \
  -H "Cookie: media_sid=sess_abc123" \
  -H "X-Playback-Token: pt_eyJhbGci..."

javascript

const res = await fetch('https://api.neondbmain.ru/api/v2/media?offset=0', {
  headers: {
    'Authorization': 'Bearer ndb_live_4kXp92mNqR...',
    'Cookie': 'media_sid=sess_abc123',
    'X-Playback-Token': 'pt_eyJhbGci...'
  }
});
const data = await res.json();

python

import httpx

res = httpx.get(
    "https://api.neondbmain.ru/api/v2/media",
    params={"offset": 0},
    headers={
        "Authorization": "Bearer ndb_live_4kXp92mNqR...",
        "X-Playback-Token": "pt_eyJhbGci...",
    },
    cookies={"media_sid": "sess_abc123"}
)

go

req, _ := http.NewRequest("GET",
    "https://api.neondbmain.ru/api/v2/media?offset=0", nil)
req.Header.Set("Authorization", "Bearer ndb_live_4kXp92mNqR...")
req.Header.Set("X-Playback-Token", "pt_eyJhbGci...")
req.AddCookie(&http.Cookie{Name: "media_sid", Value: "sess_abc123"})

🔒 Bearer Token

Standard API key authentication for all server-side requests. Keys are prefixed with ndb_live_ (production) or ndb_test_ (sandbox).

🎬 Playback Token

Short-lived token for media session polling. Scoped to a single session. Expires after 3600s. Renew via POST /v2/media.

Media Sessions

4 ENDPOINTS

GET

/api/v2/media

Poll media session state. Returns current session metadata, playback position, and buffering status.

streamingsessionreal-time

▶

Query Parameters

Parameter	Type	Description
offsetrequired	integer	Sequence offset for ordered delivery. Monotonically increasing integer starting at 0.
limitoptional	integer	Max events to return. Default: 50, max: 500.
formatoptional	string	Response format: `json` · `msgpack` · `cbor`

Request Headers

Header	Value	Description
Cookierequired	media_sid=<token>	Session identifier. Set by POST /v2/media on creation.
X-Playback-Tokenrequired	string	Short-lived playback token. Expires after 3600s.
Acceptoptional	application/json	Preferred response media type.

json — 200 OK

{
  "session_id": "sess_4kXp92mNqR",
  "status": "active",
  "offset": 0,
  "events": [{
    "type": "buffer_update",
    "timestamp": 1748304000,
    "payload": { "buffered_ms": 4200, "bitrate_kbps": 3840, "quality": "1080p" }
  }],
  "next_offset": 1,
  "ttl": 3600
}

json — 400 Bad Request

{
  "error": "ERR_INVALID_OFFSET",
  "message": "offset must be a non-negative integer",
  "request_id": "req_7fGh3kLmNp"
}

json — 401 Unauthorized

{
  "error": "ERR_SESSION_EXPIRED",
  "message": "X-Playback-Token has expired. Refresh via POST /v2/media",
  "expires_at": 1748300400
}

json — 429 Too Many Requests

{
  "error": "ERR_RATE_EXCEEDED",
  "message": "Rate limit exceeded",
  "retry_after": 12
}

Try it

offset

X-Playback-Token

media_sid cookie

response

POST

/api/v2/media

Create a new media session. Returns session credentials and initial playback token.

sessioncreatedrm

▶

Request Body

Field	Type	Description
asset_idrequired	string	Unique identifier of the media asset to stream.
qualityoptional	string	Initial preset: auto · 360p · 720p · 1080p · 4k
drmoptional	object	DRM config. Supports Widevine, FairPlay, PlayReady.

json — request body

{
  "asset_id": "asset_7fGh3kLmNp",
  "quality": "auto",
  "drm": { "scheme": "widevine", "license_url": "https://drm.neondbmain.ru/license" }
}

json — 201 Created

{
  "session_id": "sess_4kXp92mNqR",
  "playback_token": "pt_eyJhbGciOiJIUzI1NiJ9...",
  "expires_at": 1748307600,
  "set_cookie": "media_sid=sess_4kXp92mNqR; HttpOnly; Secure; SameSite=None"
}

json — 400

{ "error": "ERR_ASSET_NOT_FOUND", "message": "asset_id does not exist" }

PUT

/api/v2/media/{session_id}

Update session parameters. Adjust quality, seek position, or playback rate mid-stream.

sessionupdateseek

▶

Path Parameters

Parameter	Type	Description
session_idrequired	string	Active session identifier from POST /v2/media response.

Request Body

Field	Type	Description
qualityoptional	string	New quality preset. Applied at next segment boundary.
seek_msoptional	integer	Seek to position in milliseconds.
playback_rateoptional	float	Playback speed multiplier. Range: 0.25–4.0.

json — request body

{ "quality": "720p", "seek_ms": 142000, "playback_rate": 1.5 }

DEL

/api/v2/media/{session_id}

Terminate a media session and release all associated server resources.

sessioncleanup

▶

Gracefully terminates the session. Buffered data is flushed, DRM licenses are revoked. Returns 204 No Content on success.

204 No Content

// Empty response body

json — 404

{ "error": "ERR_SESSION_NOT_FOUND", "message": "Session does not exist or already terminated" }

Streaming

HLS · DASH · CMAF

GET/v2/stream

Chunked streaming endpoint. Long-poll connection, server pushes data frames. Compatible with SSE clients.

GET/v2/segments

Download individual media segments. Supports byte-range requests. Returns binary MPEG-TS or fMP4.

GET/v2/manifest

Adaptive bitrate manifest. Returns HLS .m3u8 or MPEG-DASH .mpd depending on Accept header.

Rate Limits

Applied per API key on a rolling 60-second window. Exceeding limits returns 429 Too Many Requests with a Retry-After header.

Plan	Requests / min	Concurrent sessions	Bandwidth
Free	60	2	10 GB/mo
Pro	1,200	50	1 TB/mo
Enterprise	unlimited	unlimited	custom

Error Codes

Code	HTTP	Description	Resolution
ERR_SESSION_EXPIRED	401	Playback token expired.	Refresh via POST /v2/media
ERR_INVALID_OFFSET	400	Offset out of bounds.	Reset offset to 0
ERR_SESSION_NOT_FOUND	404	Session terminated.	Create new session
ERR_RATE_EXCEEDED	429	Rate limit hit.	Check Retry-After header
ERR_ASSET_UNAVAILABLE	503	Asset temporarily unavailable.	Retry with backoff
ERR_DRM_DENIED	403	DRM license denied.	Check entitlements

SDKs & Libraries

JavaScript / TypeScript

npm install @neondb/media

Full TypeScript types. Tree-shakeable. Browser + Node.js + Edge runtimes.

v3.1.4ESM

Python

pip install neondb-media

Async-first. asyncio + httpx. Python 3.10+.

v2.0.1

Go

go get neondbmain.ru/media

Zero dependencies. Context-aware. Go 1.21+.

v1.4.0

Changelog

2026-05-12

NEWv2.4.1 — xPadding obfuscation

Tokenish padding for reduced fingerprinting on constrained networks. Configurable via extra.xPaddingMethod.
2026-04-03

IMPROVEDv2.4.0 — xmux multiplexing

Session multiplexing now supports up to 16 concurrent streams per connection. Connection overhead reduced by ~40%.
2026-02-18

NEWv2.3.0 — Adaptive bitrate via polling

GET /v2/media now returns ABR ladder recommendations based on observed throughput metrics.
2025-11-30

DEPRECATEDv1 endpoints sunset

/api/v1/* endpoints will be removed on 2026-06-01. See migration guide.

Sign in to NeonDB

Get API Key

Your API Key

System Status

NeonDB Media APIReference

🔒 Bearer Token

🎬 Playback Token

GET/v2/stream

GET/v2/segments

GET/v2/manifest

JavaScript / TypeScript

Python

Go

NEWv2.4.1 — xPadding obfuscation

IMPROVEDv2.4.0 — xmux multiplexing

NEWv2.3.0 — Adaptive bitrate via polling

DEPRECATEDv1 endpoints sunset

NeonDB Media API
Reference