How to Embed the AIOZ Stream Player on Your Website

Uploading a video to AIOZ Stream is the easy part. Getting it to actually show up, playable, on your own site is where most people get stuck for longer than they should.

TL;DR:

• The fastest working embed is a single iframe pointed at embed.aiozstream.network/vod/hls/{video_id}
• The video ID comes from your upload response or the dashboard's video list, not from the player itself
• Player look and feel (colors, thumbnail height, track height) is set once as a named Player Session in the dashboard and applied per video, not passed as URL query parameters
• Wrap the iframe in a CSS aspect-ratio container so it resizes correctly instead of using fixed pixel dimensions
• allowfullscreen and frameborder="0" are both required attributes, not optional polish

The fastest way: a single iframe

AIOZ Stream's player embed is deliberately simple. There's no JavaScript SDK to install and no build step. You drop an iframe into your HTML and point it at the embed domain with your video's ID in the path:

<iframe
  src="https://embed.aiozstream.network/vod/hls/video_id"
  width="100%"
  frameborder="0"
  scrolling="no"
  allowfullscreen="true"
></iframe>

Replace video_id with the actual ID of the video you uploaded. That's the entire embed. No API key goes in this URL, no signed token, just the ID. If you can paste an HTML snippet into a page (a CMS, a static site, a React component's JSX), you can embed the player.

Where the video ID actually comes from

This trips people up more than the embed code itself: the player doesn't generate or look up a video ID for you. You get it from whichever path you used to upload the video in the first place.

If you uploaded through the AIOZ Stream dashboard, the ID sits next to the video in your video list, ready to copy. If you uploaded through the Developer API, the ID comes back in the upload response itself, and you'd typically store it against whatever record in your own database represents that video (a course lesson, a product demo, a user-generated clip). The upload endpoint walkthrough covers that flow end to end if you're building the upload side yourself rather than using the dashboard.

Either way, treat the video ID as a normal piece of application data, not a secret. It only becomes useful in combination with the embed URL, and the embed itself doesn't require authentication to play a public video. That's worth internalizing early if you're storing video IDs in a database alongside other application records: they don't need the same access controls a real credential would, since knowing a video's ID doesn't grant any capability beyond viewing that one already-public video.

Making the embed responsive

The docs set width="100%" on the iframe, but width alone doesn't give you a correctly proportioned player. Without a height rule, the iframe either collapses to nothing or falls back to a default height that doesn't match your video's aspect ratio. The fix isn't AIOZ-specific, it's the standard way to make any iframe responsive: wrap it in a container sized with the CSS aspect-ratio property instead of hardcoding pixel dimensions.

<div style="aspect-ratio: 16 / 9; width: 100%;">
  <iframe
    src="https://embed.aiozstream.network/vod/hls/video_id"
    width="100%"
    height="100%"
    frameborder="0"
    scrolling="no"
    allowfullscreen="true"
  ></iframe>
</div>

Set aspect-ratio to match your source video (16/9 for most widescreen content, 9/16 if you're embedding vertical video). This way the player scales cleanly from a phone screen to a desktop layout without a layout-shift jump when the page first loads, which is the part fixed-pixel embeds usually get wrong. Older browser support for aspect-ratio is solid enough at this point that a padding-percentage hack (the classic "padding-top: 56.25%" trick) isn't necessary anymore for anything targeting a reasonably current browser; reach for that fallback only if your actual traffic data shows a meaningful share of visitors on browsers that predate it.

Customizing how it looks: Player Sessions, not URL parameters

If you've embedded video from other providers before, you might expect to control the player's look with query string parameters, something like ?color=ff0000&autoplay=1 tacked onto the src URL. AIOZ Stream doesn't work that way, and it's worth knowing before you go looking for parameters that don't exist.

Instead, you create a Player Session in the AIOZ Stream dashboard, a named configuration with fields for Main Color, Background Color, Track Color, Text Color, Caption Color, Thumb Height, and Track Height. Once that session exists, you apply it to a video from the video's own settings page by picking it from a dropdown. The player theme is now attached to the video, not to the embed code, so the same iframe snippet works everywhere you paste it and the appearance stays consistent without touching HTML.

The practical upside: you can reskin every video tied to a given Player Session in one place (say, to match a rebrand) without editing a single embed on your site. The tradeoff is you can't give two embeds of the same video different colors on two different pages purely through the URL, since the theme lives with the video, not the link. If you need that, you'd need two separate uploads or a proxy layer of your own on top. For more on how the player behaves once it's actually streaming, see the breakdown of how it adapts bitrate during playback.

A complete, working example

Here's a minimal HTML page that puts the responsive wrapper and the embed together, ready to paste and adjust:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>My Video</title>
</head>
<body>
  <div style="max-width: 900px; margin: 0 auto;">
    <div style="aspect-ratio: 16 / 9; width: 100%;">
      <iframe
        src="https://embed.aiozstream.network/vod/hls/video_id"
        width="100%"
        height="100%"
        frameborder="0"
        scrolling="no"
        allowfullscreen="true"
      ></iframe>
    </div>
  </div>
</body>
</html>

The outer max-width div is optional, it just keeps the player from stretching edge to edge on a wide desktop monitor. Drop this into any static page, CMS embed block, or component and swap in your own video ID.

Common mistakes worth checking first

Most embed problems trace back to one of a handful of causes, roughly in order of how often they actually show up.

Leaving out allowfullscreen is the most common one. Without it, viewers lose the fullscreen control entirely, and it's easy to miss since the player still looks fine at first glance. It's a required attribute on the iframe tag itself, not styling polish.

A hardcoded pixel height is the second. Something like height="360" looks fine on whatever screen you tested it on and wrong everywhere else. Use the aspect-ratio wrapper from the previous section instead of a fixed number.

Pasting the wrong ID into the embed path also happens more than you'd expect, usually a Player Session ID, an API key, or a webhook ID where the actual video ID should go. They're not interchangeable, and a wrong ID here typically just renders a blank or error state rather than a helpful message telling you what went wrong.

People also assume URL parameters control the player's appearance, since that's how several other video platforms work. AIOZ Stream doesn't. If the player looks wrong, check the Player Session applied to that specific video in the dashboard, not the embed code.

Last one: embedding a video before it's finished processing. A freshly uploaded video needs to finish transcoding before the embed has anything to play, so check the video's status in the dashboard or via the API before assuming the embed code itself is broken.

FAQ

Do I need an API key to embed a video?
No. The embed URL itself doesn't require authentication for a public video. API keys matter for uploading, managing, and querying videos through the Developer API, not for playing one back through the iframe.

Can I embed the same video with different colors on two different pages?
Not through the embed code alone, since the Player Session (and its colors) is attached to the video, not the URL. You'd need to duplicate the video under a different upload or apply a different Player Session to each and accept that both embeds everywhere else will share whichever session is currently applied.

Is there a JavaScript SDK for the player, instead of an iframe?
Not as a separate embedding SDK. The documented embed method is the iframe itself. AIOZ Stream does publish Node.js and Go SDKs, but those are for server-side API calls (uploads, video management), not for controlling playback in the browser.

Why is my embed showing a blank player?
Check three things in order: that the video ID in the src URL is correct, that the video has finished processing rather than still transcoding, and that you haven't accidentally pasted a Player Session ID or API key into the video ID slot.

Does the iframe embed work the same for both HLS and MPEG-DASH playback?
Yes, the embed URL itself doesn't change. Which manifest format the player actually requests is handled behind the scenes based on the viewer's browser, covered in more detail in the HLS vs MPEG-DASH breakdown.

Can I restrict which sites are allowed to embed my video?
That's not covered in AIOZ Stream's current player documentation. If domain restriction matters for your use case, treat it as an open question to raise with AIOZ directly rather than something to assume is configurable today.

Related reading

• AIOZ Stream Video Player: Features and Customization Guide
• AIOZ Stream Explained: Decentralized Video Infrastructure from Ingest to Playback
• HLS vs MPEG-DASH: How the AIOZ Stream Player Actually Adapts
• AIOZ Stream Developer Guide: API, SDKs, and Webhooks
• Building a Video Upload Endpoint with Cursor or Claude Code
• AIOZ Stream Pricing Explained: A Full Cost Breakdown

For background on the general technique used above, MDN has a solid reference on the CSS aspect-ratio property.