# Upload an asset with the Wowza Video REST API (1.x legacy 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. Info - This topic only applies to version 1.x of the REST API. - You must obtain a license for the Asset Manager as part of a Wowza Video subscription to add this capability to your account. Contact us 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](/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 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. Info 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. 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. Info 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'; ``` Info 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: ![log file](/assets/log-file-2.eaa18c8ac49266dd2d609d248bac5aa120b176ed3fc5cbf8245f9e92ed0c7217.71a4f21c.png) ## 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" } } ```