Uploading Files via Requests

Upload API provides uploading files by making requests with payload to our endpoints. There are two basic types:

Direct Uploads, a regular upload mode that suits most files less than 100MB in size. You won’t be able to use this mode for larger files.
Multipart Uploads, a more sophisticated uploading mode supporting any files larger than 10MB and implementing accelerated uploads through a distributed network.

Note, when using Uploadcare File Uploader, you can define which upload mode will be used based on a file size threshold set by the data-multipart-min-size file uploader option.

Direct Uploads

Direct Uploads comply with the RFC 7578 standard and work by making POST requests via HTTPS to:

https://upload.uploadcare.com/base/

Direct Uploads only support files smaller than 100MB. An attempt of handling a larger file raises a 413 error with the respective description. If you want to upload larger files via Upload API, refer to Multipart Uploads.

Request parameters

UPLOADCARE_PUB_KEY, `string`

Defines a public key identifying an Uploadcare project your uploads will go to. You can get one by signing up for Uploadcare. Another option is using demopublickey for testing purposes. However, you should be aware we wipe out all files from our demo account every few hours.

UPLOADCARE_STORE

Sets the file storing behavior. In this context, storing a file means making it permanently available. The opposite to it is automatically deleting your file after a 24-hour period. Accepted values are:

0 or not set, files do not get stored upon uploading.
1, files get stored upon uploading. Requires the “automatic file storing” setting to be enabled.
auto, file storing behavior follows your “automatic file storing” project settings.

(other)

Files as form data, any field names will do. You are free to send many files at once. Just make sure their total size does not exceed 100MB. Refer to RFC 7578 for details on sending multiple files as form data.

Response

With Direct Uploads, in a response, you get a JSON dictionary where keys relate to file field names, and their values hold the respective file UUIDs. Here is an example,

Request:

curl -F "UPLOADCARE_PUB_KEY=demopublickey" \
     -F "UPLOADCARE_STORE=1" \
     -F "file=@image.jpeg" \
     "https://upload.uploadcare.com/base/"

Response:

{
  "file": "17be4678-dab7-4bc7-8753-28914a22960a"
}

Multipart Uploading

Multipart Uploading is useful when you are dealing with files larger than 100MB or explicitly want to accelerate the uploading process.

Another benefit is your file will go straight to AWS S3 bypassing our upload instances thus quickly becoming available for further use.

Note, there also exists a minimum file size to use with Multipart Uploads, 10MB. Trying to use Multipart Uploads with a smaller file will result in an error.

Requests, multipart

Each multipart upload is a three-phase transaction.

Starting a multipart upload transaction

A multipart upload is started by making a request to the /multipart/start/ endpoint:

https://upload.uploadcare.com/multipart/start/

You should pass the following parameters in the request:

filename, required, stands for an original filename. If not sent, an error is raised, The "filename" parameter is missing.
size, required, stands for a precise file size in bytes. Should not exceed your project file size cap.
- Passing no size parameter raises the The provided "size" should be an integer. error.
- When size exceeds your project file size cap, File size exceeds your project limits, see Uploadcare pricing for details.
- When size is below the 10MB limit set for Multipart Uploads, File size should not be less than 10485760 bytes. Please use Direct Uploads instead.
content_type, required, a file MIME-type. If not provided, an error is raised, The "content_type" parameter is missing.
UPLOADCARE_STORE, sets if an uploaded file should be stored, see the corresponding Direct Uploads section for details.

With Multipart Uploads, in a response, you get a JSON holding your uploaded file UUID along with the pre-signed AWS upload URLs where file parts should go to.

Request, example:

curl -F "UPLOADCARE_PUB_KEY=demopublickey" \
     -F "filename=myfile.mp4" \
     -F "size=27796904" \
     -F "content_type=video/mp4" \
     -F "UPLOADCARE_STORE=auto" \
     "https://upload.uploadcare.com/multipart/start/?jsonerrors=1"

Response, example:

{
  "parts": [
    "<presigned-url-1>",
    "<presigned-url-2>",
    "<presigned-url-3>",
    "<presigned-url-4>",
    "<presigned-url-5>",
    "<presigned-url-6>",
  ],
  "uuid": "67947755-1584-4e3f-902b-d4e2bf76a841"
}

Uploading individual file parts

The second phase is about uploading file parts to the provided AWS S3 URLs. Each uploaded part should be 5MB (5242880 bytes) in size except for the last one that can be smaller.

You can upload file parts in parallel provided the byte order stays unchanged.

File parts should be uploaded by making PUT requests to the provided URLs. Make sure to define Content-Type for your data. Here is an example,

curl -X PUT \
     -H "Content-Type: video/mp4" \
     -d chunk_01 \
     "https://uploadcare.s3-accelerate.amazonaws.com/<presigned-url-1>"

Completing a multipart upload

Once all file parts have been uploaded to the provided AWS URLs, you should make a request to the /multipart/complete/ endpoint to complete the multipart upload transaction:

https://upload.uploadcare.com/multipart/complete/

The only parameter you need to pass here is the uuid you got in response to a request made to /multipart/start/.

However, there are some errors raised in case you provide invalid parameters:

No uuid was supplied in a request, The "uuid" parameter is missing.
If the provided uuid does not exist, 404 File not found.
If a file has already been uploaded to S3 via Direct Uploads, File has already been uploaded, try addressing it via UUID.
Total size of uploaded file parts exceeds size, Total size of uploaded file parts exceeds original file size.
Total size of uploaded file parts is smaller than size, Total size of uploaded file parts is smaller than original file size.
If an error occurred when addressing S3 to complete an upload, Could not complete your upload. Consider checking file part sizes.