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 #

Required parameters #

You must provide the file's name and 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 #

Response format #

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": []
}