Skip to main content
From creating the video object to sending the actual video content, you’ll learn how to complete the process smoothly.

​
What You’ll Need

Before you begin, ensure you have: A video library already created. It can be done via Dashboard (Follow “Step 1” in the Stream Quickstart 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 the Stream API Reference 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.

​
Understanding the Upload Process

Uploading a video through the HTTP API involves two main steps:
  1. Create the video object in your library (metadata and title).
  2. Upload the video file in binary format using a PUT request.

​
Creating a Video

Before uploading any video content, you must first create a video object in your library. This step is often overlooked, so please ensure it’s completed before proceeding with the upload.
This step tells Bunny Stream that you’re about to upload a new video and gives it a title and optional metadata. It doesn’t upload the video yet, just sets up the “slot” for it.
You can find full details about the available parameters in the Stream API Reference.

​
How to Create a Video:

Make an authenticated POST request to the following endpoint: 
POST https://video.bunnycdn.com/library/:libraryId/videos
Headers:
  • AccessKey: Your Stream API key
  • Accept: application/json
  • Content-Type: application/json
Body Parameters:
  • title: The name of your video. This will appear in the library UI.
  • collectionId (optional): The ID of a collection in your library where this video should be placed.
  • thumbnailTime (optional): The time (in milliseconds) to use when extracting the main video thumbnail.
Example request: 
curl --request POST
  --url https://video.bunnycdn.com/library/:libraryId/videos
  --header 'AccessKey: <Your Stream Library API key>'
  --header 'accept: application/json'
  --header 'content-type: application/json'
  --data '{"title":"test"}'
Example Response: The response will return a new video object, including:
  • A unique videoId (guid)
  • The libraryId
  • Basic metadata such as title and creation date
At this stage, most fields (like encoding status or view count) will be empty or zero since the file hasn’t been uploaded yet. You’ll need the videoId from this response in the next step.

​
Uploading the Video File

Once the video object is created, you can proceed to upload the actual video file. Full API reference: Stream API Reference. Upload Endpoint: 
PUT https://video.bunnycdn.com/library/{libraryId}/videos/{videoId}
Required Parameters: libraryId: Your video library ID (retrieved as before). videoId: The unique ID returned when you created the video object. You can also find this ID in the Bunny dashboard under the “Video ID” field for any listed video. Example curl request: 
curl --request PUT
  --url <https://video.bunnycdn.com/library/><Your Library ID>/videos/<Your Video ID>
  --header 'AccessKey: <Your Stream Library API key>'
  --header 'accept: application/json'
  --data-binary '@path/to/your/video.mp4'
Example Response: 
{ "success": true, "message": "OK" }
This response indicates that the video was uploaded successfully. File Format Requirements: When uploading your video file, it must be sent as raw binary data, not encoded or wrapped in JSON. Don’t base64 encode the file Send the video as binary in the body of the request cURL Tip: Use the “—data-binary” flag to send the file correctly 
\--data-binary '@video.mp4'
If this step is skipped or misconfigured, the upload may silently fail or the video will not process correctly.

​
Fetching Videos from a Remote URL (Optional)

If you already have a video file hosted on another platform or server, bunny.net allows you to fetch it directly using a remote URL, saving you the trouble of downloading and re-uploading manually. The documentation link to this can be found in the Stream API Reference.
The URL you provide must be accessible by bunny.net’s fetch system. You can use the optional headers parameter to include custom HTTP headers with the fetch request, enabling authentication methods such as:
  • Basic Authentication (via the Authorization header)
  • Static API keys (via custom headers like X-API-Key or Authorization: Bearer <token>)
However, more advanced authentication mechanisms such as signed URLs, expiring tokens, or time-limited access links are not supported, as the fetch is performed as a single server-side request and cannot handle dynamic token generation or multi-step authentication flows.See the Fetch Video API Reference for details on the headers parameter.
Endpoint:
bash
POST <https://video.bunnycdn.com/library/{libraryId}/videos/fetch>
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://example.com/video.mp4>"}'
Once fetched, the video will be automatically added to your library and begin processing like a normal upload.

​
Queued Fetch Limit

The fetch API supports a limited number of queued fetch requests per user at a time; this limit may vary by region, time, current load, and other factors. If you exceed the limit before previous fetches complete, the API will return HTTP 429 (Too Many Requests). To avoid this, either wait for in-progress fetches to finish before submitting new ones, or implement retry logic with backoff when you receive a 429 response.