The TON (Twitter Object Nest) API allows implementers to upload media and various assets to Twitter. In this document we will cover authentication & authorization, usage, principles, and provide examples to get started.
Please consult with your Platform Relations representative or Ads API Partner Engineer on details specific to your integration; the below information may not be true for your integration. This document covers upload only. The TON API supports other operations but they are not covered in this document, as they are not needed for the upload API.
The TON API supports non-resumable and resumable upload methods based on the size of the file. For files less than 64MB, non-resumable may be used. For files greater than or equal to 64MB, resumable must be used. Resumable uploads require chunk sizes of less than 64MB. Calculation of 64MB is based on 1024 bytes (64 * 1024 * 1024).
If your dedicated upload bandwidth for the TON Upload is less than ~20 Mbit/s we recommend using resumable upload even for files less than 64MB in size.
- The endpoint for the TON API is
- All requests must be made over HTTPS
- All responses are in
- The Content-Type of your request cannot be
- The Content-Type of your request will be a valid media type as defined by IANA: http://www.iana.org/assignments/media-types/media-types.xhtml
- Chunks should be in integer multiples of
X-TON-Min-Chunk-Size(except the last).
Locationheader after upload should be saved to be used in subsequent Twitter APIs, such as the Video API.
For Tailored Audiences, please use the bucket name
Note that the
ta_partner bucket also requires the
header to be set with an expiration date up to 7 days from the current
date (see the
script for more detail). For all other TON API buckets, this header is
optional however it’s safe and a good practice to pass this header all
the time and buckets that do not require it will simply ignore it.
Each bucket can be configured to support additional requirements. To confirm requirements for other features using the TON API, please refer to the documentation of that feature.
Included below are several examples on how to get started using the TON
API. Please note that your Application ID must be whitelisted for the
bucket that you are attempting to use.
Twurl is a Ruby gem that is like
curl, but tailored specifically for the Twitter API. Once
configured, it can be used to make requests similar to
An example non-resumable request:
twurl -t -H ton.twitter.com /1.1/ton/bucket/product_bucket_name -X POST -A "Content-Type: image/jpeg" -A "Content-Length: 136" --data "MY PRECIOUS BYTES"
You can find a sample Ruby TON upload script that depends on Twurl here.