Live Streams

Live Streams

Download Spec

get/live-streams

List all live streams

Get the list of livestreams on the workspace.

streamKeystring

The unique stream key that allows you to stream videos.

Example: "dw-dew8-q6w9-k67w-1ws8"

namestring

You can filter live streams by their name or a part of their name.

Example: "My Video"

sortBystring

Enables you to sort live stream results. Allowed attributes: name, createdAt, updatedAt. name - the name of the live stream. createdAt - the time a live stream was created. updatedAt - the time a live stream was last updated.

When using createdAt or updatedAt, the API sorts the results based on the ATOM UTC time format.

Enum: name
createdAt
updatedAt
Example: "createdAt"

sortOrderstring

Allowed: asc, desc. Ascending for date and time means that earlier values precede later ones. Descending means that later values preced earlier ones. For title, it is 0-9 and A-Z ascending and Z-A, 9-0 descending.

Enum: asc
desc
Example: "desc"

currentPageint

Choose the number of search results to return per page. Minimum value: 1

Default: 1
Example: 2

pageSizeint

Results per page. Allowed values 1-100, default is 25.

Default: 25
Example: 30

Responses

Request examples

// First install the go client with "go get github.com/apivideo/api.video-go-client"
// Documentation: https://github.com/apivideo/api.video-go-client/blob/main/docs/LiveStreamsApi.md#list

package main
  
  import (
      "context"
      "fmt"
      "os"
      apivideosdk "github.com/apivideo/api.video-go-client"
  )
  
  func main() {
      client := apivideosdk.ClientBuilder("YOUR_API_KEY").Build()
      // if you rather like to use the sandbox environment:
      // client := apivideosdk.SandboxClientBuilder("YOUR_SANDBOX_API_KEY").Build()
      req := apivideosdk.LiveStreamsApiListRequest{}
      
      req.StreamKey("30087931-229e-42cf-b5f9-e91bcc1f7332") // string | The unique stream key that allows you to stream videos.
      req.Name("My Video") // string | You can filter live streams by their name or a part of their name.
      req.SortBy("createdAt") // string | Enables you to sort live stream results. Allowed attributes: `name`, `createdAt`, `updatedAt`.
      req.SortOrder("desc") // string | Allowed: asc, desc. Ascending for date and time means that earlier values precede later ones. Descending means that later values preced earlier ones. For title, it is 0-9 and A-Z ascending and Z-A, 9-0 descending.
      req.CurrentPage(int32(2)) // int32 | Choose the number of search results to return per page. Minimum value: 1 (default to 1)
      req.PageSize(int32(30)) // int32 | Results per page. Allowed values 1-100, default is 25. (default to 25)
  
      res, err := client.LiveStreams.List(req)
      
  
      if err != nil {
          fmt.Fprintf(os.Stderr, "Error when calling `LiveStreams.List``: %v\
", err)
      }
      // response from `List`: LiveStreamListResponse
      fmt.Fprintf(os.Stdout, "Response from `LiveStreams.List`: %v\
", res)
  }

Response examples

Success

{
  "data": [
    {
      "liveStreamId": "li400mYKSgQ6xs7taUeSaEKr",
      "createdAt": "2020-01-31T10:17:47+00:00",
      "updatedAt": "2020-03-09T13:19:43+00:00",
      "streamKey": "30087931-229e-42cf-b5f9-e91bcc1f7332",
      "restreams": [
        {
          "name": "YouTube",
          "serverUrl": "rtmp://youtube.broadcast.example.com",
          "streamKey": "cc1b4df0-d1c5-4064-a8f9-9f0368385188"
        },
        {
          "name": "Twitch",
          "serverUrl": "rtmp://twitch.broadcast.example.com",
          "streamKey": "cc1b4df0-d1c5-4064-a8f9-9f0368385188"
        }
      ],
      "name": "Live Stream From the browser",
      "public": true,
      "broadcasting": false,
      "assets": {
        "iframe": "<iframe src=\"https://embed.api.video/live/li400mYKSgQ6xs7taUeSaEKr\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
        "player": "https://embed.api.video/live/li400mYKSgQ6xs7taUeSaEKr",
        "hls": "https://live.api.video/li400mYKSgQ6xs7taUeSaEKr.m3u8",
        "thumbnail": "https://live.api.video/li400mYKSgQ6xs7taUeSaEKr/thumbnail.jpg"
      }
    },
    {
      "liveStreamId": "li4pqNqGUkhKfWcBGpZVLRY5",
      "createdAt": "2020-07-29T10:45:35+00:00",
      "updatedAt": "2020-07-29T10:45:35+00:00",
      "streamKey": "cc1b4df0-d1c5-4064-a8f9-9f0368385135",
      "restreams": [
        {
          "name": "YouTube",
          "serverUrl": "rtmp://youtube.broadcast.example.com",
          "streamKey": "cc1b4df0-d1c5-4064-a8f9-9f0368385135"
        },
        {
          "name": "Twitch",
          "serverUrl": "rtmp://twitch.broadcast.example.com",
          "streamKey": "cc1b4df0-d1c5-4064-a8f9-9f0368385135"
        }
      ],
      "name": "Live From New York",
      "public": true,
      "broadcasting": false,
      "assets": {
        "iframe": "<iframe src=\"https://embed.api.video/live/li4pqNqGUkhKfWcBGpZVLRY5\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
        "player": "https://embed.api.video/live/li4pqNqGUkhKfWcBGpZVLRY5",
        "hls": "https://live.api.video/li4pqNqGUkhKfWcBGpZVLRY5.m3u8",
        "thumbnail": "https://live.api.video/li4pqNqGUkhKfWcBGpZVLRY5/thumbnail.jpg"
      }
    }
  ],
  "pagination": {
    "currentPage": 1,
    "currentPageItems": 19,
    "pageSize": 25,
    "pagesTotal": 1,
    "itemsTotal": 19,
    "links": [
      {
        "rel": "self",
        "uri": "/live-streams?currentPage=1&pageSize=25"
      },
      {
        "rel": "first",
        "uri": "/live-streams?currentPage=1&pageSize=25"
      },
      {
        "rel": "last",
        "uri": "/live-streams?currentPage=1&pageSize=25"
      }
    ]
  }
}

post/live-streams

Create live stream

Creates a livestream object.

namestring

required

Add a name for your live stream here.

Example: "My Live Stream Video"

publicboolean

Whether your video can be viewed by everyone, or requires authentication to see it. A setting of false will require a unique token for each view. Learn more about the Private Video feature here.

playerIdstring

The unique identifier for the player.

Example: "pl4f4ferf5erfr5zed4fsdd"

restreamsarray

Use this parameter to add, edit, or remove RTMPS or RTMP services where you want to restream a live stream. The list can only contain up to 5 destinations.

namestring

required

Use this parameter to define a name for the restream destination.

Example: "My restream server"

serverUrlstring

required

Use this parameter to set the RTMPS or RTMP server URL of the restream destination.

Example: "rtmp://my.broadcast.example.com/app"

streamKeystring

required

Use this parameter to provide the unique key of the live stream that you want to restream.

Example: "dw-dew8-q6w9-k67w-1ws8"

Responses

Request examples

{
  "name": "Test live",
  "playerId": "pl4f4ferf5erfr5zed4fsdd",
  "restreams": [
    {
      "name": "YouTube",
      "serverUrl": "rtmp://youtube.broadcast.example.com",
      "streamKey": "dw-dew8-q6w9-k67w-1ws8"
    },
    {
      "name": "Twitch",
      "serverUrl": "rtmp://twitch.broadcast.example.com",
      "streamKey": "dw-dew8-q6w9-k67w-1ws8"
    }
  ]
}

Response examples

Success

{
  "liveStreamId": "li4pqNqGUkhKfWcBGpZVLRY5",
  "createdAt": "2020-07-29T10:45:35+00:00",
  "updatedAt": "2020-07-29T10:45:35+00:00",
  "streamKey": "cc1b4df0-d1c5-4064-a8f9-9f0368385135",
  "restreams": [
    {
      "name": "YouTube",
      "serverUrl": "rtmp://youtube.broadcast.example.com",
      "streamKey": "cc1b4df0-d1c5-4064-a8f9-9f0368385135"
    },
    {
      "name": "Twitch",
      "serverUrl": "rtmp://twitch.broadcast.example.com",
      "streamKey": "cc1b4df0-d1c5-4064-a8f9-9f0368385135"
    }
  ],
  "name": "Live From New York",
  "public": true,
  "broadcasting": false,
  "assets": {
    "iframe": "<iframe src=\"https://embed.api.video/live/li4pqNqGUkhKfWcBGpZVLRY5\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
    "player": "https://embed.api.video/live/li4pqNqGUkhKfWcBGpZVLRY5",
    "hls": "https://live.api.video/li4pqNqGUkhKfWcBGpZVLRY5.m3u8",
    "thumbnail": "https://live.api.video/li4pqNqGUkhKfWcBGpZVLRY5/thumbnail.jpg"
  }
}

get/live-streams/{liveStreamId}

Retrieve live stream

Get a livestream by id.

liveStreamIdstring

required

The unique ID for the live stream you want to watch.

Example: "li400mYKSgQ6xs7taUeSaEKr"

Responses

Request examples

// First install the go client with "go get github.com/apivideo/api.video-go-client"
// Documentation: https://github.com/apivideo/api.video-go-client/blob/main/docs/LiveStreamsApi.md#get

package main

import (
    "context"
    "fmt"
    "os"
    apivideosdk "github.com/apivideo/api.video-go-client"
)

func main() {
    client := apivideosdk.ClientBuilder("YOUR_API_KEY").Build()
    // if you rather like to use the sandbox environment:
    // client := apivideosdk.SandboxClientBuilder("YOUR_SANDBOX_API_KEY").Build()
        
    liveStreamId := "li400mYKSgQ6xs7taUeSaEKr" // string | The unique ID for the live stream you want to watch.

    
    res, err := client.LiveStreams.Get(liveStreamId)

    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `LiveStreams.Get``: %v\
", err)
    }
    // response from `Get`: LiveStream
    fmt.Fprintf(os.Stdout, "Response from `LiveStreams.Get`: %v\
", res)
}

Response examples

Success

{
  "liveStreamId": "li4pqNqGUkhKfWcBGpZVLRY5",
  "createdAt": "2020-07-29T10:45:35+00:00",
  "updatedAt": "2020-07-29T10:45:35+00:00",
  "streamKey": "cc1b4df0-d1c5-4064-a8f9-9f0368385135",
  "restreams": [
    {
      "name": "YouTube",
      "serverUrl": "rtmp://youtube.broadcast.example.com",
      "streamKey": "cc1b4df0-d1c5-4064-a8f9-9f0368385135"
    },
    {
      "name": "Twitch",
      "serverUrl": "rtmp://twitch.broadcast.example.com",
      "streamKey": "cc1b4df0-d1c5-4064-a8f9-9f0368385135"
    }
  ],
  "name": "Live From New York",
  "public": true,
  "broadcasting": false,
  "assets": {
    "iframe": "<iframe src=\"https://embed.api.video/live/li4pqNqGUkhKfWcBGpZVLRY5\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
    "player": "https://embed.api.video/live/li4pqNqGUkhKfWcBGpZVLRY5",
    "hls": "https://live.api.video/li4pqNqGUkhKfWcBGpZVLRY5.m3u8",
    "thumbnail": "https://live.api.video/li4pqNqGUkhKfWcBGpZVLRY5/thumbnail.jpg"
  }
}

delete/live-streams/{liveStreamId}

Delete a live stream

If you do not need a live stream any longer, you can send a request to delete it. All you need is the liveStreamId.

liveStreamIdstring

required

The unique ID for the live stream that you want to remove.

Example: "li400mYKSgQ6xs7taUeSaEKr"

Responses

Request examples

// First install the go client with "go get github.com/apivideo/api.video-go-client"
// Documentation: https://github.com/apivideo/api.video-go-client/blob/main/docs/LiveStreamsApi.md#delete

package main

import (
    "context"
    "fmt"
    "os"
    apivideosdk "github.com/apivideo/api.video-go-client"
)

func main() {
    client := apivideosdk.ClientBuilder("YOUR_API_KEY").Build()
    // if you rather like to use the sandbox environment:
    // client := apivideosdk.SandboxClientBuilder("YOUR_SANDBOX_API_KEY").Build()
        
    liveStreamId := "li400mYKSgQ6xs7taUeSaEKr" // string | The unique ID for the live stream that you want to remove.

    
    err := client.LiveStreams.Delete(liveStreamId)

    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `LiveStreams.Delete``: %v\
", err)
    }
}

Response examples

No Content

Empty response

patch/live-streams/{liveStreamId}

Update a live stream

Updates the livestream object.

namestring

The name you want to use for your live stream.

Example: "My Live Stream Video"

publicboolean

Whether your video can be viewed by everyone, or requires authentication to see it. A setting of false will require a unique token for each view. Learn more about the Private Video feature here.

playerIdstring

The unique ID for the player associated with a live stream that you want to update.

Example: "pl45KFKdlddgk654dspkze"

restreamsarray

Use this parameter to add, edit, or remove RTMPS or RTMP services where you want to restream a live stream. The list can only contain up to 5 destinations. This operation updates all restream destinations in the same request. If you do not want to modify an existing restream destination, you need to include it in your request, otherwise it is removed.

namestring

required

Use this parameter to define a name for the restream destination.

Example: "My restream server"

serverUrlstring

required

Use this parameter to set the RTMPS or RTMP server URL of the restream destination.

Example: "rtmp://my.broadcast.example.com/app"

streamKeystring

required

Use this parameter to provide the unique key of the live stream that you want to restream.

Example: "dw-dew8-q6w9-k67w-1ws8"

Responses

Request examples

{
  "name": "My Live Stream Video",
  "public": true,
  "playerId": "pl45KFKdlddgk654dspkze",
  "restreams": [
    {
      "name": "My restream server",
      "serverUrl": "rtmp://my.broadcast.example.com/app",
      "streamKey": "dw-dew8-q6w9-k67w-1ws8"
    }
  ]
}

Response examples

Success

{
  "liveStreamId": "li4pqNqGUkhKfWcBGpZVLRY5",
  "createdAt": "2020-07-29T10:45:35+00:00",
  "updatedAt": "2020-07-29T10:45:35+00:00",
  "streamKey": "cc1b4df0-d1c5-4064-a8f9-9f0368385135",
  "restreams": [
    {
      "name": "YouTube",
      "serverUrl": "rtmp://youtube.broadcast.example.com",
      "streamKey": "cc1b4df0-d1c5-4064-a8f9-9f0368385135"
    },
    {
      "name": "Twitch",
      "serverUrl": "rtmp://twitch.broadcast.example.com",
      "streamKey": "cc1b4df0-d1c5-4064-a8f9-9f0368385135"
    }
  ],
  "name": "Live From New York",
  "public": true,
  "broadcasting": false,
  "assets": {
    "iframe": "<iframe src=\"https://embed.api.video/live/li4pqNqGUkhKfWcBGpZVLRY5\" width=\"100%\" height=\"100%\" frameborder=\"0\" scrolling=\"no\" allowfullscreen=\"\"></iframe>",
    "player": "https://embed.api.video/live/li4pqNqGUkhKfWcBGpZVLRY5",
    "hls": "https://live.api.video/li4pqNqGUkhKfWcBGpZVLRY5.m3u8",
    "thumbnail": "https://live.api.video/li4pqNqGUkhKfWcBGpZVLRY5/thumbnail.jpg"
  }
}

post/live-streams/{liveStreamId}/thumbnail

Upload a thumbnail

Upload the thumbnail for the livestream.

filefile

required

The image to be added as a thumbnail. The mime type should be image/jpeg, image/png or image/webp. The max allowed size is 8 MiB.

Responses

Request examples

// First install the go client with "go get github.com/apivideo/api.video-go-client"
// Documentation: https://github.com/apivideo/api.video-go-client/blob/main/docs/LiveStreamsApi.md#uploadThumbnail

package main

import (
    "context"
    "fmt"
    "os"
    apivideosdk "github.com/apivideo/api.video-go-client"
)

func main() {
    client := apivideosdk.ClientBuilder("YOUR_API_KEY").Build()
    // if you rather like to use the sandbox environment:
    // client := apivideosdk.SandboxClientBuilder("YOUR_SANDBOX_API_KEY").Build()
        
    liveStreamId := "vi4k0jvEUuaTdRAEjQ4Jfrgz" // string | The unique ID for the live stream you want to upload.
    file := os.NewFile(1234, "some_file") // *os.File | The image to be added as a thumbnail.

    
    res, err := client.LiveStreams.UploadThumbnailFile(liveStreamId, file)

    // you can also use a Reader instead of a File:
    // client.LiveStreams.UploadThumbnail(liveStreamId, fileName, fileReader)

    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `LiveStreams.UploadThumbnail``: %v\
", err)
    }
    // response from `UploadThumbnail`: LiveStream
    fmt.Fprintf(os.Stdout, "Response from `LiveStreams.UploadThumbnail`: %v\
", res)
}

Response examples

Created

{
  "liveStreamId": "li400mYKSgQ6xs7taUeSaEKr",
  "name": "My Live Stream",
  "streamKey": "dw-dew8-q6w9-k67w-1ws8",
  "public": true,
  "assets": {
    "hls": "https://live.api.video/li4pqNqGUkhKfWcBGpZVLRY5.m3u8",
    "iframe": "<iframe src=\\\"https://embed.api.video/live/li4pqNqGUkhKfWcBGpZVLRY5\\\" width=\\\"100%\\\" height=\\\"100%\\\" frameborder=\\\"0\\\" scrolling=\\\"no\\\" allowfullscreen=\\\"\\\"></iframe>",
    "player": "https://embed.api.video/live/li400mYKSgQ6xs7taUeSaEKr",
    "thumbnail": "https://live.api.video/li400mYKSgQ6xs7taUeSaEKr/thumbnail.jpg"
  },
  "playerId": "pl45d5vFFGrfdsdsd156dGhh",
  "broadcasting": true,
  "restreams": [
    {
      "name": "My restream server",
      "serverUrl": "rtmp://my.broadcast.example.com/app",
      "streamKey": "dw-dew8-q6w9-k67w-1ws8"
    }
  ],
  "createdAt": "2020-01-31T10:17:47+00:00",
  "updatedAt": "2020-01-31T10:18:47+00:00"
}

delete/live-streams/{liveStreamId}/thumbnail

Delete a thumbnail

Send the unique identifier for a live stream to delete its thumbnail.

liveStreamIdstring

required

The unique identifier of the live stream whose thumbnail you want to delete.

Example: "li400mYKSgQ6xs7taUeSaEKr"

Responses

Request examples

// First install the go client with "go get github.com/apivideo/api.video-go-client"
// Documentation: https://github.com/apivideo/api.video-go-client/blob/main/docs/LiveStreamsApi.md#deleteThumbnail

package main

import (
    "context"
    "fmt"
    "os"
    apivideosdk "github.com/apivideo/api.video-go-client"
)

func main() {
    client := apivideosdk.ClientBuilder("YOUR_API_KEY").Build()
    // if you rather like to use the sandbox environment:
    // client := apivideosdk.SandboxClientBuilder("YOUR_SANDBOX_API_KEY").Build()
        
    liveStreamId := "li400mYKSgQ6xs7taUeSaEKr" // string | The unique identifier for the live stream you want to delete. 

    
    res, err := client.LiveStreams.DeleteThumbnail(liveStreamId)

    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `LiveStreams.DeleteThumbnail``: %v\
", err)
    }
    // response from `DeleteThumbnail`: LiveStream
    fmt.Fprintf(os.Stdout, "Response from `LiveStreams.DeleteThumbnail`: %v\
", res)
}

Response examples

Success

{
  "liveStreamId": "li400mYKSgQ6xs7taUeSaEKr",
  "name": "My Live Stream",
  "streamKey": "dw-dew8-q6w9-k67w-1ws8",
  "public": true,
  "assets": {
    "hls": "https://live.api.video/li4pqNqGUkhKfWcBGpZVLRY5.m3u8",
    "iframe": "<iframe src=\\\"https://embed.api.video/live/li4pqNqGUkhKfWcBGpZVLRY5\\\" width=\\\"100%\\\" height=\\\"100%\\\" frameborder=\\\"0\\\" scrolling=\\\"no\\\" allowfullscreen=\\\"\\\"></iframe>",
    "player": "https://embed.api.video/live/li400mYKSgQ6xs7taUeSaEKr",
    "thumbnail": "https://live.api.video/li400mYKSgQ6xs7taUeSaEKr/thumbnail.jpg"
  },
  "playerId": "pl45d5vFFGrfdsdsd156dGhh",
  "broadcasting": true,
  "restreams": [
    {
      "name": "My restream server",
      "serverUrl": "rtmp://my.broadcast.example.com/app",
      "streamKey": "dw-dew8-q6w9-k67w-1ws8"
    }
  ],
  "createdAt": "2020-01-31T10:17:47+00:00",
  "updatedAt": "2020-01-31T10:18:47+00:00"
}

put/live-streams/{liveStreamId}/complete

Complete a live stream

Request the completion of a live stream that is currently running. This operation is asynchronous and the live stream will stop after a few seconds.

The API adds the EXT-X-ENDLIST tag to the live stream's HLS manifest. This stops the live stream on the player and also stops the recording of the live stream. The API keeps the incoming connection from the streamer open for at most 1 minute, which can be used to terminate the stream.

liveStreamIdstring

required

The unique ID for the live stream you want to complete.

Example: "vi4k0jvEUuaTdRAEjQ4Jfrgz"

Responses

Response examples

Accepted

Empty response

Was this page helpful?