AIOZ Stream API
Media
Video

Video

This section covers the Video API endpoints for managing video content.

Create video object

This endpoint is used to programmatically create a video object.

The request body when creating a video will look like this:

{
  "type": "video",
  "title": "string",
  "description": "string",
  "is_public": true,
  "metadata": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "qualities": [
    {
      "resolution": "string",
      "type": "string",
      "container_type": "string",
      "video_config": {
        "codec": "string",
        "bitrate": 0,
        "index": 0
      },
      "audio_config": {
        "bitrate": 0,
        "channels": "string",
        "codec": "string",
        "index": 0,
        "language": "string",
        "sample_rate": 0
      }
    }
  ],
  "tags": ["string"]
}

The type field is required and must be set to video. Requests that omit type will be rejected.

For example, this would be a simplified body for creating a video:

{
  "title": "My Video Title",
  "type": "video"
}

Advanced Custom Encoding Configuration

For advanced users, you can create detailed, custom encoding configurations to precisely control the video and audio quality outputs.

Configuration Structure

The qualities field is an array containing one or more objects, each defining specific encoding parameters.

Fields available for each quality object:

FieldTypeDescriptionSupported ValuesExamples
resolutionstringResolution of the video output. Required if video_config is specified."240p", "360p", "480p", "720p", "1080p", "1440p", "2160p", "4320p""360p", "1080p"
typestringThe streaming format."hls", "dash""hls"
container_typestringFor hls, container_type supports mpegts or mp4.
For dash, container_type supports fmp4. Must match the type field.		hls: "mpegts", "mp4",
dash: "fmp4"		"mpegts"
video_configobject(Optional) Video encoding parameters.See details belowSee details below
audio_configobject(Optional) Audio encoding parameters.See details belowSee details below

Video Config Details

This object lets you configure specific video encoding parameters:

FieldTypeDescriptionSupported ValuesExample
codecstringCodec used for video encoding"h264", "h265""h264"
bitratenumberTarget video bitrate (bits/sec)Positive integer3000000 (~3Mbps)
indexnumberVideo track index from input fileUsually 0 (default track)0

NOTE: On Apple platforms (Safari, iOS, tvOS), HLS supports HEVC/H.265 only when segments are fMP4/CMAF. HEVC in MPEG-TS segments is not supported. H.264/AVC works with both MPEG-TS and fMP4/CMAF.

Video resolutions and their corresponding dimensions and bitrate ranges are as follows:

ResolutionDimensionsMax Bitrate (bps)
240p426 × 240700,000 bps
360p640 × 3601,200,000 bps
480p854 × 4802,000,000 bps
720p1280 × 720 (HD)4,000,000 bps
1080p1920 × 1080 (Full HD)6,000,000 bps
1440p2560 × 1440 (2K/QHD)12,000,000 bps
2160p3840 × 2160 (4K/UHD)30,000,000 bps
4320p7680 × 4320 (8K/UHD-2)60,000,000 bps

Audio Config Details

This object configures specific audio encoding parameters:

FieldTypeDescriptionSupported ValuesExample
codecstringCodec for audio encoding"aac""aac"
bitratenumberTarget audio bitrate (bits/sec)Positive integer128000 (~128kbps)
channelsnumberNumber of audio channels1 (mono), 2 (stereo), 3 (2.1/3), 4 (Quad/4.0), 5 (5.0), 6 (5.1)2
sample_ratenumberAudio sampling rate (Hz)Typically 44100 or 4800044100
languagestringAudio track language (BCP 47 format)"en", "es", "ja""en"
indexnumberAudio track index from input fileUsually 0 (default track)0

Recommended Audio Bitrates

Audio QualityBitrate (bps)
Standard (Stereo)128,000 – 192,000 bps
High Quality192,000 – 256,000 bps

Sample_rate only accepts the following values.

Sample Rate (Hz)Usage & Quality
8,000Telephone quality (lowest)
11,025Low-quality audio for voice recordings
16,000Suitable for clear speech recordings
22,050Medium-quality voice and music
32,000Higher-quality audio, common for streaming voice
44,100CD-quality audio (standard music/audio)
48,000Professional audio & streaming standard
88,200High-definition audio
96,000Studio-grade audio quality

Important Notes

  • video_config and audio_config are optional:

    • If neither is specified, the server applies default encoding values for both audio and video.
    • If only video_config is specified, the encoded result may include only video.
    • If video_config's resolution is higher than its source resolution, that quality will be ignored.

  • Track Index (index):

    • Specifies which track from the original input file to encode. Typically, this is 0 for single-track media.
    • Ensure correct indexing when dealing with multi-track input sources.

  • On Apple platforms (Safari, iOS, tvOS), HLS supports HEVC/H.265 only when segments are fMP4/CMAF. HEVC in MPEG-TS segments is not supported. H.264/AVC works with both MPEG-TS and fMP4/CMAF.

  • Supported codecs:

    • Video codecs: Only H.264 and H.265 are currently supported. (H.264 maximum resolution is 4K and H.265 is 8K)
    • Audio codecs: Only AAC is supported.

Example Configuration

Video with Multiple Quality Settings

{
  "title": "My Video",
  "type": "video",
  "qualities": [
    {
      "resolution": "1080p",
      "type": "hls",
      "container_type": "mpegts",
      "video_config": {
        "codec": "h264",
        "bitrate": 5000000,
        "index": 0
      },
      "audio_config": {
        "codec": "aac",
        "bitrate": 192000,
        "channels": "2",
        "sample_rate": 48000,
        "language": "en",
        "index": 0
      }
    },
    {
      "resolution": "720p",
      "type": "hls",
      "container_type": "mpegts",
      "video_config": {
        "codec": "h264",
        "bitrate": 3000000,
        "index": 0
      },
      "audio_config": {
        "codec": "aac",
        "bitrate": 128000,
        "channels": "2",
        "sample_rate": 44100,
        "language": "en",
        "index": 0
      }
    }
  ]
}
POSThttps://api.aiozstream.network/api/media/create

Headers

Authorization Bearer your_access_token_here
or
stream-public-key your_public_key_here
stream-secret-key your_secret_key_here

Body

title* Video's title
type Type should be "video"
description Video's description
is_public Video public's status
metadata Video's metadata (ex: {"genre":"rock"})
tags Video's metadata (ex: {"genre":"rock"})
qualities Video's transcoded qualities

Response

201: Created
{
    "data": {
          "id": "video_id",
          "user_id": "user_id",
          "type": "video",
          "title": "video's title (required)",
          "description": "",
          "metadata": null,
          "tags": null,
          "qualities": [
              {
                  "name": "360p",
                  "status": "done",
                  "type": "hls"
              },
              {
                  "name": "720p",
                  "status": "done",
                  "type": "hls"
              },
              {
                  "name": "1080p",
                  "status": "done",
                  "type": "hls"
              }
          ],
          "captions": null,
          "chapters": null,
          "player_theme": null,
          "duration": 283.492426,
          "size": 63109470,
          "is_mp4": false,
          "is_public": true,
          "status": "done",
          "created_at": "created_at",
          "updated_at": "updated_at",
          "assets": {
              "source_url": "https://api.aiozstream.network/api/media/video_id/source",
              "thumbnail_url": "https://api.aiozstream.network/api/media/video_id/thumbnail?resolution=original",
              "hls_url": "https://api.aiozstream.network/api/media/video_id/m3u8",
              "hls_iframe": "\u003ciframe src=\"https://embed.aiozstream.network/vod/hls/video_id\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"true\"\u003e\u003c/iframe\u003e",
              "hls_player_url": "https://embed.aiozstream.network/vod/hls/video_id",
              "dash_url": "https://api.aiozstream.network/api/media/video_id/manifest",
              "dash_iframe": "\u003ciframe src=\"https://embed.aiozstream.network/vod/dash/video_id\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"true\"\u003e\u003c/iframe\u003e",
              "dash_player_url": "https://embed.aiozstream.network/vod/dash/video_id",
              "mp4_url": "https://api.aiozstream.network/api/media/video_id/mp4"
          },
          "player_theme_id": ""
      },
    "status": "success"
}
curl --location https://api.aiozstream.network/api/media/create \
--header 'Authorization: Bearer your_access_token_here' \
# --header 'stream-public-key: your_public_key_here' \
# --header 'stream-secret-key: your_secret_key_here' \
--header 'Content-Type: application/json' \
--data '{
"title": "My Video Title",
"type": "video"
}'

List videos

This endpoint lists and searches videos with multiple filters.

POSThttps://api.aiozstream.network/api/media

Headers

Authorization Bearer your_access_token_here
or
stream-public-key your_public_key_here
stream-secret-key your_secret_key_here

Body

offset The number of records to skip before starting to return the results (default: 0)
limit The maximum number of records to return in a query (default: 25, max: 100)
sort_by The field or property to sort by (sort_by defaults to created_at and supports: created_at, updated_at, title, size)
order_by The way record should be arranged (orderBy defaults to asc and supports: asc, desc)
type Filter by media type. Use video to return videos only. If omitted, the response may include other media types
tags Video's tags (ex: music,mp4)
metadata Video's metadata (ex: {"genre":"rock"})
status Video's status (allowed: new, transcoding, done, fail, deleted)
search The keyword to search in both the title and description fields

Response

200: OK
{
    "status": "success",
    "data": {
        "videos": [
            {
                "id": "video_id",
                "user_id": "user_id",
                "type": "video",
                "title": "video's title",
                "description": "",
                "metadata": null,
                "tags": null,
                "qualities": [
                    {
                        "name": "360p",
                        "status": "done",
                        "type": "hls"
                    },
                    {
                        "name": "720p",
                        "status": "done",
                        "type": "hls"
                    }
                ],
                "captions": null,
                "chapters": null,
                "player_theme": null,
                "duration": 283.492426,
                "size": 63109470,
                "is_mp4": false,
                "is_public": true,
                "status": "done",
                "created_at": "created_at",
                "updated_at": "updated_at",
                "assets": {
                    "source_url": "https://api.aiozstream.network/api/media/video_id/source",
                    "thumbnail_url": "https://api.aiozstream.network/api/media/video_id/thumbnail?resolution=original",
                    "hls_url": "https://api.aiozstream.network/api/media/video_id/m3u8",
                    "hls_iframe": "\u003ciframe src=\"https://embed.aiozstream.network/vod/hls/video_id\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"true\"\u003e\u003c/iframe\u003e",
                    "hls_player_url": "https://embed.aiozstream.network/vod/hls/video_id",
                    "dash_url": "https://api.aiozstream.network/api/media/video_id/manifest",
                    "dash_iframe": "\u003ciframe src=\"https://embed.aiozstream.network/vod/dash/video_id\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"true\"\u003e\u003c/iframe\u003e",
                    "dash_player_url": "https://embed.aiozstream.network/vod/dash/video_id",
                    "mp4_url": "https://api.aiozstream.network/api/media/video_id/mp4"
                },
                "player_theme_id": ""
            }
        ],
        "total": 1
    }
}
 
curl 'https://api.aiozstream.network/api/media' \
  -H 'authorization: Bearer your_access_token_here' \
  # --header 'stream-public-key: your_public_key_here' \
  # --header 'stream-secret-key: your_secret_key_here' \
  -H 'Content-Type: application/json' \
  --data-raw '{"limit":10,"offset":0,"sort_by":"created_at","order_by":"desc","type":"video"}' \

Get video detail

This API will show video's detail.

GEThttps://api.aiozstream.network/api/media/:video_id

Parameters

video_id The unique identifier of the video.

Headers

Authorization Bearer your_access_token_here
or
stream-public-key your_public_key_here
stream-secret-key your_secret_key_here

Response

200: OK
{
    "status": "success",
    "data": {
                "id": "video_id",
                "user_id": "user_id",
                "type": "video",
                "title": "video's title",
                "description": "",
                "metadata": null,
                "tags": null,
                "qualities": [
                    {
                        "name": "360p",
                        "status": "done",
                        "type": "hls"
                    },
                    {
                        "name": "720p",
                        "status": "done",
                        "type": "hls"
                    }
                ],
                "captions": null,
                "chapters": null,
                "player_theme": null,
                "duration": 283.492426,
                "size": 63109470,
                "is_mp4": false,
                "is_public": true,
                "status": "done",
                "created_at": "created_at",
                "updated_at": "updated_at",
                "assets": {
                    "source_url": "https://api.aiozstream.network/api/media/video_id/source",
                    "thumbnail_url": "https://api.aiozstream.network/api/media/video_id/thumbnail?resolution=original",
                    "hls_url": "https://api.aiozstream.network/api/media/video_id/m3u8",
                    "hls_iframe": "\u003ciframe src=\"https://embed.aiozstream.network/vod/hls/video_id\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"true\"\u003e\u003c/iframe\u003e",
                    "hls_player_url": "https://embed.aiozstream.network/vod/hls/video_id",
                    "dash_url": "https://api.aiozstream.network/api/media/video_id/manifest",
                    "dash_iframe": "\u003ciframe src=\"https://embed.aiozstream.network/vod/dash/video_id\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"true\"\u003e\u003c/iframe\u003e",
                    "dash_player_url": "https://embed.aiozstream.network/vod/dash/video_id",
                    "mp4_url": "https://api.aiozstream.network/api/media/video_id/mp4"
                },
                "player_theme_id": ""
    }
}
curl --location 'https://api.aiozstream.network/api/media/video_id' \
--header 'authorization: Bearer your_access_token_here'
# --header 'stream-public-key: your_public_key_here' \
# --header 'stream-secret-key: your_secret_key_here'

Calculate transcode price

Calculate the estimated transcoding cost for a video based on duration and the selected output qualities. The returned cost is in USD.

NOTE: qualities can be provided as a comma-separated list (e.g. qualities=240p,360p) or as repeated query parameters (e.g. qualities=360p&qualities=1080p). The cost covers transcoding to all requested qualities.

GEThttps://api.aiozstream.network/api/media/cost

Query

qualities Video's transcode qualities (allowed: 144p, 240p, 360p, 480p, 720p, 1080p, 1440p, 2160p)
type Type should be "video"
duration Video's duration in seconds

Headers

Authorization Bearer your_access_token_here
or
stream-public-key your_public_key_here
stream-secret-key your_secret_key_here

Response

200: OK
{
    "status": "success",
    "data": {
      "price": 1.23,
      "is_enough": true
    }
}
curl --location 'https://api.aiozstream.network/api/media/cost?duration=60&type=video&qualities=360p%2C1080p' \
--header 'Authorization: Bearer your_access_token_here'
# --header 'stream-public-key: your_public_key_here' \
# --header 'stream-secret-key: your_secret_key_here'

Upload video part

This API allows you to upload your video or a part of it. If your file size is larger than the chunk size (chunk size: 50MB – 200MB), split the file into parts and upload each one sequentially.

POSThttps://api.aiozstream.network/api/media/:video_id/part

Parameters

video_id The unique identifier of the video.

Headers

Authorization Bearer your_access_token_here
or
stream-public-key your_public_key_here
stream-secret-key your_secret_key_here
Content-Range bytes {start_pos}-{end_pos}/{file_size}

Body

file* The video file (or chunk) to upload.
index* The index of the part to upload.
hash* MD5 hash of the part's content.

Response

200: OK
{"status":"success","message":"Upload part successfully."}
curl --location 'https://api.aiozstream.network/api/media/video_id/part' \
--header 'Authorization: Bearer your_access_token_here' \
--header 'Content-Range: bytes 0-49999999/100000000' \
--form 'hash="part_content_md5_hash"' \
--form 'index="0"' \
--form 'file=@"/path/to/file"'

Upload video completed

This API notifies the server that the video upload process is done. Call this endpoint after all parts have been uploaded successfully.

GEThttps://api.aiozstream.network/api/media/:video_id/complete

Parameters

video_id The unique identifier of the video.

Headers

Authorization Bearer your_access_token_here
or
stream-public-key your_public_key_here
stream-secret-key your_secret_key_here

Response

200: OK
{"status":"success","message":"Upload completed successfully."}
curl --location 'https://api.aiozstream.network/api/media/video_id/complete' \
--header 'Authorization: Bearer your_access_token_here'

Update video info

This API allows you to update video's information.

PATCHhttps://api.aiozstream.network/api/media/:video_id

Parameters

video_id The unique identifier of the video.

Headers

Authorization Bearer your_access_token_here
or
stream-public-key your_public_key_here
stream-secret-key your_secret_key_here

Body

title Video's title
description Video's description
metadata Pairs of key and value
tags Video's tags
is_public Whether the video is publicly available or not (Default: true).
player_theme_id The unique Id for the player you want to associate with your video.

Response

200: OK
{"status":"success","message":"Update video info successfully."}
curl --location --request PATCH 'https://api.aiozstream.network/api/media/video_id' \
--header 'Authorization: Bearer your_access_token_here' \
# --header 'stream-public-key: your_public_key_here' \
# --header 'stream-secret-key: your_secret_key_here' \
--header 'Content-Type: application/json' \
--data '{
  "description": "string",
  "player_theme_id": "string",
  "is_public": true,
  "metadata": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "tags": [
    "string"
  ],
  "title": "string"
}'

Upload video thumbnail

This API allows you to upload a thumbnail for a video.

POSThttps://api.aiozstream.network/api/media/:video_id/thumbnail

Parameters

video_id The unique identifier of the video.

Headers

Authorization Bearer your_access_token_here
or
stream-public-key your_public_key_here
stream-secret-key your_secret_key_here

Body

file* The thumbnail file to upload. (allowed: .png,.jpg)

Response

200: OK
  {"status":"success","message":"Upload thumbnail successfully."}
curl --location 'https://api.aiozstream.network/api/media/video_id/thumbnail' \
--header 'Authorization: Bearer your_access_token_here' \
# --header 'stream-public-key: your_public_key_here' \
# --header 'stream-secret-key: your_secret_key_here' \
--form 'file=@"/path/to/file"'

Delete video

Deletes a video object by ID.

DELETEhttps://api.aiozstream.network/api/media/:video_id

Parameters

video_id The unique identifier of the video.

Headers

Authorization Bearer your_access_token_here
or
stream-public-key your_public_key_here
stream-secret-key your_secret_key_here

Response

200: OK
{"status":"success","message":"Video deleted successfully."}
curl --location --request DELETE 'https://api.aiozstream.network/api/media/video_id' \
--header 'Authorization: Bearer your_access_token_here'
# --header 'stream-public-key: your_public_key_here' \
# --header 'stream-secret-key: your_secret_key_here'
PreviousPlayer setup and customizationNextAudio