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, which is worth noting as a design choice, not just a convenience: a media object, a webhook subscription, and an analytics query all authenticate the same way, so there's no separate credential type or account-linking step to manage per resource the way there sometimes is when a platform's feature set grew by bolting on separate products over time.

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. Go and Node.js cover the two most common integration shapes for this kind of platform, a backend service coordinating uploads and webhooks (Node.js) and infrastructure-adjacent tooling that already leans on Go for its own services (Go). If your stack is in a different language entirely, the REST API underneath both SDKs is the same one they're built on, so nothing about the platform's capability is actually gated behind having an SDK in your specific language, it's a convenience layer, not a requirement.

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. That naming follows the de facto convention most APIs converged on before a formal standard existed; there's now an active IETF draft standard for RateLimit header fields aiming to formalize the same three pieces of information (limit, remaining, reset) under a standardized, non-prefixed name, which is worth knowing about if you're building a client meant to work against multiple APIs' rate-limit conventions, not just this one. 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.

Building the handler itself, treat webhook delivery as at-least-once, not exactly-once, which is standard practice across virtually every webhook system, not something specific to AIOZ Stream. Stripe's own webhook guidance, one of the most widely referenced treatments of this problem, recommends making handlers idempotent by checking whether an event's ID has already been processed before acting on it again, since network retries or a slow response on your end can cause the same event to arrive more than once. The same principle applies here: an encoding_finished event landing twice shouldn't double-process a video on your side just because the delivery wasn't perfectly exactly-once.

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, which means they can be added in a follow-up call whenever they're ready rather than needing to be bundled into the initial upload request. 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.

Should a webhook handler assume each event only arrives once?
No. Treat delivery as at-least-once, the standard assumption across virtually every webhook system, and make the handler idempotent by checking whether an event ID has already been processed before acting on it, rather than assuming a duplicate delivery can't happen.

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
• Getting Started with the AIOZ Stream Node.js SDK: a full worked walkthrough of the Node.js client specifically
• API Keys: Upload-Only vs Full-Access Roles: the full detail behind the key-role split summarized above

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