Uploads
If you want to upload a file into our temporary storage to then use in a subsequent API request, you need to request a URL to upload that file to.
POST /uploads
NOTE
If this ability is not enabled for your account or quotas have been hit, the request may be denied. You will see the returned error code and message if so.
Required parameters
You must provide the file's name
and size
.
Key | Type | Description |
---|---|---|
name | String | The file's name |
size | Number | The file's size |
The name
should have the appropriate extension to avoid issues later on. For example if you are uploading:
- a video? Its name should end with .mp4, .mov, .mpg, .wmv, .mkv
- a thumbnail image? Its name should end with .jpg
- a captions/subtitles WebVTT track? Its name should end with .vtt
The size
should be a number, in bytes. How to get that depends on your application but every language has a way to get a file's size. For example:
On a Mac/Linux, you can get that using stat -f%z example.jpg
.
With PHP, you can get that using filesize("example.jpg")
Example request
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"example.mp4", "size": 12345}' \
"https://api.vidbeo.com/v2/uploads"
Example response
{
"success": true,
"result": {
"id": "abcde12345abcde12345a",
"name": "example.mp4",
"size": 12345,
"key": "path/to/file.mp4",
"url": "https://example.com/path/to/file.mp4?...",
"created_by": "abcde12345abcde1234a",
"created_time": "2022-01-01T00:00:00.000Z",
"updated_by": "abcde12345abcde12345a",
"updated_time": "2022-01-01T00:00:00.000Z"
},
"links": null,
"errors": []
}
The important fields are url
and id
:
The url
is what you now upload your file to. It is only valid for a very short time.
The id
will be used in your subsequent API request to reference that file.
How do I upload to that URL?
Do a PUT
request to it, sending the binary data of the file in the body of the request.
How exactly that is done depends on your application. In our documentation we use the curl command line tool, so using that you would do:
curl -L -X PUT "THE-URL-GOES-HERE" --data-binary "@path/to/file.ext"
For example if you have an image called example.jpg in the same folder you are running the command from, you would do:
curl -L -X PUT "THE-URL-GOES-HERE" --data-binary "@example.jpg"
As another example, using the free Postman app/extension, the request type is PUT, the URL is of course the URL we provide, and then underneath make sure you have picked binary as the body (as shown below). Then select your file. And send the request:
Once the upload is complete, you send its id
in your subsequent API request like vidbeo://uploads/abcde12345abcde12345
. As:
- the input in POST /videos
- the url in POST /videos/:id/thumbnail
- the url in POST /videos/:id/tracks
GET /uploads
Since upload URLs are temporary we will automatically delete records of older ones.
Example request
curl \
-H "Authorization: Bearer YOUR-API-KEY" \
"https://api.vidbeo.com/v2/uploads"
Example response
{
"success": true,
"result": [
{
"id": "abcde12345abcde12345a",
"name": "example.mp4",
"size": 12345,
"key": "path/to/file.mp4",
"url": "",
"created_by": "abcde12345abcde1234a",
"created_time": "2022-01-01T00:00:00.000Z",
"updated_by": "abcde12345abcde12345a",
"updated_time": "2022-01-01T00:00:00.000Z"
},
...
],
"links": {},
"errors": []
}
Optional parameters
Name | Type | Default | Information |
---|---|---|---|
limit | String | 25 | Maximum number to return |
cursor | String | "" | Used to get the next page of results: if applicable we return this as part of the links.next URL |
Response format
Key | Type | Description |
---|---|---|
id | String | The unique identifier given to this upload |
name | String | The name of the uploaded file (e.g "example.mp4") |
size | Number | The size of the uploaded file |
key | String | The generated path to the temporary file we will store |
url | String | The temporary authorization URL to upload your file to in a PUT request |
created_by | String | The ID of the user who created it (if known) |
created_time | String | The date and time it was created |
updated_by | String | The ID of the user who last modified it (if known) |
updated_time | String | The date and time it was last modified |
DELETE /uploads/:id
Note: The uploaded file (if one was uploaded using the URL) is automatically deleted separately.
Example request
curl \
-H "Authorization: Bearer YOUR-API-KEY" \
-X DELETE \
"https://api.vidbeo.com/v2/uploads/abcde12345abcde12345a"
Example response
{
"success": true,
"result": {},
"links": null,
"errors": []
}