Uploadcare Getting Started: Account, Keys, and First Upload (2026)

Getting started overview

This guide outlines the foundational steps for integrating with Uploadcare, covering account creation, credential retrieval, and executing an initial file upload. It focuses on practical implementation to enable developers to begin using Uploadcare's file management and media processing services quickly. The process typically involves three key stages: account setup, obtaining API keys, and making a successful first API call, often through an SDK or direct HTTP request. Understanding these initial steps is critical for leveraging Uploadcare's features for web and mobile app file uploads and image optimization and delivery.

A quick reference for the getting started process is provided below:

Create an account and get keys

To begin using Uploadcare, an account is required. This provides access to the Uploadcare dashboard, where project management and API key retrieval occur. Uploadcare offers a free tier that includes 5 GB of storage, 10 GB of traffic, and 20 GB of processing, suitable for initial development and testing.

1. Sign Up for an Account: Navigate to the Uploadcare pricing page and select the free tier option to create a new account. Registration typically involves an email address and password.
2. Create a Project: Upon successful login to the Uploadcare dashboard, you will be prompted to create your first project or can do so from the 'Projects' section. Each project is assigned a unique set of API keys.
3. Retrieve API Keys: Within your project settings in the Uploadcare dashboard, locate the 'API keys' section. You will find two primary credentials:
• Public Key: Used for client-side operations, such as direct file uploads from a browser or mobile application. This key is generally safe to expose publicly.
• Secret Key: Used for server-side operations, including secure file processing, deletion, and managing files through the Uploadcare API. This key must be kept confidential and never exposed in client-side code.

For detailed information on managing projects and obtaining keys, refer to the Uploadcare API reference documentation.

Your first request

A common first request with Uploadcare involves uploading a file. This can be accomplished using the official SDKs or by making a direct HTTP POST request to the Uploadcare API. This example uses the Python SDK for illustration, as Python is one of the primary language examples supported by Uploadcare. Before proceeding, ensure you have Python installed and the Uploadcare Python SDK installed via pip (pip install uploadcare).

Using the Uploadcare Python SDK

This example demonstrates how to upload a local file using the Python SDK. Remember to replace 'YOUR_PUBLIC_KEY' and 'YOUR_SECRET_KEY' with your actual credentials from the Uploadcare dashboard.

import uploadcare

# Initialize the Uploadcare client with your API keys
# Public key is used for client-side, but for direct file uploads (like this), both are often used for authentication.
# Secret key is crucial for server-side operations.

public_key = 'YOUR_PUBLIC_KEY'
secret_key = 'YOUR_SECRET_KEY'

api = uploadcare.api.Uploadcare(public_key, secret_key)

# Define the path to the file you want to upload
file_path = 'path/to/your/local/image.jpg'

try:
    # Upload the file
    uploaded_file = api.file.upload(file_path)

    print(f"File uploaded successfully!")
    print(f"File UUID: {uploaded_file.uuid}")
    print(f"File URL: {uploaded_file.cdn_url}")
    print(f"File Info: {uploaded_file.info}")

    # You can also store the file permanently if auto_store is not enabled by default
    # uploaded_file.store()
    # print("File stored permanently.")

except uploadcare.exceptions.UploadcareException as e:
    print(f"An error occurred during upload: {e}")

Before running this code, ensure you have a placeholder image (e.g., image.jpg) at the specified file_path. The output will include the unique UUID of the uploaded file and its CDN URL, which can be used for accessing and transforming the image.

Direct HTTP Request (cURL example)

For scenarios where an SDK is not preferred, files can be uploaded using a direct HTTP POST request. This cURL example demonstrates a multipart/form-data upload. Note that while a Public Key is provided, server-side operations often benefit from a signed upload for enhanced security, especially when dealing with sensitive files or user-generated content.

curl -X POST \
  -F "UPLOADCARE_PUB_KEY=YOUR_PUBLIC_KEY" \
  -F "file=@/path/to/your/local/document.pdf" \
  https://upload.uploadcare.com/base/

Replace YOUR_PUBLIC_KEY with your Uploadcare Public Key and /path/to/your/local/document.pdf with the actual path to a file on your system. A successful response will return a JSON object containing the file's UUID.

Common next steps

After successfully uploading your first file, several common next steps can enhance your application's functionality:

• Image Optimization and Transformations: Utilize Uploadcare's Image CDN to optimize and transform images on the fly. This includes resizing, cropping, applying filters, and format conversion. For example, appending -/resize/200x200/ to an image URL resizes it.
• File Processing: Explore advanced file processing options, such as document conversion to different formats (e.g., PDF to an image preview), video encoding, or audio processing. The File Processing API provides endpoints for these operations.
• Integrate the File Uploader Widget: For web applications, integrate the highly customizable Uploadcare File Uploader widget to provide a user-friendly interface for file selection and upload directly from the client.
• Webhooks: Configure webhooks to receive notifications about file upload status, processing completion, or other events. This enables asynchronous processing and real-time updates in your application. For general guidance on webhook security, refer to Twilio's webhook security guide.
• Secure File Access: Implement signed URLs for secure access to private files, restricting access based on time or specific user permissions.
• Explore SDKs: While this guide used Python, explore other Uploadcare SDKs for languages like JavaScript, React, Angular, Vue, PHP, Ruby, Java, Go, Node.js, and .NET to streamline integration into existing projects.

Troubleshooting the first call

When making your first API call to Uploadcare, common issues can arise. Here are typical problems and their solutions:

• Invalid API Keys: Double-check that you have copied the correct Public Key and Secret Key for your project. Ensure no leading or trailing spaces are present. The Public Key is used for client-side uploads, while the Secret Key is for server-side operations and authentication.
• Incorrect File Path: Verify that the file_path in your code or cURL command accurately points to an existing file on your local system. Relative paths can sometimes be misinterpreted, so using an absolute path can help diagnose this.
• Network Issues: Ensure your development environment has an active internet connection and that no firewalls or proxies are blocking outgoing requests to upload.uploadcare.com or api.uploadcare.com.
• Missing Dependencies/SDK: If using an SDK (e.g., Python), confirm that the SDK is correctly installed and imported into your project. For Python, this means running pip install uploadcare.
• File Size Limits: Check if the file you are trying to upload exceeds any configured limits in your Uploadcare project settings or the free tier's default limits. While the free tier offers 5 GB storage, individual file size limits might apply.
• Server-side Errors (HTTP Status Codes): Pay attention to the HTTP status codes returned in API responses.
• 400 Bad Request: Often indicates an issue with the request parameters, such as an invalid file format or missing required fields.
• 401 Unauthorized: Typically means your API keys are incorrect or missing from the request headers/parameters.
• 403 Forbidden: Suggests that your API keys lack the necessary permissions for the requested operation.
• 5xx Server Error: Indicates an issue on Uploadcare's end. If this persists, check the Uploadcare status page or contact support.
• Debugging SDK Issues: Most SDKs provide mechanisms for logging or verbose output. Consult the specific SDK documentation for debugging instructions. For example, in the Python SDK, you might catch uploadcare.exceptions.UploadcareException as shown in the example code.