AIOZ Stream API
Videos

Videos

Create video object

This endpoint is used to programmatically create a video object.

The request body when create a video object will look like this:

{
  "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"],
  "title": "video's title"
}

Notice the title is required.

For example, this would be a simplified body for this request:

{
  "title": "video's title"
}

Advanced Custom Encoding Configuration

For advanced users, you can create detailed, custom encoding configurations to precisely control the video and audio quality outputs. Below you'll find a comprehensive guide on configuring the qualities field in your encoding JSON.

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
resolutionstring(Conditional) Resolution of the video output. Required if video_config is specified. For audio-only configurations, this can be any descriptive string."240p", "360p", "480p", "720p", "1080p", "1440p", "2160p", "4320p", or any descriptive label for audio-only"360p", "1080p", "audio-only"
typestringThe streaming format."hls", "dash""hls"
container_typestringContainer format for the output stream. 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: apple hls only support h265 codec in mp4 container type.

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)
channelsstringNumber of audio channels"1" (mono), "2" (stereo)"2"
sample_ratenumberAudio sampling rate (Hz)Typically 44100 or 4800044100
languagestringAudio track language (ISO code)"en", "es", "jp""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

Your audio must use one of the following valid sample rates:

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 one (video_config or audio_config) is specified, the encoded result may include only video or audio, respectively.

  • 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.

  • Supported codecs:

    • Video codecs: Only h264 and h265 are currently supported.
    • Audio codecs: Only aac is supported.

  • Apple HLS supports the h265 (HEVC) codec exclusively with the mp4 container type. Using mpegts with HEVC (h265) is not supported on Apple devices and will result in playback failures.

  • Invalid configurations:

    • If the qualities array is empty or not provided, the server will return an error.
    • If both video_config's resolution is higher than its source resolution, that quality will be ignored.

Example Advanced Configuration

Here's a practical example to illustrate custom encoding settings clearly:

{
  "qualities": [
    {
      "resolution": "1080p",
      "type": "hls",
      "container_type": "mpegts",
      "video_config": {
        "codec": "h265",
        "bitrate": 5000000,
        "index": 0
      },
      "audio_config": {
        "codec": "aac",
        "bitrate": 192000,
        "channels": "2",
        "sample_rate": 48000,
        "language": "en",
        "index": 0
      }
    },
    {
      "resolution": "720p",
      "type": "dash",
      "container_type": "fmp4",
      "video_config": {
        "codec": "h264",
        "bitrate": 3000000,
        "index": 0
      }
      // No audio_config specified, video-only output for this quality.
    },
    {
      "resolution": "audio",
      "type": "dash",
      "container_type": "fmp4",
      "audio_config": {
        "codec": "aac",
        "bitrate": 192000,
        "channels": "2",
        "sample_rate": 48000,
        "language": "en",
        "index": 0
      }
      // No video_config specified, audio-only output for this quality.
      // Video only resolutions will use this audio playlist.
    }
  ]
}
POSThttps://api.aiozstream.network/api/videos/create

Headers

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

Body

title* Video's title
description Video's description
is_public Video public's status
metadata Video's pairs of key and value
tags Video's tags
qualitites Video's transcoded qualities (allow: 144p, 240p, 360p, 480p, 720p, 1080p, 1440p, 2160p)

Response

201: Created
{
    "data": {
          "id": "video_id",
          "user_id": "user_id",
          "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"
              }
          ],
          "subtitles": null,
          "chapters": null,
          "player_theme": null,
          "duration": 283.492426,
          "size": 63109470,
          "is_mp4": false,
          "is_public": true,
          "is_panoramic": false,
          "status": "done",
          "created_at": "created_at",
          "updated_at": "updated_at",
          "assets": {
              "source_url": "https://api.aiozstream.network/api/videos/video_id/source",
              "thumbnail_url": "https://api.aiozstream.network/api/videos/video_id/thumbnail?resolution=original",
              "hls_url": "https://api.aiozstream.network/api/videos/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/videos/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/videos/video_id/mp4"
          },
          "player_theme_id": ""
      },
    "status": "success"
}
curl --location https://api.aiozstream.network/api/videos \
--header 'Accept-Language: en-US,en;q=0.9' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--data '{
"title": "video's title"
}'

List videos

This API will list all your videos.

POSThttps://api.aiozstream.network/api/videos

Headers

Authorization Bearer your_access_token_here
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 (default: created_at, allow: created_at, updated_at, title, size)
order_by The way record should be arranged (default: desc, allow: asc,desc)
tags Video's tags (ex: music,mp4)
metadata Video's metadata (ex: {"genre":"rock"})
status Video's status (allow: 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",
                "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"
                    }
                ],
                "subtitles": null,
                "chapters": null,
                "player_theme": null,
                "duration": 283.492426,
                "size": 63109470,
                "is_mp4": false,
                "is_public": true,
                "is_panoramic": false,
                "status": "done",
                "created_at": "created_at",
                "updated_at": "updated_at",
                "assets": {
                    "source_url": "https://api.aiozstream.network/api/videos/video_id/source",
                    "thumbnail_url": "https://api.aiozstream.network/api/videos/video_id/thumbnail?resolution=original",
                    "hls_url": "https://api.aiozstream.network/api/videos/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/videos/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/videos/video_id/mp4"
                },
                "player_theme_id": ""
            }
        ],
        "total": 1
    }
}
 
curl 'https://api.aiozstream.network/api/videos' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'authorization: Bearer <YOUR_JWT_TOKEN>' \
  --data-raw '{"limit":10,"offset":0,"sort_by":"created_at","order_By":"desc"}' \

Get video object

This API will show video's detail.

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

Parameters

video_id The unique identifier of the video.

Headers

Authorization Bearer your_access_token_here
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",
                "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"
                    }
                ],
                "subtitles": null,
                "chapters": null,
                "player_theme": null,
                "duration": 283.492426,
                "size": 63109470,
                "is_mp4": false,
                "is_public": true,
                "is_panoramic": false,
                "status": "done",
                "created_at": "created_at",
                "updated_at": "updated_at",
                "assets": {
                    "source_url": "https://api.aiozstream.network/api/videos/video_id/source",
                    "thumbnail_url": "https://api.aiozstream.network/api/videos/video_id/thumbnail?resolution=original",
                    "hls_url": "https://api.aiozstream.network/api/videos/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/videos/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/videos/video_id/mp4"
                },
                "player_theme_id": ""
    }
}
curl --location 'https://api.aiozstream.network/api/videos/video_id' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: Bearer <YOUR_JWT_TOKEN>'

Calculate transcode price

This endpoint allows you to calculate the price to transcode your video based on your choice of qualities and video's duration.

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

Query

qualities Video's transcode qualities (allow: 144p, 240p, 360p, 480p, 720p, 1080p, 1440p, 2160p)
duration Video's duration

Headers

Authorization Bearer your_access_token_here
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/videos/cost?duration=60&qualities=360p%2C1080p' \
--header 'accept: application/json' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Upload video part

This API allows you to upload your video or a part of it if your video's size is larger than chunk size (chunk size: 50MB - 200MB).

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

Parameters

video_id The unique identifier of the video.

Headers

Authorization Bearer your_access_token_here
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 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/videos/video_id/part' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'content-range: bytes {start_pos}-{end_pos}/{file_size}' \
--form 'hash="part\'s content MD5 hash"' \
--form 'index="part\'s index"' \
--form 'file=@"/path/to/file"'

Upload video completed

This API notify server that video's uploading process is done.

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

Parameters

video_id The unique identifier of the video.

Headers

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

Response

200: OK
{
  "status": "success",
  "message": "Upload video complete successfully."
}
curl --location 'https://api.aiozstream.network/api/videos/video_id/complete' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: Bearer <YOUR_JWT_TOKEN>'

Update video object

This API allow you to update video's information.

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

Parameters

video_id The unique identifier of the video.

Headers

Authorization Bearer your_access_token_here
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_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/videos/video_id' \
--header 'accept: application/json' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "description": "string",
  "player_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 certain video.

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

Parameters

video_id The unique identifier of the video.

Headers

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

Body

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

Response

200: OK
  {"status":"success","message":"Upload thumbnail successfully."}
curl --location 'https://api.aiozstream.network/api/videos/video_id/thumbnail' \
--header 'accept: application/json' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--form 'file=@"/path/to/file"'

Delete video

This API will delete certain video.

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

Parameters

video_id The unique identifier of the video.

Headers

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

Response

200: OK
{"status":"success","message":"Delete video successfully."}
curl --location --request DELETE 'https://api.aiozstream.network/api/videos/video_id' \
--header 'accept: application/json' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'
PreviousPlayer setup and customizationNextLive streamings