Uploading files with API
Upload any file type from a variety of sources using Uploadcare’s flexible Upload API.
Once uploaded, files are:
- Stored in your project’s storage.
- Instantly available via Uploadcare CDN using secure, unguessable URLs.
- Accessible for further processing or delivery.
Each file belongs to a project — an isolated environment with its own API keys and settings.
Projects
All files are uploaded into the projects. Projects are separate environments with unique sets of API keys, dedicated storage, and settings.
For example, projects can be used to separate development, staging, and production environments. Learn more about projects.
File storing behavior
When uploading files, you can specify whether you want to keep them permanently or not.
Notice the UPLOADCARE_STORE
parameter in the example above.
It can be set as follows:
0
— the file will be deleted after 24 hours.1
— the file will be stored permanently until explicitly deleted.auto
— defers the choice of storage behavior to the project’s auto-store setting (which is ON by default).
If you don’t specify UPLOADCARE_STORE
parameter, the default value is auto
.
Note: Before, the value was 0
by default.
Learn more about storing behavior.
Billing
Learn how we charge for uploading operations.
Note: Only image uploads are available on the Free plan. To upload other file types besides images, you will need to add a credit card to your account for Know Your Customer (KYC) principles, but as long as you are on the free plan, you will not be charged.
Request and response
When you upload a file:
cURL
JavaScript
PHP
Python
Ruby
Swift
Kotlin
you immediately receive the file’s UUID in a 200 response:
and the file immediately becomes available on our CDN:
Save this UUID into your database and retrieve it to:
- Serve optimized and transformed images.
- Encode videos based on their size and codec.
- Organize them with arbitrary metadata.
- Detect the type of content.
Learn more about Upload API.
Upload local file
The simplest way to upload a local file is to perform a HTTP POST request. As in the example above, you only need to specify the project’s public key. Direct file uploads support files smaller than 100 MiB only. (If you want to upload larger files, please use multipart uploads instead).
cURL
JavaScript
PHP
Python
Ruby
Swift
Kotlin
Check out detailed API reference for direct uploads.
Upload from URL
Uploadcare can fetch a file from a publicly available URL and upload it to your project.
cURL
JavaScript
PHP
Python
Ruby
Swift
Kotlin
Check out detailed uploads from URL API reference.
Requests to the endpoint return a JSON dictionary with a token that can be
further used to check the status of an upload request. The token is not a
file ID and can’t be used to address the file directly. The actual file ID
should be retrieved by calling the /from_url/status/
endpoint.
Integration implementation may vary, please refer to the respective documentation.
cURL
JavaScript
PHP
Python
Ruby
Swift
Kotlin
Check out detailed API reference for uploads from URL.
Duplicates prevention
By default, every request to the /from_url/
endpoint with the same
source_url
results in a new upload leading to file duplication.
If you would like Uploadcare to keep track of the requested URLs and avoid
duplicate uploads, pass the save_URL_duplicates
and check_URL_duplicates
parameters described in uploads from URL API reference.
cURL
JavaScript
PHP
Python
Ruby
Swift
Kotlin
If the source_url
had already been fetched and uploaded previously, this
request would return information about the already uploaded file.
Upload large file
Multipart uploads should be used if you need to upload files larger than 100 MiB or if you want to explicitly trigger AWS S3 Transfer Acceleration.
cURL
JavaScript
PHP
Python
Ruby
Swift
Kotlin
Check out detailed API reference for multipart uploads.
Note: Each uploaded part should be at least 5242880 bytes in size except for the last one, which can be smaller. You can upload the file parts in parallel, provided that the byte order stays unchanged.
Add arbitrary metadata
You can add additional, arbitrary key-value data associated with uploaded files. For example, you could store user IDs, order IDs, or tags.
cURL
JavaScript
PHP
Python
Ruby
Swift
Kotlin
Learn more about file metadata.
Get file info
There’re various methods to get file information: via Upload API file info, REST API file info, or URL API file info. Upload API gives you limited but essential access, while REST API gives full details. Integration implementation may vary, please refer to the respective documentation.
cURL
JavaScript
PHP
Python
Ruby
Swift
Kotlin
Check out detailed API reference for file info.
Remote uploading method
You can upload remote files on the fly with Proxy.
Proxy automatically retrieves files from existing remote locations and delivers them using Uploadcare CDN. It’s easy to integrate, requiring only one URL modification: