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 theThe 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.
- Passing no
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.
Request, example:
curl -F "UPLOADCARE_PUB_KEY=demopublickey" \
-F "uuid=67947755-1584-4e3f-902b-d4e2bf76a841" \
"https://upload.uploadcare.com/multipart/complete/?jsonerrors=1"
Response, multipart
Response, example:
{
"is_stored": true,
"done": 27796904,
"file_id": "67947755-1584-4e3f-902b-d4e2bf76a841",
"total": 27796904,
"size": 27796904,
"uuid": "67947755-1584-4e3f-902b-d4e2bf76a841",
"is_image": false,
"filename": "myfile.mp4",
"video_info": null,
"is_ready": true,
"original_filename": "myfile.mp4",
"image_info": null,
"mime_type": "video/mp4"
}