Upload an asset with the Wowza Video REST API

The Wowza Video™ Asset Manager allows users to ingest, store, and tag video content in order to centralize, reuse, amplify, and provide user-friendly access to assets. See Video CMS: What it is and why you need one for more information.

You must obtain a license for the Asset Manager to add this capability to your new or existing account. Contact sales@wowza.com for more information.

This article demonstrates how to upload .mp4 files to the Wowza Video Asset Manager using the Wowza Video REST API.

Before you start

---

You should be familiar with the following concepts:

• API authentication methods. We use JSON web tokens for API authentication. See 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 for instructions.

1. Create an asset

Add assets to the Wowza Video Asset Manager by sending a POST request to the /assets endpoint. Keep in mind, you can only upload MP4 format and H.264 and AAC encoded files. Any files with unsupported codecs are rejected.

You can update the asset to have a description and tags once the asset has finished transcoding.

You can use the following sample request, making sure to:

• Set file_name to the name of the .mp4 file you are uploading. We also encourage you to use only these characters in your file name:
  • Letters: A-Z, a-z
  • Numbers: 0-9
  • Special characters: _ - . ()
    
    
    If there are any other characters in the file name, we'll replace or remove them to avoid file management issues in storage.

Sample request

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
   "asset": {
     "file_name": "asset1.mp4"
   } 
}' "${WV_HOST}/api/${WV_VERSION}/assets"

Sample response

The response includes:

• An id for the asset that you'll use to complete other actions on the asset.
• An upload_url for the asset that you'll use in step 2 to upload the asset to the Wowza Video Asset Manager.
   

  Note: The URL is set to expire in 300 seconds. Typically, this is sufficient time when you're running built code, but if you're manually walking through these steps to see the workflow, you might encounter this expiration between this step and the next. If you do, you'll need to make this call again for a new upload URL with a new expiration.

{
    "asset": {
        "created_at": "2020-01-29T17:16:21.956Z"
        "id": "abcntjvl",
        "file_name": "asset1.mp4",
        "upload_url": "https://objectstorage.us-ashburn-1.oraclecloud.com/p/k9bGRcyPFPtdeQeTRgAVTByIVVS0Z_EKrLBu3TusTrRfBuIpoDyio_ZY3qJM55tp/n/a1b2c3d4e5f6/b/recordings-qa-S7I69eYn/o/uploads/recording_bry7vv0s/asset1.mp4"
    }
}

2. Upload the asset

You can upload the file with the cURL --upload-file option. 

Note: You can only upload MP4 format and H.264 and AAC encoded files. Any files with unsupported codecs are rejected.

You can use the following sample request, making sure to:

• Set upload_url to the upload_url returned when you created the asset.
• Set file_path to the location on your computer for the file you would like to upload.
  
  For example, ~/Downloads/MyFile.mp4

Sample request

curl -X PUT -H 'Content-Type: video/mp4' --upload-file file_path 'upload_url'

This is the sample request using the file_path and upload_url from the previous step:

curl -X PUT -H 'Content-Type: video/mp4' --upload-file MyFile.mp4 'https://objectstorage.us-ashburn-1.oraclecloud.com/p/k9bGRcyPFPtdeQeTRgAVTByIVVS0Z_EKrLBu3TusTrRfBuIpoDyio_ZY3qJM55tp/n/a1b2c3d4e5f6/b/recordings-qa-S7I69eYn/o/uploads/recording_bry7vv0s/MyFile.mp4;

Tip: If you are manually walking through these steps and would like additional error reporting as well as a visual indicator on the command line regarding upload status, you can append a log-to-file command to the cURL request above: >log_file.out

You'll get a log file written locally and upload status in the command line while the file is uploading, like:

3. Notify the Wowza Video Asset Manager that the upload has completed

Once the upload has completed, you need to notify the Wowza Video Asset Manager by sending a PATCH request to the /assets/{id}/upload_completed endpoint.

You can use the following sample request, making sure to:

• Set duration to the length of the asset.

Sample request

Endpoint Reference

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
   "asset": {
     "duration": 30
   } 
}' "${WV_HOST}/api/${WV_VERSION}/assets/{id}/upload_completed"

4. Check the status of your asset

Once you notify the Wowza Video Asset Manager that your upload has completed, your asset will begin transcoding. This may take several minutes. You'll need to check that the state of your asset is "complete" before you can add tags and a description to your asset. Send a GET request to the /assets/{id} endpoint to check the state of the asset.

You can use the following sample request, making sure to:

• Set id to the ID of the asset returned in Step 1.

Sample request

Endpoint Reference

curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_VERSION}/assets/{id}"

Sample response

The response includes:

• The state of the asset. The state can be returned as "uploading," "processing," "removing," "completed," or "failed." The state must be returned as completed before you can add a description and tags to your asset.

{
    "asset": {
        "id": "abcntjvl",
        "name": "asset1.mp4",
        "created_at": "2020-01-29T17:16:21.956Z",
        "updated_at": "2022-03-30T16:44:46.499Z",
        "published": false,
        "thumbnail_url": "https://objectstorage.us-ashburn-1.oraclecloud.com/n/idcrz33q3xdo/b/recordings-qa-S7I69eYn/o/abcd1234/recording_0pfxrlw2/0pfxrlw2_thumbnail.jpg",
        "state": "processing",
        "processing_percentage": 0.0,
        "file_size": 1570024,
        "playback_url": "https://cdn3-qa.wowza.com/2/aXo2QTd0Y05WMGkw/M2gyUWVV/hls/cfvvbphl/playlist.m3u8",
        "download_url": "https://objectstorage.us-ashburn-1.oraclecloud.com/n/idcrz33q3xdo/b/recordings-qa-S7I69eYn/o/abcd1234/recording_0pfxrlw2/asset1.mp4",
        "file_name": "test1.mp4",
        "description": null,
        "available_renditions": [],
        "duration": 30,
        "tags": [],
        "unique_viewers": 0,
        "total_viewing_time": 0,
        "average_view_time": 0,
        "total_storage_size": 1570024,
        "vod_stream_id": "cfvvbphl",
        "recording_id": "hw07v2r9"
    }
}

5. Publish your asset

Once your asset is uploaded and transcoding has been completed, you can set your asset to enable playback by sending a PATCH request to the /assets/{id} endpoint. Publishing the asset enables playback.

You can use the following sample request, making sure to:

• Set published to true.
• (Optional) Set description to a descriptive string for the asset. Descriptions can be up to 16,000 characters long.
• (Optional) Set tags to any descriptive tags you choose for the asset.

Sample request

Endpoint Reference

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
   "asset": {
     "published": true,
     "description": "This is my new asset.",
     "tags": ["new"], ["meetings"]
   } 
}' "${WV_HOST}/api/${WV_VERSION}/assets/{id}"

Sample response

{
    "asset": {
        "id": "abcntjvl",
        "name": "new name",
        "created_at": "2020-01-29T17:16:21.956Z",
        "updated_at": "2022-03-30T17:20:01.421Z",
        "published": true,
        "thumbnail_url": "https://objectstorage.us-ashburn-1.oraclecloud.com/n/idcrz33q3xdo/b/recordings-qa-S7I69eYn/o/abcd1234/recording_0pfxrlw2/0pfxrlw2_thumbnail.jpg",
        "state": "completed",
        "processing_percentage": 100.0,
        "file_size": 1570024,
        "playback_url": "https://cdn3-qa.wowza.com/2/ZFVwZk1DNGRmZi9s/SFk3R0lZ/hls/1t2vvfhn/playlist.m3u8",
        "download_url": "https://objectstorage.us-ashburn-1.oraclecloud.com/n/idcrz33q3xdo/b/recordings-qa-S7I69eYn/o/abcd1234/recording_0pfxrlw2/MyAsset.mp4",
        "file_name": "test1.mp4",
        "description": "This is my new asset.",
        "available_renditions": [
            {
                "height": 720,
                "width": 1280,
                "bitrate_kbps": 48486
            },
            {
                "height": 360,
                "width": 640,
                "bitrate_kbps": 17616
            },
            {
                "height": 432,
                "width": 768,
                "bitrate_kbps": 22070
            },
            {
                "height": 1080,
                "width": 1920,
                "bitrate_kbps": 102440
            },
            {
                "height": 540,
                "width": 960,
                "bitrate_kbps": 30778
            }
        ],
        "duration": 30,
        "tags": ["new"], ["meetings"],
        "unique_viewers": 0,
        "total_viewing_time": 0,
        "average_view_time": 0,
        "total_storage_size": 1570024,
        "vod_stream_id": "1t2vvfhn",
        "recording_id": "9zkmrv1b"
    }
}

Related API requests

• GET /assets — View all assets for an account.
• DEL /assets/[ID] — Delete an asset.
• PATCH /assets/id/upload_failed — Report a failed upload to Wowza Video.