Skip to Content

TwentyThree

Browser-based uploads to the API

Browser-based uploading use of two API endpoints:

This approach is designed to allow API consumers to pre-authenticate uploads to their TwentyThree account. It enables applications to let users upload videos to TwentyThree directly from their browsers. This scheme allows you to accept uploads from users without ever having to proxy or host the files from your server. You should opt for this approach to uploading if you do not want to host or store the uploaded files.

1. Post upload meta data to TwentyThree

Start by posting title, description, album, tags and publish status to the API alongside a return_url where the user is returned after uploading the actual file:

https://videos.examples.com/api/2/photo/get-upload-token?
  title=My+title&
  album_id=12345&
  return_url=https://www.example.com/upload/callback?theme=green

This will return you an upload_token plus information about the exact meta data, about the expiration of the token and about how many times the token can be used:

{
    "status": "ok",
    "permission_level": "write",
    "cached": false,
    "message": "The upload token is ready to use",
    "data": {
        "description": "",
        "valid_minutes": 360,
        "album_id": 12345,
        "max_uploads": 1,
        "tags": "",
        "publish": "t",
        "absolute_url": "",
        "return_url": "https://www.example.com/upload/callback?theme=green",
        "title": "My title",
        "user_id": 61550003,
        "valid_until": 1712329635,
        "publish_date": "",
        "upload_token": "022fe6e3fb42758d6147c539727c5358af3524b1",
        "background_return_p": false,
        "token_tags": ""
    }
}

In this example, you're getting a token valid for one upload and for 3 hours.

2. Get the upload_token

From this returned information you will need to extract the upload_token. In this case, the token is:

022fe6e3fb42758d6147c539727c5358af3524b1

3. Build the HTML form using the upload_token

Using this token you can now build a simple HTML form for the user.

<form action="https://videos.example.com/api/2/photo/redeem-upload-token" 
  method="post" enctype="multipart/form-data">
  <input type="hidden" name="upload_token" value="022fe6e3fb42758d6147c539727c5358af3524b1" />
  <input type="file" name="file" />
  <input type="submit" value="Upload video" />
</form>

Of course, if you set the max_uploads parameter, you can also more advanced upload methods for uploading multiple files at once.

4a. Handle the call-back after the upload completes.

The callback URL is defined by the return_url parameter, and the callback request will always take the form of a HTTP 301 redirect to a GET-style address.

The request will always include the upload_token and domain as a parameter. If the upload succeeded, the parameters photo_id, token, tree_id will be included:

https://www.example.com/upload/callback?
  theme=green&
  domain=videos.example.com&
  upload_token=022fe6e3fb42758d6147c539727c5358af3524b1&
  photo_id=12345&
  tree_id=97531&
  token=mhpDudicFtdjz1isvidhnzsgqv3kaske

4b. Handle the call-back on upload errors

On upload failure, the user is sent to the same callback page. The request includes an error_message parameter alongside upload_token and domain. For example:

https://www.example.com/upload/callback?
  theme=green&
  domain=videos.example.com&
  upload_token=022fe6e3fb42758d6147c539727c5358af3524b1&
  error_message=The+file+type+isn't+supported