Sign up for free

Live Streams

List all live streams

Get the list of livestreams on the workspace.

get /live-streams
streamKey string

The unique stream key that allows you to stream videos.

Example
"dw-dew8-q6w9-k67w-1ws8"
name string

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

Example
"My Video"
sortBy string

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 ISO-8601 time format.

Enum
  • name
  • createdAt
  • updatedAt
Example
"createdAt"
sortOrder 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.

Enum
  • asc
  • desc
Example
"desc"
currentPage int

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

Default
1
Example
2
pageSize int

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

Default
25
Example
30

Requests

// 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)
  }

Responses

ExamplesSchema

Success

{
  "data": [
    {
      "liveStreamId": "li400mYKSgQ6xs7taUeSaEKr",
      "createdAt": "2020-01-31T10:17:47.000Z",
      "updatedAt": "2020-03-09T13:19:43.000Z",
      "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.000Z",
      "updatedAt": "2020-07-29T10:45:35.000Z",
      "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"
      }
    ]
  }
}

Create live stream

Creates a livestream object.

post /live-streams
name string

required

Add a name for your live stream here.

Example
"My Live Stream Video"
public boolean

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.

playerId string

The unique identifier for the player.

Example
"pl4f4ferf5erfr5zed4fsdd"
restreams array[object (Restreams request object)]

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

Requests

{
  "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"
    }
  ]
}

Responses

ExamplesSchema

Success

{
  "liveStreamId": "li4pqNqGUkhKfWcBGpZVLRY5",
  "createdAt": "2020-07-29T10:45:35.000Z",
  "updatedAt": "2020-07-29T10:45:35.000Z",
  "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"
  }
}

Retrieve live stream

Get a livestream by id.

get /live-streams/{liveStreamId}
liveStreamId string

required

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

Example
"li400mYKSgQ6xs7taUeSaEKr"

Requests

// 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)
}

Responses

ExamplesSchema

Success

{
  "liveStreamId": "li4pqNqGUkhKfWcBGpZVLRY5",
  "createdAt": "2020-07-29T10:45:35.000Z",
  "updatedAt": "2020-07-29T10:45:35.000Z",
  "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 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.

delete /live-streams/{liveStreamId}
liveStreamId string

required

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

Example
"li400mYKSgQ6xs7taUeSaEKr"

Requests

// 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)
    }
}

Responses

ExamplesSchema

No Content

Empty response

Update a live stream

Updates the livestream object.

patch /live-streams/{liveStreamId}
name string

The name you want to use for your live stream.

Example
"My Live Stream Video"
public boolean

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.

playerId string

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

Example
"pl45KFKdlddgk654dspkze"
restreams array[object (Restreams request object)]

Use this parameter to add, edit, or remove 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.

Requests

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

Responses

ExamplesSchema

Success

{
  "liveStreamId": "li4pqNqGUkhKfWcBGpZVLRY5",
  "createdAt": "2020-07-29T10:45:35.000Z",
  "updatedAt": "2020-07-29T10:45:35.000Z",
  "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"
  }
}

Upload a thumbnail

Upload the thumbnail for the livestream.

post /live-streams/{liveStreamId}/thumbnail
file file

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.

Requests

// 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)
}

Responses

ExamplesSchema

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=\\\"