Uploading

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 -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.

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 -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.

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.

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.

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:

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