OAS 3.0.3

Video Live Streaming

Use the Video Live Streaming API to create and manage your RTMP live streams. This includes managing outputs as well as manually starting and stopping streams. See the live streaming guide for information on how to use the Live Streaming API to stream video to your users.

The API supports Basic Authentication using your Cloudinary API Key and API Secret (which can be found on the Dashboard page of your Cloudinary Console).

Base URL

cloudName

Basic Authentication (basicAuth)

Client Libraries

Shell

Ruby

Node.js

PHP

Python

cURL Shell

Live Stream

Live Stream endpoint

Endpoints

GET/live_streams POST/live_streams GET/live_streams/{liveStreamId}PATCH/live_streams/{liveStreamId}DELETE/live_streams/{liveStreamId}POST/live_streams/{liveStreamId}/activate POST/live_streams/{liveStreamId}/idle GET/live_streams/{liveStreamId}/outputs POST/live_streams/{liveStreamId}/outputs GET/live_streams/{liveStreamId}/outputs/{liveStreamOutputId}PATCH/live_streams/{liveStreamId}/outputs/{liveStreamOutputId}DELETE/live_streams/{liveStreamId}/outputs/{liveStreamOutputId}

Get a list of live streams

Responses

200a list of live streams
application/json
401authentication error
application/json
403authorization error
application/json

GET/live_streams

Shell cURL

curl --request GET \
  --url https://api.cloudinary.com/v2/video/CLOUD_NAME/live_streams \
  --header 'Authorization: Basic'

Show Schema

{
  "request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
  "data": [
    {
      "id": "0bd7f11c043da975e2a8ad9ebae0b6ec",
      "name": "My Live Stream 1",
      "input": {
        "type": "rtmp",
        "uri": "rtmp://live.cloudinary.com/streams",
        "stream_key": "dh8bxtg97t9cns4bddoa"
      },
      "status": "idle",
      "outputs": [
        {
          "id": "8132d2dc5251432bb57f32ee55a336c1",
          "name": "default hls",
          "type": "hls",
          "uri": "https://res.cloudinary.com/demo/video/live/live_stream_0bd7f11c043da975e2a8ad9ebae0b6ec_hls.m3u8",
          "created_at": 1712914020253,
          "updated_at": 1712914020253
        },
        {
          "id": "29b5cd6f54474bea9cec3834e763e12c",
          "name": "default archive",
          "type": "archive",
          "public_id": "live_stream_0bd7f11c043da975e2a8ad9ebae0b6ec_archive",
          "created_at": 1712914020253,
          "updated_at": 1714378330476
        }
      ],
      "idle_timeout_sec": 120,
      "max_runtime_sec": 10800,
      "created_at": 1697265900621,
      "updated_at": 1697265900621
    },
    {
      "id": "92aa375287aa4f2b82be628060c46f43",
      "name": "My Live Stream 2",
      "input": {
        "type": "rtmp",
        "uri": "rtmp://live.cloudinary.com/streams",
        "stream_key": "48224ec768164e11a685a558605f52f5"
      },
      "status": "idle",
      "outputs": [
        {
          "id": "2c5e87b0648c4767acd93ea66d34a3c0",
          "name": "default hls",
          "type": "hls",
          "uri": "https://res.cloudinary.com/demo/video/live/live_stream_92aa375287aa4f2b82be628060c46f43_hls.m3u8",
          "created_at": 1712914020253,
          "updated_at": 1712914020253
        },
        {
          "id": "bb55ab0c159445df93cffbfc1d3a85db",
          "name": "default archive",
          "type": "archive",
          "public_id": "live_stream_92aa375287aa4f2b82be628060c46f43_archive",
          "created_at": 1712914020253,
          "updated_at": 1714378330476
        }
      ],
      "idle_timeout_sec": 120,
      "max_runtime_sec": 10800,
      "created_at": 1697265900621,
      "updated_at": 1697265900621
    }
  ]
}

My Live Streams Response

Create a new live stream

Body

application/json

name

string

ExampleMy first stream

input

required

object

idle_timeout_sec

integer | nullable

Integer numbers.

Example120

max_runtime_sec

integer | nullable

Integer numbers.

Example10800

Responses

200created live stream
application/json
401authentication error
application/json
403authorization error
application/json

POST/live_streams

Shell cURL

curl --request POST \
  --url https://api.cloudinary.com/v2/video/CLOUD_NAME/live_streams \
  --header 'Authorization: Basic' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "My first stream",
  "input": {
    "type": "rtmp"
  },
  "idle_timeout_sec": 120,
  "max_runtime_sec": 10800
}'

Show Schema

{
  "request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
  "data": {
    "id": "0bd7f11c043da975e2a8ad9ebae0b6ec",
    "name": "My Live Stream",
    "input": {
      "type": "rtmp",
      "uri": "rtmp://live.cloudinary.com/streams",
      "stream_key": "dh8bxtg97t9cns4bddoa"
    },
    "status": "idle",
    "outputs": [
      {
        "id": "8132d2dc5251432bb57f32ee55a336c1",
        "name": "default hls",
        "type": "hls",
        "uri": "https://res.cloudinary.com/demo/video/live/live_stream_0bd7f11c043da975e2a8ad9ebae0b6ec_hls.m3u8",
        "created_at": 1712914020253,
        "updated_at": 1712914020253
      },
      {
        "id": "29b5cd6f54474bea9cec3834e763e12c",
        "name": "default archive",
        "type": "archive",
        "public_id": "live_stream_0bd7f11c043da975e2a8ad9ebae0b6ec_archive",
        "created_at": 1712914020253,
        "updated_at": 1714378330476
      }
    ],
    "idle_timeout_sec": 120,
    "max_runtime_sec": 10800,
    "created_at": 1697265900621,
    "updated_at": 1697265900621
  }
}

My Live Stream Response

Get a single live stream

Path Parameters

liveStreamId
required
string

live stream id

Responses

200a live stream
application/json
401authentication error
application/json
403authorization error
application/json
404live stream not found
application/json

GET/live_streams/{liveStreamId}

Shell cURL

curl --request GET \
  --url https://api.cloudinary.com/v2/video/CLOUD_NAME/live_streams/__LIVESTREAMID__ \
  --header 'Authorization: Basic'

Show Schema

{
  "request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
  "data": {
    "id": "0bd7f11c043da975e2a8ad9ebae0b6ec",
    "name": "My Live Stream",
    "input": {
      "type": "rtmp",
      "uri": "rtmp://live.cloudinary.com/streams",
      "stream_key": "dh8bxtg97t9cns4bddoa"
    },
    "status": "idle",
    "outputs": [
      {
        "id": "8132d2dc5251432bb57f32ee55a336c1",
        "name": "default hls",
        "type": "hls",
        "uri": "https://res.cloudinary.com/demo/video/live/live_stream_0bd7f11c043da975e2a8ad9ebae0b6ec_hls.m3u8",
        "created_at": 1712914020253,
        "updated_at": 1712914020253
      },
      {
        "id": "29b5cd6f54474bea9cec3834e763e12c",
        "name": "default archive",
        "type": "archive",
        "public_id": "live_stream_0bd7f11c043da975e2a8ad9ebae0b6ec_archive",
        "created_at": 1712914020253,
        "updated_at": 1714378330476
      }
    ],
    "idle_timeout_sec": 120,
    "max_runtime_sec": 10800,
    "created_at": 1697265900621,
    "updated_at": 1697265900621
  }
}

My Live Stream Response

Update a live stream

Path Parameters

liveStreamId
required
string

live stream id

Body

application/json

name

string | nullable

ExampleMy first stream

idle_timeout_sec

integer | nullable

Integer numbers.

Example120

max_runtime_sec

integer | nullable

Integer numbers.

Example10800

Responses

200a live stream
application/json
401authentication error
application/json
403authorization error
application/json
404live stream not found
application/json

PATCH/live_streams/{liveStreamId}

Shell cURL

curl --request PATCH \
  --url https://api.cloudinary.com/v2/video/CLOUD_NAME/live_streams/__LIVESTREAMID__ \
  --header 'Authorization: Basic' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "My first stream",
  "idle_timeout_sec": 120,
  "max_runtime_sec": 10800
}'

Show Schema

{
  "request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
  "data": {
    "id": "0bd7f11c043da975e2a8ad9ebae0b6ec",
    "name": "My Live Stream",
    "input": {
      "type": "rtmp",
      "uri": "rtmp://live.cloudinary.com/streams",
      "stream_key": "dh8bxtg97t9cns4bddoa"
    },
    "status": "idle",
    "outputs": [
      {
        "id": "8132d2dc5251432bb57f32ee55a336c1",
        "name": "default hls",
        "type": "hls",
        "uri": "https://res.cloudinary.com/demo/video/live/live_stream_0bd7f11c043da975e2a8ad9ebae0b6ec_hls.m3u8",
        "created_at": 1712914020253,
        "updated_at": 1712914020253
      },
      {
        "id": "29b5cd6f54474bea9cec3834e763e12c",
        "name": "default archive",
        "type": "archive",
        "public_id": "live_stream_0bd7f11c043da975e2a8ad9ebae0b6ec_archive",
        "created_at": 1712914020253,
        "updated_at": 1714378330476
      }
    ],
    "idle_timeout_sec": 120,
    "max_runtime_sec": 10800,
    "created_at": 1697265900621,
    "updated_at": 1697265900621
  }
}

My Live Stream Response

Delete a live stream

Path Parameters

liveStreamId
required
string

live stream id

Responses

200ok
application/json
401authentication error
application/json
403authorization error
application/json
404live stream not found
application/json

DELETE/live_streams/{liveStreamId}

Shell cURL

curl --request DELETE \
  --url https://api.cloudinary.com/v2/video/CLOUD_NAME/live_streams/__LIVESTREAMID__ \
  --header 'Authorization: Basic'

Show Schema

{
  "request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
  "data": {
    "message": "…"
  }
}

Manually activate a live stream

Path Parameters

liveStreamId
required
string

live stream id

Responses

200ok
application/json
401authentication error
application/json
403authorization error
application/json

POST/live_streams/{liveStreamId}/activate

Shell cURL

curl --request POST \
  --url https://api.cloudinary.com/v2/video/CLOUD_NAME/live_streams/__LIVESTREAMID__/activate \
  --header 'Authorization: Basic'

Show Schema

{
  "request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
  "data": {
    "message": "…"
  }
}

Manually idle a live stream

Path Parameters

liveStreamId
required
string

live stream id

Responses

200ok
application/json
401authentication error
application/json
403authorization error
application/json

POST/live_streams/{liveStreamId}/idle

Shell cURL

curl --request POST \
  --url https://api.cloudinary.com/v2/video/CLOUD_NAME/live_streams/__LIVESTREAMID__/idle \
  --header 'Authorization: Basic'

Show Schema

{
  "request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
  "data": {
    "message": "…"
  }
}

Get a list of live stream outputs

Path Parameters

liveStreamId
required
string

live stream id

Responses

200a list of outputs for a live stream
application/json
401authentication error
application/json
403authorization error
application/json

GET/live_streams/{liveStreamId}/outputs

Shell cURL

curl --request GET \
  --url https://api.cloudinary.com/v2/video/CLOUD_NAME/live_streams/__LIVESTREAMID__/outputs \
  --header 'Authorization: Basic'

Show Schema

{
  "request_id": "2f9754330d613b998bb572696869b1ed",
  "data": [
    {
      "id": "2c5e87b0648c4767acd93ea66d34a3c0",
      "name": "default hls",
      "type": "hls",
      "uri": "https://res.cloudinary.com/demo/video/live/live_stream_0bd7f11c043da975e2a8ad9ebae0b6ec_hls.m3u8",
      "created_at": 1714480579982,
      "updated_at": 1714480579982
    },
    {
      "id": "bb55ab0c159445df93cffbfc1d3a85db",
      "name": "default archive",
      "type": "archive",
      "public_id": "92aa375287aa_archive",
      "created_at": 1714480579982,
      "updated_at": 1714480579982
    },
    {
      "id": "54434dddf7d44ed7abf55ca34ec70527",
      "name": "new youtube",
      "type": "simulcast",
      "uri": "rtmp://a.rtmp.youtube.com/live2",
      "stream_key": "43q7qmah2e1p83jhfpbs",
      "vendor": "youtube",
      "created_at": 1715859923186,
      "updated_at": 1715859923186
    }
  ]
}

My Live Stream Outputs Response

Create a new live stream output

Path Parameters

liveStreamId
required
string

live stream id

Body

application/json

name

string | nullable

Examplemain stream

type

required

string

Examplehls

uri

string | nullable

Examplertmp://a.rtmp.youtube.com/live2

stream_key

string | nullable

Examplef11c043da975e2a8ad9ebae0b6ec0bd7

vendor

string | nullable

Exampleyoutube

public_id

string | nullable

Examplemain_stream_archive

Responses

200created live stream output
application/json
401authentication error
application/json
403authorization error
application/json

POST/live_streams/{liveStreamId}/outputs

Shell cURL

curl --request POST \
  --url https://api.cloudinary.com/v2/video/CLOUD_NAME/live_streams/__LIVESTREAMID__/outputs \
  --header 'Authorization: Basic' \
  --data '{
  "name": "new youtube",
  "type": "simulcast",
  "uri": "rtmp://a.rtmp.youtube.com/live2",
  "stream_key": "43q7qmah2e1p83jhfpbs",
  "vendor": "youtube"
}'

Show Schema

{
  "request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
  "data": {
    "id": "f11c043da975e2a8ad9ebae0b6ec0bd7",
    "name": "new youtube",
    "type": "simulcast",
    "uri": "rtmp://a.rtmp.youtube.com/live2",
    "stream_key": "43q7qmah2e1p83jhfpbs",
    "vendor": "youtube",
    "created_at": 1697265900621,
    "updated_at": 1697265900621
  }
}

My Live Stream Output Wrapped Response

Get a single live stream output

Path Parameters

liveStreamId
required
string

live stream id
liveStreamOutputId
required
string

live stream output id

Responses

200a live stream output
application/json
401authentication error
application/json
403authorization error
application/json
404live stream output not found
application/json

GET/live_streams/{liveStreamId}/outputs/{liveStreamOutputId}

Shell cURL

curl --request GET \
  --url https://api.cloudinary.com/v2/video/CLOUD_NAME/live_streams/__LIVESTREAMID__/outputs/__LIVESTREAMOUTPUTID__ \
  --header 'Authorization: Basic'

Show Schema

{
  "request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
  "data": {
    "id": "f11c043da975e2a8ad9ebae0b6ec0bd7",
    "name": "new youtube",
    "type": "simulcast",
    "uri": "rtmp://a.rtmp.youtube.com/live2",
    "stream_key": "43q7qmah2e1p83jhfpbs",
    "vendor": "youtube",
    "created_at": 1697265900621,
    "updated_at": 1697265900621
  }
}

My Live Stream Output Wrapped Response

Update a live stream output

Path Parameters

liveStreamId
required
string

live stream id
liveStreamOutputId
required
string

live stream output id

Body

application/json

name

string | nullable

Examplemain stream

uri

string | nullable

Examplertmp://a.rtmp.youtube.com/live2/f11c043da975e2a8ad9ebae0b6ec0bd7

stream_key

string | nullable

Examplef11c043da975e2a8ad9ebae0b6ec0bd7

public_id

string | nullable

Examplemain_stream_archive

Responses

200a live stream output
application/json
401authentication error
application/json
403authorization error
application/json
404live stream output not found
application/json

PATCH/live_streams/{liveStreamId}/outputs/{liveStreamOutputId}

Shell cURL

curl --request PATCH \
  --url https://api.cloudinary.com/v2/video/CLOUD_NAME/live_streams/__LIVESTREAMID__/outputs/__LIVESTREAMOUTPUTID__ \
  --header 'Authorization: Basic' \
  --data '{
  "name": "new youtube",
  "uri": "rtmp://a.rtmp.youtube.com/live2",
  "stream_key": "43q7qmah2e1p83jhfpbs",
  "public_id": "main_stream_archive"
}'

Show Schema

{
  "request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
  "data": {
    "id": "f11c043da975e2a8ad9ebae0b6ec0bd7",
    "name": "new youtube",
    "type": "simulcast",
    "uri": "rtmp://a.rtmp.youtube.com/live2",
    "stream_key": "43q7qmah2e1p83jhfpbs",
    "vendor": "youtube",
    "created_at": 1697265900621,
    "updated_at": 1697265900621
  }
}

My Live Stream Output Wrapped Response

Delete a live stream output

Path Parameters

liveStreamId
required
string

live stream id
liveStreamOutputId
required
string

live stream output id

Responses

200ok
application/json
401authentication error
application/json
403authorization error
application/json
404live stream output not found
application/json

DELETE/live_streams/{liveStreamId}/outputs/{liveStreamOutputId}

Shell cURL

curl --request DELETE \
  --url https://api.cloudinary.com/v2/video/CLOUD_NAME/live_streams/__LIVESTREAMID__/outputs/__LIVESTREAMOUTPUTID__ \
  --header 'Authorization: Basic'

Show Schema

{
  "request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
  "data": {
    "message": "…"
  }
}

Live Stream Output

Live Stream Output endpoint

Models

MessageWrappedResponse

ErrorWrappedResponse

{} LiveStreamsWrappedResponse

{} LiveStreamWrappedResponse

{} LiveStreamOutputsWrappedResponse

{} LiveStreamOutputWrappedResponse

{} LiveStreamResponse

{} LiveStreamInputResponse

{} LiveStreamOutputResponse

{} LiveStreamCreatePayload


Key Required
Secret

Key

Value

Response

.,,uod8B8bou,,. ..,uod8BBBBBBBBBBBBBBBBRPFT?l!i:. ||||||||||||||!?TFPRBBBBBBBBBBBBBBB8m=, |||| '""^^!!||||||||||TFPRBBBVT!:...! |||| '""^^!!|||||?!:.......! |||| ||||.........! |||| ||||.........! |||| ||||.........! |||| ||||.........! |||| ||||.........! |||| ||||.........! ||||, ||||.........` |||||!!-._ ||||.......;. ':!|||||||||!!-._ ||||.....bBBBBWdou,. bBBBBB86foi!|||||||!!-..:|||!..bBBBBBBBBBBBBBBY! ::!?TFPRBBBBBB86foi!||||||||!!bBBBBBBBBBBBBBBY..! :::::::::!?TFPRBBBBBB86ftiaabBBBBBBBBBBBBBBY....! :::;`"^!:;::::::!?TFPRBBBBBBBBBBBBBBBBBBBY......! ;::::::...''^::::::::::!?TFPRBBBBBBBBBBY........! .ob86foi;::::::::::::::::::::::::!?TFPRBY..........` .b888888888886foi;:::::::::::::::::::::::..........` .b888888888888888888886foi;::::::::::::::::...........b888888888888888888888888888886foi;:::::::::......`!Tf998888888888888888888888888888888886foi;:::....` '"^!|Tf9988888888888888888888888888888888!::..` '"^!|Tf998888888888888888888888889!! '` '"^!|Tf9988888888888888888!!` iBBbo. '"^!|Tf998888888889!` WBBBBbo. '"^!|Tf9989!` YBBBP^' '"^!` `

Error

Video Live Streaming

Live Stream​ # Copy link to "Live Stream"

Get a list of live streams​ # Copy link to "Get a list of live streams"

Create a new live stream​ # Copy link to "Create a new live stream"

Get a single live stream​ # Copy link to "Get a single live stream"

Update a live stream​ # Copy link to "Update a live stream"

Delete a live stream​ # Copy link to "Delete a live stream"

Manually activate a live stream​ # Copy link to "Manually activate a live stream"

Manually idle a live stream​ # Copy link to "Manually idle a live stream"

Get a list of live stream outputs​ # Copy link to "Get a list of live stream outputs"

Create a new live stream output​ # Copy link to "Create a new live stream output"

Get a single live stream output​ # Copy link to "Get a single live stream output"

Update a live stream output​ # Copy link to "Update a live stream output"

Delete a live stream output​ # Copy link to "Delete a live stream output"

Live Stream Output​ # Copy link to "Live Stream Output"

Models

Live Stream

Get a list of live streams

Create a new live stream

Get a single live stream

Update a live stream

Delete a live stream

Manually activate a live stream

Manually idle a live stream

Get a list of live stream outputs

Create a new live stream output

Get a single live stream output

Update a live stream output

Delete a live stream output

Live Stream Output