This guide provides step-by-step instructions for uploading videos to our platform using the HTTP API. It covers everything from obtaining the necessary API key to uploading video content, ensuring a smooth and successful video upload process. Before proceeding with this guide, please make sure you have created a video library as this is a prerequisite for video upload.
What you'll need
Before you dive in, make sure you have the following prerequisites in place:
- A bunny.net account (Log in or sign up for a free trial).
- A video library already created. It can be done via Website (Follow "Step 1" in the guide Uploading your first video through our website to create a video library. An incorrect library ID will result in upload failure) or via API (use the "Add Video Library" HTTP call explained in our Add Video Library - docs.bunny.net guide).
- Have your Stream API key prepared. To learn how to obtain your stream API key, see How to obtain your Stream API key guide.
Creating a video
Before uploading any video content, you must first create a video object. This is a common oversight, so ensure you've completed this step.
The exact parameters can be found on our documentation website found here: Create Video - docs.bunny.net.
To create a video, make an authenticated POST request:
POST https://video.bunnycdn.com/library/{libraryId}/videos
Body parameters:
- LibraryID -Your libraryID can be returned via the 'List Video Libraries' API call found here: List Video Libraries - docs.bunny.net.
- The title of the video is what you would like the title of your video upload to be, the collectionId parameter is if you wish to upload the video to a specific collection ID. (body parameter)
Path parameters:
- Title - The title of the video is what you would like the title of your video upload to be, the collectionId parameter is if you wish to upload the video to a specific collection ID. (body parameter)
- collectionId - The ID of the collection where the video will be put
- thumbnailTime - Video time in ms to extract the main video thumbnail.
Example request:
curl --request POST \
--url https://video.bunnycdn.com/library/<Your Library ID>/videos \
--header 'AccessKey: <Your Stream Library API key>' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{"title":"test"}'
The response shows a newly created video object with its unique video ID (guid), library ID, and basic attributes like title and upload date. Initially, most properties, such as views, dimensions, and encoding status, are set to zero or null, indicating the video is yet to be processed or viewed.
(Video ID is needed in the next step to start uploading).
Uploading the video
Now you have created a library and a video, it is time to upload the actual video content. The parameters for this can be found here: Upload Video - docs.bunny.net.
To upload your video, make an authenticated PUT request:
PUT https://video.bunnycdn.com/library/{libraryId}/videos/{videoId}
Required parameters:
- LibraryID -Your libraryID can be returned via the 'List Video Libraries' API call found here: List Video Libraries - docs.bunny.net.
- The videoId can be located within the video card itself in our control panel under 'Video ID' - or if created via our API, the 'guid' response would be the videoId.
Example Request:
curl --request PUT \
--url https://video.bunnycdn.com/library/<Your Library ID>/videos/c9a07aa6-9bf3-4190-8e17-54a4f9bbfa71 \
--header 'AccessKey: <Your Stream Library API key> ' \
--header 'accept: application/json'
The example response for the Upload Video endpoint indicates a successful video upload, denoted by "success": true, with a status message of "OK" and a HTTP status code of 200.
🚧 What type of data needs to be added as the file body
Please note that the file body needs to be the video object itself in an unencoded binary format. You will not be able to upload an encoded mp4 file for example, if using cURL the binary of a file can be passed using the --data-binary parameter.
Fetching videos
We understand that some customers may wish to fetch an encoded copy of a video from a 3rd party source, for example a file storage platform or a web server. We have built in an API call for this called 'Fetch Video' which will allow you to do this. The documentation link to this can be found here: Fetch Video - docs.bunny.net.
To fetch your video, make an authenticated POST request:
POST https://video.bunnycdn.com/library/{libraryId}/videos/fetch
Required parameters:
- Your libraryID can be returned via the 'List Video Libraries' API call found here: List Video Libraries - docs.bunny.net.
- The url parameter will allow you to enter a remote URL for our API to grab the encoded video from and then pass to the Stream platform.
Example Request:
curl --request POST \
--url https://video.bunnycdn.com/library/<Your Library ID>/videos/fetch \
--header 'AccessKey: <Your Stream Library API key> ' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"url": "https://test.video.mp4"
}
Need help or encountering issues?
If you encounter any difficulties or have questions while following this Quickstart Guide, our support team is here to assist you. Please don't hesitate to contact us via support request form for prompt assistance.
Our dedicated support team is ready to help you resolve any issues you might face during the deployment process, provide additional guidance, or answer your questions.