# Create an ABR stream and send it to a target with the Wowza Video REST API Learn how to use the REST API to ingest a single video encode into the Wowza Streaming Cloud™ service, transcode it to multiple adaptive bitrate renditions, and deliver the ABR output to a target, or destination. Then, learn how to programmatically start and stop the transcoder. ## Before you start You should be familiar with the following concepts: - **API authentication** **methods**. We use JSON web tokens for API authentication. See [Authentication](/docs/wowza-video/about-the-rest-api/authentication) for more information. - **Environment variables**. We use environment variables for the API version and your JWT in the cURL API request examples in this topic to make it easier for you to copy, paste, and run commands in your Terminal or Command Prompt window. If you don't set environment variables for these values, you'll need to manually enter the correct values in the code samples throughout this tutorial. See [Tools for testing the API](/docs/wowza-video/about-the-rest-api/api-overview#tools-for-testing-the-api) for instructions. ## 1. Create a transcoder Create a transcoder that receives the stream from a source encoder or file by sending a `POST` request to the `/transcoders` endpoint. You can use the following sample request, making sure to: - Set `protocol` to the ingest protocol you'll use. - Set `broadcast_location` to the region that's closest to your video source. - Change any values unique to your broadcast, using the API reference documentation as a resource. See the **Endpoint Reference** button below. #### Sample request Endpoint Reference ``` curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${WV_JWT}" \ -d '{ "transcoder": { "billing_mode": "pay_as_you_go", "broadcast_location": "us_west_california", "buffer_size": 4000, "delivery_method": "push", "low_latency": true, "name": "MyABRtranscoder", "protocol": "rtsp", "transcoder_type": "transcoded" } }' "${WV_HOST}/api/${WV_VERSION}/transcoders" ``` #### Sample response The response includes: - An `id` for the transcoder that you'll use for various requests, including starting and stopping the stream. - The details of the transcoder. There are currently no outputs (`"outputs": [ ]`); you'll create and configure these in a later step. ``` { "transcoder": { "application_name": "app-B8P6K226", "billing_mode": "pay_as_you_go", "broadcast_location": "us_west_california", "buffer_size": 4000, "closed_caption_type": none, "created_at": "2015-07-22T13:43:56.989", "delivery_method": "push", "delivery_protocols": [ "rtmp", "rtsp", "wowz", "webrtc" ], "direct_playback_urls": {...}, "disable_authentication": false, "domain_name": "[subdomain].entrypoint.cloud.wowza.com", "id": "1234abcd", "idle_timeout": 1200, "low_latency": true, "name": "MyABRtranscoder", "outputs": [], "password": "12345678", "playback_stream_name": "f8758cd3", "play_maximum_connections": 10, "protocol": "rtsp", "source_port": 1935, "stream_name": "1a2a3a4a", "stream_smoother": false, "suppress_stream_target_start": false, "transcoder_type": "transcoded", "updated_at": "2015-07-22T13:43:56.989", "username": "client1", "watermark": false } } ``` ## 2. Create the highest bitrate output for the transcoder Next, define the output renditions you want the transcoder to generate, starting with the highest bitrate rendition: a passthrough output that uses the source encoder's settings. #### Sample request Endpoint Reference ``` curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${WV_JWT}" \ -d '{ "output": { "video_codec": "passthrough", "audio_codec": "passthrough" } }' "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/outputs" ``` The response includes: - An `id` for the output rendition, which you will need to use if you would like to update an output rendition. - The details of the output. There are currently no targets (`"output_stream_targets": [ ]`); you'll create and configure these in a later step. #### Sample response ``` { "output": { "bitrate_audio": 0, "bitrate_video": 0, "created_at": "2015-07-28T11:01:26.044", "framerate_reduction": 0, "h264_profile": null, "id": "5678efgh", "keyframes": "follow_source", "name": "Video+Audio=Passthrough+Passthrough", "video_codec": "passthrough", "audio_codec": "passthrough", "output_stream_targets": [], "transcoder_id": "1234abcd", "updated_at": "2015-07-28T11:01:26.044" } } ``` ## 3. Create additional, lower bitrate outputs for the transcoder Now that you have created one output, you can create up to 9 additional outputs for the transcoder to generate. The maximum number of outputs you can add to a single transcoder is 10. Additional outputs should be transcoded to create lower-quality renditions than the passthrough output. Depending on the resolution of the passthrough, you might want to create three to five additional outputs. You can use the following sample requests, making sure to: - Specify the `aspect_ratio_height`, `aspect_ratio_width`, `bitrate_video`, and `profile` you want for your unique broadcast. - Change any additional values unique to your broadcast, using the API reference documentation as a resource. See the **Endpoint Reference** button below. Create a 480x848 output: Endpoint Reference ``` curl -X POST -H "Content-Type: application/json" \ -H "Authorization: Bearer ${WV_JWT}" \ -d '{ "output": { "audio_codec": "aac", "video_codec": "h264", "aspect_ratio_height": 480, "aspect_ratio_width": 848, "bitrate_audio": 128, "bitrate_video": 1700, "framerate_reduction": 0, "h264_profile": "main", "keyframes": "follow_source" } }' "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/outputs" ``` Create a 640x360 output: Endpoint Reference ``` curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${WV_JWT}" \ -d '{ "output": { "audio_codec": "aac", "video_codec": "h264", "aspect_ratio_height": 360, "aspect_ratio_width": 640, "bitrate_audio": 128, "bitrate_video": 1024, "framerate_reduction": 0, "h264_profile": "main", "keyframes": "follow_source" } }' "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/outputs" ``` Create a 512x288 output: Endpoint Reference ``` curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${WV_JWT}" \ -d '{ "output": { "audio_codec": "aac", "video_codec": "h264", "aspect_ratio_height": 288, "aspect_ratio_width": 512, "bitrate_audio": 128, "bitrate_video": 512, "framerate_reduction": 0, "h264_profile": "baseline", "keyframes": "follow_source" } }' "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/outputs" ``` Create a 320x188 output: Endpoint Reference ``` curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${WV_JWT}" \ -d '{ "output": { "audio_codec": "aac", "video_codec": "h264", "aspect_ratio_height": 188, "aspect_ratio_width": 320, "bitrate_audio": 128, "bitrate_video": 320, "framerate_reduction": 0, "h264_profile": "baseline", "keyframes": "follow_source" } }' "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/outputs" ``` ## 4. Create a stream target for the outputs Next, configure a stream target to define the destination for the output renditions. You can use one of the following stream targets: - [Custom stream target](#custom-stream-target) — Delivers the stream to a third-party CDN. - [Wowza CDN on Fastly stream target](#wowza-cdn-on-fastly-stream-target) — Delivers the stream to Wowza CDN using Fastly. ### Custom stream target A custom stream target is a destination that allows you to leverage a third-party CDN. You can use the following sample request, making sure to: - Set `primary_url` to the primary RTMP ingest URL of the destination, for example `[targetdomain].com/application`. - Set `username` and `password` to the username/ID and password associated with the target username for RTMP authentication. - Set `provider` to the value for the CDN you're using. - Set `stream_name` to the name of the stream as defined in the target's ingestion settings. - Change any values unique to your broadcast, using the API reference documentation as a resource. See the **Endpoint Reference** button below. #### Sample request Endpoint Reference ``` curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${WV_JWT}" \ -d '{ "stream_target_custom": { "name": "MyCustomTarget", "password": "secret", "primary_url": "rtmp://[targetdomain].com/application", "provider": "rtmp", "stream_name": "1a2b3c4d", "username": "123456" } }' "${WV_HOST}/api/${WV_VERSION}/stream_targets/custom" ``` #### Sample response ``` { "stream_target_custom": { "backup_url": "rtmp://[backuptargetdomain].com/application", "created_at": "2015-07-28T11:01:45.044", "id": "9123wxyz", "name": "MyCustomTarget", "password": "secret", "delivery_protocols": [ "rtmp" ], "playback_urls": {}, "primary_url": "rtmp://[targetdomain].com/application", "provider": "rtmp", "stream_name": "1a2b3c4d", "updated_at": "2015-07-28T11:01:45.044", "username": "123456" } } ``` ### Wowza CDN on Fastly stream target A Wowza CDN on Fastly stream target is a destination that uses Wowza CDN to deliver the stream to players. We recommend using Wowza CDN on Fastly stream targets for new stream configurations. Advanced properties are available for Wowza CDN on Fastly stream targets. You can use the following sample request, making sure to: - Change any values unique to your broadcast, using the API reference documentation as a resource. See the **Endpoint Reference** button below. #### Sample request Endpoint Reference ``` curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${WV_JWT}" \ -d '{ "stream_target_fastly": { "name": "My first Wowza CDN on Fastly target" } }' "${WV_HOST}/api/${WV_VERSION}/stream_targets/fastly" ``` #### Sample response The response includes: - An ID for the stream target that you'll use in step 3 to assign the stream target to the transcoder. ``` { "stream_target_fastly": { "id": "lwzgrj9r", "name": "My first Wowza CDN on Fastly target", "state": "activated", "stream_name": "ZmYxSXRrTERrUlk9", "playback_urls": { "hls": [ { "name": "default", "url": "https://[subdomain].wowza.com/1/[stream_id]/[stream_name]/hls/live/playlist.m3u8" } ] }, "token_auth_enabled": false, "token_auth_playlist_only": false, "geoblock_enabled": false, "geoblock_by_location": "disabled", "geoblock_ip_override": "disabled", "force_ssl_playback": false, "created_at": "2021-07-22T16:38:21.000Z", "updated_at": "2021-07-22T16:38:21.000Z" } } ``` ## 5. Add the stream target to each output Now that you have created a stream target for each output, you can add the stream target to each output rendition. #### Sample request Endpoint Reference ``` curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${WV_JWT}" \ -d '{ "output_stream_target": { "stream_target_id": "9123wxyz", "use_stream_target_backup_url": false } }' "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/outputs/[output_id]/output_stream_targets" ``` #### Sample response ``` { "output_stream_target": { "stream_target_id": "9123wxyz" "use_stream_target_backup_url": false } } ``` ## 6. Start and stop the transcoder When the transcoder, outputs, and targets are created, use the `PUT` method to start and stop the transcoder. Wowza Video will ingest the stream from the source, create the passthrough output and the lower-quality transcoded output renditions, and send all of the outputs to the target address. 1. Start the transcoder: Endpoint Reference ``` curl -X PUT \ -H "Authorization: Bearer ${WV_JWT}" \ "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/start" ``` 2. Stop the transcoder. Endpoint Reference ``` curl -X PUT \ -H "Authorization: Bearer ${WV_JWT}" \ "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/stop" ``` ## Related transcoder API requests - GET/transcoders/ID/state — View a transcoder's state. - GET/transcoders/ID — View the details of a transcoder. - PUT/transcoders/ID/enable_all_stream_targets — Start all of a transcoder's stream targets. - GET/transcoders/ID/thumbnail_url — View a transcoder's preview image. - DELETE/transcoders/ID — Delete a transcoder.