Import an M3U8 HLS Video to AIOZ Stream Without Re-Encoding

AIOZ Stream can import an existing HLS video from its M3U8 master playlist URL without re-encoding it. You pass the URL as source_url to POST /api/media/create, and the service copies every rendition and segment byte for byte. You get exactly the variants in your manifest.

Most platforms handle migration differently: you re-upload your source files and they re-encode them from scratch. That works, but it throws away encoding decisions you already made and paid for.

TL;DR:

• The industry generally splits migration into two approaches: "re-ingest from masters" (upload source files, re-encode) or "asset transfer" (copy existing renditions as-is). AIOZ Stream's new import feature is the second kind.
• One API call, POST /media/create with a source_url pointing to an HLS master playlist, and AIOZ Stream downloads every variant and segment and copies them byte-for-byte: "nothing is re-encoded. The qualities you get are exactly the variants listed in your source manifest."
• Billing reflects that directly: imported videos incur storage costs only, no transcoding charges, since nothing gets re-encoded.
• Source requirements are strict and worth checking before attempting an import: VOD only (must end with #EXT-X-ENDLIST), unencrypted only, no byte-range segments, a master playlist with resolution declared on every variant, and hard limits on segment size, count, and rendition duration.
• The feature is REST-only for now, checked directly against the official Go client's generated model: CreateMediaRequest doesn't include a source_url field yet, so Go SDK users need a direct HTTP call rather than the generated client until that catches up.

Asset transfer, not re-ingest

Video-hosting migration guides generally describe two distinct approaches: re-ingesting from original source files, where the new platform re-encodes everything from zero, or transferring existing renditions directly when the formats are already compatible, preserving whatever encoding choices were already made. AIOZ Stream's new import feature is squarely the second kind. Checked directly against a real, comparable competitor's own migration documentation: Mux's guide for migrating from self-managed infrastructure describes only the first path, "call the Create Asset API with a URL pointing to your video files, Mux pulls and encodes them asynchronously," with every asset re-encoded into new renditions regardless of what encoding already existed. AIOZ Stream's import feature fills a gap Mux's own documented migration path doesn't cover: preserving an existing HLS library's exact renditions rather than re-encoding them again on arrival.

The request

A single call to the same POST /media/create endpoint already covered in the chunked upload tutorial, with a different parameter path this time: title and source_url (an HLS master playlist URL, up to 2048 characters) are required, with the usual description, type, is_public, tags, and metadata fields optional alongside it. Two fields are explicitly disallowed on an import request: qualities and watermark, which makes sense given nothing gets re-encoded, there's no transcoding step left to apply a quality ladder or a burned-in watermark to. A successful request returns 202 Accepted immediately with the new video's id and a status of transcoding, the import itself runs asynchronously from there.

Strict source requirements

The source playlist has to meet a specific, fairly strict set of conditions, worth checking against an actual source file before assuming an import will just work. It must be a finished VOD playlist ending with #EXT-X-ENDLIST, live or EVENT playlists aren't supported. It must be unencrypted, no #EXT-X-KEY beyond NONE, which rules out importing anything that was DRM-protected on its original platform, consistent with AIOZ Stream having no DRM support of its own to receive an encrypted stream into anyway. Byte-range segments (#EXT-X-BYTERANGE) aren't supported, each variant needs its own separate segment files. The master playlist itself needs RESOLUTION declared on every variant, and each variant is capped at one #EXT-X-MAP. On top of the structural rules, there are hard numeric limits: a 2 MiB playlist size cap, 200 MiB per segment, 5,000 segments per rendition, 10 renditions per video, and 4 hours per rendition, with a 30-second HTTP timeout on each fetch and a maximum of 5 redirects. A source that's encrypted, live, or byte-range-segmented needs to be re-encoded through the normal upload path instead, this import mechanism specifically handles the finished, unencrypted, standard-segment case.

Tracking an import

Same tracking options as the rest of the platform: poll GET /media/{video_id} until status flips to done (every rendition copied and playable) or fail (three retry attempts exhausted), or subscribe to the same webhook events already covered in the webhooks article, documented here in dot-notation as encoding.started, encoding.finished, and encoding.failed, the same naming variant already flagged in this series as inconsistent with the underscore-style names used in the raw API reference elsewhere. Either mechanism confirms an import the same way it confirms a normal transcode, nothing import-specific to learn beyond the source_url parameter and the stricter validation it goes through first.

The SDK gap: REST-only for now

Checked directly against the official Go client's generated model rather than assumed: CreateMediaRequest currently lists Description, IsPublic, Metadata, Qualities, SegmentDuration, Tags, Title, Type, and Watermark, no source_url or SourceUrl field anywhere. That means a project using the Go SDK can't call this feature through the generated client yet, at least not without falling back to a raw HTTP request alongside it. Worth checking the SDK's own changelog before assuming feature parity between the REST API and any given client library, new endpoints and parameters routinely ship to the API ahead of the generated clients catching up.

Frequently Asked Questions

Does AIOZ Stream's HLS import re-encode my video?
No. It's a byte-for-byte copy of the exact renditions already listed in the source master playlist, no transcoding happens.

What does an HLS import cost?
Storage costs only. Since nothing gets re-encoded, there's no transcoding charge.

Can I import a live stream or an encrypted HLS source?
No to both. The source must be a finished VOD playlist ending in #EXT-X-ENDLIST, and it must be unencrypted (no #EXT-X-KEY beyond NONE).

Can I set a custom quality ladder or watermark on an imported video?
No, both qualities and watermark are explicitly disallowed on an import request, since there's no re-encoding step to apply either to.

Does the Go SDK support this feature?
Not yet as of this writing. The generated CreateMediaRequest model has no source_url field, so Go SDK users need a direct HTTP call to use this feature.

How is this different from a normal chunked upload?
A normal upload sends your own file and AIOZ Stream re-encodes it into a fresh quality ladder. Import instead points at an already-encoded HLS playlist elsewhere and copies its exact renditions without touching them.

Related Reading

• AIOZ Stream Developer Guide: API, SDKs, and Webhooks: the hub overview for AIOZ Stream developer platform
• Chunked Video Upload Tutorial: 50-200MB Parts Explained: the re-encoding upload path this import feature is an alternative to
• Event-Driven Video Pipelines with AIOZ Stream Webhooks: the same status events used to track an import's progress
• Getting Started with the AIOZ Stream Go SDK Client: the client that doesn't yet wrap this feature's source_url parameter
• Widevine vs FairPlay vs PlayReady: DRM Explained for Video: why an encrypted source can't be imported through this path
• AIOZ Stream Pricing for Storage, Delivery and Transcoding: the storage-only billing an import incurs, with no transcoding line item
• Migrate from Amazon S3 to AIOZ Storage with rclone: moving existing files onto AIOZ Storage as they are

References

• AIOZ Stream: Import M3U8 documentation: the endpoint, validation rules, and limits quoted above
• Mux: Migrate from self-managed video infrastructure: the re-encode-on-ingest migration path contrasted above