Get started broadcasting a live stream using the Wowza Streaming Cloud REST API

Learn how to use the REST API to send a single encoded stream through the Wowza Streaming Cloud™ service, transcode it to multiple bitrate renditions, and deliver the stream to a player on a Wowza Streaming Cloud-hosted webpage. Then, learn how to programmatically start and stop the live stream and view it on the hosted page.

Locate your API key and access key


For security, all requests to the Wowza Streaming Cloud REST API must include an API key and an access key, which authenticate your requests to the Wowza Streaming Cloud service.

Both the API key and the access key can be found in the Wowza Streaming Cloud web manager.

  1. In the menu bar, click your user name and choose API Access.

Your API key appears in the middle of the Wowza Streaming Cloud REST API page.
Access keys are listed in the Access Keys panel on the left side of the page.

  1. To generate a new access key, click Add Access Key.
  2. Leave Enabled selected so that the key is immediately available, and provide an optional Description. Then, click Add.

Wowza Streaming Cloud generates the key.

You can disable and re-enable the access key at any time, and edit the description.

Important: In example requests shown in our example articles—and in your own code—for [key], substitute your API key or your access key, as appropriate.

Create a live stream


Create a Wowza Streaming Cloud live stream that receives a stream from Wowza GoCoder™, an RTSP-based encoding app for Apple iOS and Android mobile devices. 

Refer to the parameters and example request below to construct your API request. Example requests are presented in curl, but you can also use a GUI REST client for API testing such as Postman or Paw.

For detailed reference information, see the Wowza Streaming Cloud REST API Reference Documentation.

If you have basic questions about using a REST API, start with About the Wowza Streaming Cloud REST API.

Ingest parameters

Parameter Data Type Description
aspect_ratio_height integer The height, in pixels, of the output rendition. Should correspond to the aspect ratio (widescreen or standard) of the video source and be divisible by 8. Use the default, 1080.
aspect_ratio_width integer The width, in pixels, of the output rendition. Should correspond to the aspect ratio (widescreen or standard) of the video source and be divisible by 8. Use the default, 1920.

The greater the source aspect ratio, the more bitrate renditions Wowza Streaming Cloud creates of the live stream. The highest supported widescreen aspect ratio, 3840x2160, generates 7 bitrate renditions. The highest supported standard aspect ratio, 768x576, generates 4 bitrate renditions.
billing_mode string The billing mode for the stream. Use the default, pay_as_you_go
broadcast_location string Specify the region that's closest to where your stream originates.

For pay-as-you-go subscriptions, specify asia_pacific_australia, asia_pacific_india, asia_pacific_japan, asia_pacific_s_korea, asia_pacific_singapore, asia_pacific_taiwan, eu_belgium, eu_germany, eu_ireland, south_america_brazil, us_central_iowa, us_east_s_carolina, us_east_virginia, us_west_california, or us_west_oregon.

For 24x7 subscriptions, specify asia_pacific_taiwan, eu_belgium, us_central_iowa, or us_east_s_carolina.

4K streaming (3840x2160 aspect ratio) is not supported at asia_pacific_indiaasia_pacific_taiwan, eu_belgium, us_central_iowa, or us_east_s_carolina.
closed_caption_type string The type of closed caption data being passed from the source. For this example, use the default, none, indicating that no data is being provided. 
delivery_method string The method you're using to deliver the source stream to the transcoder. Use push, the default, to push the stream directly to Wowza Streaming Cloud from the Wowza GoCoder app.
encoder string Specify wowza_gocoder to use the Wowza GoCoder mobile encoding app as the video source for the live stream. one of the following values as the video source for the live stream.
name string The name of the live stream. Enter an alphanumeric string that is short (maximum 200 characters) and descriptive, for example, MyLiveStream.
password string A password for authenticating an RTMP or RTSP push connection. Can contain only uppercase and lowercase letters; numbers; and the period (.), underscore (_), and hyphen (-) characters. No other special characters can be used. If you don't specify a password, Wowza Streaming Cloud will generate one for you.
transcoder_type string Transcoders can be either transcoded, for streams that are transcoded into adaptive bitrate renditions, or passthrough, for streams that aren't processed by the transcoder. Specify the default, transcoded.
 
Note: Adaptive bitrate transcoding (transcoded) is available at all broadcast locations. Passthrough transcoding is only available at asia_pacific_taiwan, eu_belgium, us_central_iowa, and us_east_s_carolina.
username string A username for authenticating an RTMP or RTSP push connection. Can contain only uppercase and lowercase letters; numbers; and the period (.), underscore (_), and hyphen (-) characters. No other special characters can be used. If you don't specify a username, Wowza Streaming Cloud will generate one for you.

Player parameters

By default, creating a live stream generates a player that viewers can use to watch the event. The player can be embedded on a webpage hosted by the Wowza Streaming Cloud service, or you can embed it in a third-party site.

For this example, customize the player using the following parameters.

Parameter Data Type Description
player_countdown Boolean A clock that appears in the player before the event and counts down to the start of the stream. Specify true to display the countdown clock. The default is false.
player_countdown_at datetime The date and time that the event starts, used by the countdown clock. Specify YYYY-MM-DD HH:MM:SS, where HH is a 24-hour clock in UTC.
player_logo_image string A Base64-encoded string representation of a GIF, JPEG, or PNG logo file that appears partially transparent in a corner of the player throughout playback. Must be 2.5 MB or smaller.
player_logo_position string If a player logo is used, the corner of the player in which you want the player logo to appear. The default is top-left. Other accepted values are top-right, bottom-left, and bottom-right.
player_responsive Boolean A player whose size adjusts according to the device on which it's being viewed. The default, true, creates a responsive player. If false, Wowza Streaming Cloud creates a fixed-width player.
player_type string The player you want to use. Select wowza_player to provide HTML5 playback over Apple HLS.

wowza_player requires that target_delivery_protocol be hls and closed_caption_type be none.
player_video_poster_image string A Base64-encoded string representation of a GIF, JPEG, or PNG poster image that appears in the player before the stream begins. Must be 2.5 MB or smaller.
player_width integer The width, in pixels, of a fixed-width player. The default is 640. The player height is calculated automatically based on the aspect ratio of the source. If player_responsive is true, player_width is 0.

Hosted page parameters

By default, creating a live stream generates a webpage hosted by the Wowza Streaming Cloud service. The webpage includes the hosted player. Customize the hosted webpage for this example using the following parameters.

Parameter Data Type Description
hosted_page Boolean Use the default, true, to generate the hosted page. 
hosted_page_description string An optional description that appears on the hosted page below the player. Can't include custom HTML, JavaScript, or other tags.
hosted_page_logo_image string A Base64-encoded string representation of a GIF, JPEG, or PNG logo file that appears in the upper-left corner of the hosted page. Must be 2.5 MB or smaller.
hosted_page_sharing_icons Boolean Icons that let viewers share the stream on Facebook, Google+, Twitter, and by email. Use the default, true, to include sharing icons on the hosted page. 
hosted_page_title string A title for the page that appears above the player. Can't include custom HTML, JavaScript, or other tags. If blank, Wowza Streaming Cloud uses the live stream name as the hosted page title.

Example request and response

The following request generates a live stream that uses Wowza GoCoder as the video source and is delivered to viewers using a responsive player and webpage hosted by Wowza Streaming Cloud.

Notes:

  • For [key], substitute your API key or your access key as appropriate. For more information, see Locate your API key and access key.
  • For [version], substitute the version number of the API that you're using. For the current version, use v1.2.
curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
   "live_stream": {
     "aspect_ratio_height": 1080,
     "aspect_ratio_width": 1920,
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_west_california",
     "closed_caption_type": "none",
     "delivery_method": "push",
     "encoder": "wowza_gocoder",
     "hosted_page": true,
     "hosted_page_sharing_icons": true,
     "name": "MyLiveStream",
     "player_responsive": true,
     "player_type": "wowza_player",
     "transcoder_type": "transcoded"
   }
}' "https://api.cloud.wowza.com/api/[version]/live_streams"

The command creates a live stream with an id parameter, an associated player, and a hosted page. The details of live stream's configuration are listed in the response. You'll use the connection code or the source connection information to configure the Wowza GoCoder app as a source for the live stream.

{
    "live_stream": {
        "id": "abcntjvl",
        "name": "MyLiveStream",
        "transcoder_type": "transcoded",
        "billing_mode": "pay_as_you_go",
        "broadcast_location": "us_west_california",
        "recording": false,
        "closed_caption_type": "none",
        "low_latency": false,
        "encoder": "wowza_gocoder",
        "delivery_method": "push",
        "delivery_protocol": "hls-https",
        "target_delivery_protocol": "hls-https",
        "use_stream_source": false,
        "aspect_ratio_width": 1920,
        "aspect_ratio_height": 1080,
        "connection_code": "07yqLI",
        "connection_code_expires_at": "2018-10-17T14:39:50.000Z",
        "delivery_protocols": [
            "rtmp",
            "rtsp",
            "wowz",
            "hls"
        ],
        "source_connection_information": {
            "primary_server": "[wowzasubdomain].entrypoint.cloud.wowza.com",
            "host_port": 1935,
            "application": "app-8f5c",
            "stream_name": "4d3db5e1",
            "disable_authentication": false,
            "username": "client2",
            "password": "cde44772"
        },
        "player_id": "ly4rnpyt",
        "player_type": "wowza_player",
        "player_responsive": true,
        "player_countdown": false,
        "player_embed_code": "in_progress",
        "player_hls_playback_url": "https://[wowzasubdomain].akamaihd.net/hls/live/620367/be4fb5a4/playlist.m3u8",
        "hosted_page": true,
        "hosted_page_title": "MyLiveStream",
        "hosted_page_url": "in_progress",
        "hosted_page_sharing_icons": true,
        "stream_targets": [
            {
                "id": "jjwwxxpk"
            }
        ],
        "direct_playback_urls": {
            "rtmp": ["names, output_ids, and urls returned here"],
            "rtsp": ["names, output_ids, and urls returned here"],
            "wowz": ["names, output_ids, and urls returned here"]
        },
        "created_at": "2018-10-16T14:39:50.000Z",
        "updated_at": "2018-10-16T14:39:50.000Z"
    }
}

Configure the source


Use the connection code or the source connection information from the live stream you created to configure the Wowza GoCoder mobile app.

First, download the free Wowza GoCoder app for iOS from the Apple Store or for Android from Google Play.

Connect the GoCoder app using a connection code

The easiest connection method is using the connection code value returned when you created the live stream with the REST API.

  1. Start the GoCoder app on your mobile device.
     
  2. Tap the Connect icon (the Wowza gear).
  3. In the Connect To menu, tap Wowza Streaming Cloud.

  1. For Connection Code, enter the Wowza Streaming Cloud live stream's connection code, for example, 0ab334.

  1. Tap Done.

Connect the GoCoder app manually

To manually configure the app, use the live stream's source connection information from the REST API response to connect the app to Wowza Streaming Cloud. This connection method is useful for troubleshooting a connection with a connection code that isn't working as expected.

  1. Start the GoCoder app on your mobile device.
     
  2. Tap the Connect button (the Wowza gear icon) in the upper-right corner of the app.
     
  3. In the Connect To menu, tap Wowza Streaming Engine.

  1. Tap Host. For Server enter the primary_server value from your Wowza Streaming Cloud live stream (without rtsp:// at the start of the URL). For Port enter the live stream's host_port value. Then, tap Back.

  1. Tap Application, enter the application and stream_name values, and then tap Back.

  1. Tap Source Authentication and enter the username and password values.

  1. Tap Done.
Note: You can connect to Wowza Streaming Cloud using a number of different sources. See these articles for more information:

Start the live stream


When the live stream is created and the source is configured, use the PUT method to start it. Wowza Streaming Cloud will transcode the stream coming from the source and send it to the player for viewing on the hosted page.

Start the live stream:

curl -X PUT --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/live_streams/[live_stream_id]/start"

View the stream on the hosted page


  1. Initially, after creating the live stream using the REST API, the information in the response for the hosted page URL shows that it's "in progress." To find the URL, use the GET method to retrieve the live stream's details.

    Get details about the live stream:
     
    curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/live_streams/[live_stream_id]"
  2. Enter the hosted_page_url value into a browser to open the hosted page and view the live stream.

Stop the live stream


After viewing the live stream on the hosted page, use the PUT method to stop it.

Stop the live stream:

curl -X PUT --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/live_streams/[live_stream_id]/stop"
Note: Transcoding charges accrue for started live streams even if they aren't actively streaming content. Wowza Streaming Cloud automatically stops idle live streams after 20 minutes, but you should stop your stream as soon as your event ends to avoid accruing unnecessary charges.

More resources