AIOZ Stream Developer Guide: API, SDKs, and Webhooks

Most video APIs make you choose between a quick embed widget and a full raw API with no middle ground. AIOZ Stream's developer platform covers the whole pipeline, media upload and encoding, chapters and transcripts, playlists, webhooks, players, analytics, and live streaming, under one authentication model, with official SDKs for Go and Node.js on top of the REST API. This is an orientation to that surface: what's actually in it, how auth works, and where to start.

TL;DR:

• One REST API and two official SDKs (Go, Node.js) cover media, chapters/transcripts, playlists, webhooks, players, analytics, and live streaming.
• API keys come in two roles, full-access and upload-only, so you can delegate uploads without handing over account control.
• Production rate limits are 100 req/min for uploads, 200 for writes, 500 for reads, with 429 responses carrying the standard rate-limit headers.
• The docs are also published in an AI-coding-assistant-readable format (llms.txt), a detail worth knowing about even before it gets its own dedicated walkthrough.

What the API actually covers

The REST API is organized around a small set of resources rather than one monolithic endpoint. Media objects (video and audio) handle upload, encoding, and lifecycle. Media chapters and media transcripts attach VTT-based navigation and captions, one file per language, with transcripts specifically supporting a "default" flag so you can control which language a player loads first. Playlists group videos with custom ordering, implemented as a linked list under the hood, each item pointing at the next and previous one, so reordering is a pointer update rather than resending the whole list. Webhooks push encoding lifecycle events instead of making you poll. Players let you create and reuse branded themes. Analytics splits into three endpoint families, aggregated metrics, a breakdown by dimension like country or device, and a timeseries view, covering watch time, retention, and impressions. A separate live-streamings resource group covers stream sessions and real-time health stats. Everything sits behind the same API key and the same AIOZ token wallet used for billing.

Authentication: API keys and their two roles

An API key is either full-access or upload-only. Full-access can manage the account, including creating and revoking other keys; upload-only can add video but can't touch account settings or existing content. That split matters the moment you need to delegate uploads, say, to a CMS integration or a third-party contributor, without handing that integration the ability to delete videos or mint new keys of its own. Keys can also carry an expiration, which is the other half of not leaving a long-lived, full-access credential sitting in a config file indefinitely.

SDKs: Go and Node.js

Both official SDKs, github.com/AIOZNetwork/aioz-stream-go-client and @aiozstream/nodejs-client on npm, expose the same shape: typed sub-clients for API keys, players, playlists, video, video chapters, and webhooks, built from one credential pair. The Node.js client additionally handles chunked upload and pagination for you and exposes analytics methods directly, and both SDKs describe themselves the same way in their own docs: video infrastructure for product builders, meant for both on-demand and low-latency live features. Reaching for an SDK instead of raw HTTP mostly buys you that typing and the chunked-upload handling, not different functionality underneath.

Rate limits and webhooks: designing for production

Production-tier rate limits are 100 requests/minute for uploads, 200/minute for writes, and 500/minute for reads; a 429 response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Retry-After headers, so a client can back off correctly instead of guessing. Webhooks cover the encoding lifecycle (started, partial progress, finished, failed, plus file-received) so you don't have to poll a video's status after upload. One thing worth knowing before you build a handler: the raw API reference lists these events in snake_case (encoding_started) while the companion conceptual guide lists the same events in dot notation (encoding.started). Verify the exact field name against a live webhook payload rather than trusting either doc page's spelling by itself.

What a first integration typically looks like

Most integrations follow the same shape regardless of which SDK or raw HTTP you use: create a video object with metadata, upload the file, then register a webhook for the encoding-finished event instead of polling the video's status in a loop. Once that webhook fires, the video is ready, and the same API key that created it can fetch the player embed info to show it on a page. Chapters, transcripts, or a custom player theme get attached after that, since none of them block playback, they just enrich it. The pattern holds whether you're uploading one video from a script or building a CMS integration that uploads hundreds a day; what changes at scale is mostly which API key role and rate-limit budget you're planning around, not the shape of the flow itself.

Built to be read by AI coding assistants too

Alongside the human-facing docs, AIOZ Stream publishes an llms.txt-standard set of machine-readable reference files, an index file plus a fully concatenated version, meant to be attached directly to Claude, Cursor, ChatGPT, or Copilot so those tools can scaffold working code against the real API surface instead of guessing at it. That's enough of a distinct feature to deserve its own walkthrough later; the short version here is that it exists and is meant to be used, not just published as a formality.

Frequently Asked Questions

Do I need to use the Go or Node.js SDK, or can I call the REST API directly?
Either works. The SDKs add typing and handle chunked upload and pagination for you; the underlying REST API is the same either way.

What's the difference between a full-access and upload-only API key?
Upload-only can add video content but can't manage account settings, existing content, or other API keys. Full-access can do all of that, including creating and revoking keys.

What happens if I exceed the rate limit?
You get a 429 response with X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Retry-After headers telling you the limit and when to retry.

Are webhook event names snake_case or dot notation?
Both appear across AIOZ Stream's own documentation depending on which page you're reading. Verify against a live webhook payload before hardcoding a field name.

Is the llms.txt documentation a real product feature or just marketing?
It's a real, functioning set of machine-readable reference files meant to be attached to an AI coding assistant, not a one-off marketing page.

Related Reading

• AIOZ Stream Explained: what the API is actually orchestrating between ingest and playback
• AIOZ Stream Pricing Explained: how usage through this API gets billed
• One DePIN, Three Workloads: why one API can cover storage, compute, and delivery at once

References

• AIOZ Stream API keys documentation: the official source for the full-access/upload-only role split described above
• AIOZ Stream Node.js SDK documentation: the official source for the SDK's client structure and capabilities