Uploading

Uploading files

Whether you need to accept user generated content, serve media on your website or app, or collect and prepare files to train your ML model, we’ve got you covered.

Upload any file type from almost any source using various upload options. Uploadcare provides a robust, secure, and comprehensive Upload API that you and your users can access from your backend or directly from the browser. We also offer state-of-the-art web File Uploader and mobile widgets.

Every uploaded file is immediately available on Uploadcare CDN through unique and unguessable URLs. The files are stored in the integrated storage. Once uploaded, you can manage your files using the REST API and deliver them, applying on-the-fly operations.

Uploading basics

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.

Note: Image uploads are available on the Free plan. To upload other file types, you must add a credit card to your account according to “Know your customer” (KYC) principles, but as long as you stay on the free plan, you won’t be charged.

Upload API request and response

When you upload a file,

$curl -F "UPLOADCARE_PUB_KEY=$YOUR_PUBLIC_KEY" \
>     -F "UPLOADCARE_STORE=auto" \
>     -F "file=@sample-file.jpeg" \
>     "https://upload.uploadcare.com/base/"

you immediately receive the file’s UUID in a 200 response,

{
  "sample-image.jpeg": "17be4678-dab7-4bc7-8753-28914a22960a"
}

and the file immediately becomes available on our CDN.

https://ucarecdn.com/17be4678-dab7-4bc7-8753-28914a22960a/

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.

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.

Information about uploaded files

We can extract file data that you can use: from basic file information, e.g. EXIF, to insights into its content. We can automatically analyze files for things like malware or NSFW content. It also allows you to use MIME type moderation.

Check out files section in Dashboard to see it in action.

File Uploader

File Uploader is a new and highly customizable widget that allows users to upload files from various sources, utilizing the power of Uploadcare APIs.

If you’re looking for a ready-made uploading solution, look no further.

Uploading from the browser

If you need to build your own uploading solution and don’t want to use File Uploader, one of the options is to use our JS SDK. Upload Client works with both Node.js and browsers.

Uploading widgets for iOS and Android

Both Swift and Kotlin integrations have not only uploaded API methods but include uploading widgets for iOS and Android. They allow to:

  • Upload files from a local disk, camera, and cloud sources.
  • Upload multiple files at once.
  • Track, pause and continue multipart uploading.
  • Upload in the background.

API integrations

Upload API features

The main features of our Upload API are:

You can also check out the complete OpenAPI specification of 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 -F "UPLOADCARE_PUB_KEY=$YOUR_PUBLIC_KEY" \
>     -F "UPLOADCARE_STORE=auto" \
>     -F "file=@sample-file.jpeg" \
>     "https://upload.uploadcare.com/base/"

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 -F "pub_key=$YOUR_PUBLIC_KEY" \
>     -F "source_url=$URL" \
>     "https://upload.uploadcare.com/from_url/"

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 -F "UPLOADCARE_PUB_KEY=$YOUR_PUBLIC_KEY" \
>     -F "token=$token" \
>     "https://upload.uploadcare.com/from_url/status/"

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 -F "UPLOADCARE_PUB_KEY=$YOUR_PUBLIC_KEY" \
>     -F "check_URL_duplicates=1" \
>     -F "source_url=$URL" \
>     "https://upload.uploadcare.com/from_url/"

If the source_url had already been fetched and uploaded previously, this request would return information about the already uploaded file.

Alternative remote uploading method

You can also upload remote files with CDN Proxy.

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 -F "UPLOADCARE_PUB_KEY=$YOUR_PUBLIC_KEY" \
>     -F "filename=large-file.mp4" \
>     -F "size=27796904" \
>     -F "content_type=video/mp4" \
>     "https://upload.uploadcare.com/multipart/start/"
>
>curl -X PUT "<presigned-url-part-from-multipart-start>"
>     -H "Content-Type: application/octet-stream" --data <data-part>
>
>curl -F "UPLOADCARE_PUB_KEY=$YOUR_PUBLIC_KEY" \
>     -F "uuid=$UUID" \
>     "https://upload.uploadcare.com/multipart/complete/"

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 -F "UPLOADCARE_PUB_KEY=$YOUR_PUBLIC_KEY" \
>     -F "file=@sample-image.jpeg" \
>     -F "metadata[userId]=1" \
>     -F "metadata[type]=avatar" \
>     "https://upload.uploadcare.com/base/"

Learn more about file metadata.

Signed uploads

Signed upload requests include an authentication signature that is generated based on your project’s secret key and expiration time parameters. This signature must be generated on your backend, as you must never expose your secret key in client-side code. Learn more about signed uploads.

Webhooks on upload

Uploadcare can notify your application when a new file has been uploaded asynchronously. For example, you may need to decide on your file based on the above-mentioned analysis. When an upload happens, we’ll make a POST request with a JSON payload to the endpoint you provided. Learn more about webhooks.

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 -F "pub_key=$YOUR_PUBLIC_KEY" \
>     -F "file_id=$UUID" \
>     "https://upload.uploadcare.com/info/"

Check out detailed API reference for file info.

Retrieve remote files on the fly

Proxy automatically retrieves files from existing remote locations and delivers them using Uploadcare CDN. It’s easy to integrate, requiring only one URL modification:

https://endpoint.ucr.io/ + https://yoursite.com/assets/image.jpg =
https://endpoint.ucr.io/https://yoursite.com/assets/image.jpg

Learn more about Proxy.

Migrate files from anywhere

If you migrated to Uploadcare from a DIY solution or another platform, you need to migrate your files. First, copy the files from their current location to your Uploadcare storage so they can be processed and delivered using the Uploadcare CDN.

Learn more about Migro.