Python API Client

Uploadcare Python & Django integrations handle uploads and further operations with files by wrapping Upload and REST APIs.

GitHub →

Features

Uploading (Upload API):

• Upload files from a local storage and URLs (up to 5 TB)
• Multipart uploading for large files
• Uploading network to speed up uploading jobs (like CDN)

File management (REST API):

• Get file info
• Perform various file operations (store/delete/copy/group)
• Detect unsafe and malicious content
• Encode and transform videos
• Convert documents and other files
• Recognize objects in the image
• Add arbitrary file metadata
• Manage webhooks

Image processing (URL API):

• Compression
• Geometry
• Colors
• Definition
• Image and text overlays
• Rotations
• Recognition
• File info
• Proxy (fetch)

Security features:

• Secure authentication
• Secure uploads (signed uploads)
• Secure delivery (signed URLs)
• Secure webhooks (signing secret)

Installation

In order to install pyuploadcare, run these command in CLI:

$
pip install pyuploadcare

To use in Django project install with extra dependencies:

$
pip install pyuploadcare[django]

Configuration

Add your Uploadcare API keys to Django settings:

1
# settings.py
2
UPLOADCARE = {
3
    "pub_key": "YOUR_PUBLIC_KEY",
4
    "secret": "YOUR_SECRET_KEY",
5
}

For secure uploads, enable signed uploads:

1
UPLOADCARE = {
2
    "pub_key": "YOUR_PUBLIC_KEY",
3
    "secret": "YOUR_SECRET_KEY",
4
    "signed_uploads": True,
5
}

For subdomain CDN addressing (recommended for high-traffic projects):

1
UPLOADCARE = {
2
    "pub_key": "YOUR_PUBLIC_KEY",
3
    "secret": "YOUR_SECRET_KEY",
4
    "subdomains": True,
5
}

Usage example

Here is an example how to include Uploadcare ImageField into an existing Django project.

1
from django import forms
2
from django.db import models
3
4
from pyuploadcare.dj.models import ImageField
5
from pyuploadcare.dj.forms import FileWidget, ImageField as ImageFormField
6
7
class Candidate(models.Model):
8
    photo = ImageField(blank=True, manual_crop='4:3')
9
10
# optional. provide advanced widget options:
11
# https://uploadcare.com/docs/file-uploader/configuration/
12
# https://uploadcare.com/docs/file-uploader/options/
13
class CandidateForm(forms.Form):
14
    photo = ImageField(widget=FileWidget(attrs={
15
        'source-list': 'local,url,camera',
16
        'camera-mirror': True,
17
    }))

Widget

By default, pyuploadcare uses the File Uploader v1 widget (FileWidget). Pass any File Uploader configuration attributes via attrs:

1
from pyuploadcare.dj.forms import FileWidget, ImageField as ImageFormField
2
3
class CandidateForm(forms.Form):
4
    photo = ImageFormField(widget=FileWidget(attrs={
5
        'source-list': 'local,url,camera',
6
        'camera-mirror': True,
7
    }))

To use the legacy jQuery-based widget instead:

1
# settings.py
2
UPLOADCARE = {
3
    "pub_key": "YOUR_PUBLIC_KEY",
4
    "secret": "YOUR_SECRET_KEY",
5
    "use_legacy_widget": True,
6
    "legacy_widget": {
7
        "version": "3.x",
8
    },
9
}

Example Django project

Check out example Django project. It features:

• Project section
• Files section
• File Groups section
• Files uploading
• Documents conversion
• Video conversion
• Webhooks
• Posts section

Requirements

• Python 3.8, 3.9, 3.10, 3.11, 3.12, 3.13

To use pyuploadcare with Python 3.6 or 3.7 please install pyuploadcare < 5.0.

To use pyuploadcare with Python 2.7 please install pyuploadcare < 3.0.

Django compatibility: