Cloudinary Python SDK

The samples/ directory contains several reference implementations for different use cases using the Cloudinary Python SDK:

• Basic sample: A synchronous script demonstrating uploading local files and remote URLs, along with various transformations and options.
• Photo Album: A Django-based web application for uploading photos, managing a database of references, listing metadata, and displaying images with cloud-based transformations.
• Basic Flask sample: A simple Flask application that performs image uploads and generates transformations of the uploaded images.
• Basic Google App Engine sample: A GAE application for image uploads and transformations. Note: This requires cloudinary > 1.0.18.
• SpookyShots: A specialized application that uses Cloudinary to transform pet images into Halloween-themed creations.

Structured metadata allows you to attach typed, validated fields (like SKU, campaign, or category) to assets. Unlike Tags (flat strings) or Context (unvalidated key/value pairs), structured metadata uses a schema defined at the account level.

Key Concepts

• Schema-based: Fields are defined once on the account with a specific type and optional validation.
• Contractual: Use the external_id as the constant key in your application. Renaming a field's label does not change its external_id.
• Validation: Values are rejected if they do not match the defined type or if the external_id is not registered.

The cloudinary Python SDK is a server-side library. It requires your api_secret to function, which must never be exposed in client-side or frontend code.

If you need to allow a browser to upload files directly to Cloudinary, your server must use this SDK to generate short-lived signatures and pass them to the frontend. Do not attempt to use this SDK in frontend environments.

When using upload_large, the final chunk returns the full asset payload. Earlier chunks return a short "parts uploaded" acknowledgement.

Recommended Fields to Store:

• asset_id: Always store this. It is a permanent identifier that never changes, whereas public_id can change if the asset is renamed or moved.

Video-Specific Metadata: Video uploads include additional fields in the result dictionary that are useful for deciding which renditions to generate:

• duration: Length in seconds.
• bit_rate
• frame_rate
• audio: Sub-dictionary with codec details.
• video: Sub-dictionary with codec details.

Note: eager transformation entries appear in the result only if eager_async=False.

Use this SDK for Python server-side code (including Django) to perform tasks such as:

• Uploading media
• Performing signed operations
• Asset administration and search
• Moderation
• Generating delivery URLs

Do not use this SDK for:

• Browser or frontend rendering (use frontend SDKs instead)
• Complete in-browser upload UIs (use Upload Widget instead)
• Text-to-image or image-to-video generation (use platform APIs instead)

To prevent clients from uploading arbitrary files or choosing their own destinations, use Upload Presets instead of signing raw parameters. A preset allows you to pre-define constraints like folder, allowed_formats, and transformation settings on the Cloudinary dashboard or via the API.

When signing, you only sign the upload_preset parameter. This ensures the client can only perform the specific type of upload you have configured.

import cloudinary.api

# 1. Create the preset with restrictions
cloudinary.api.create_upload_preset(
    name="user-avatars",
    unsigned=False,
    folder="avatars",
    allowed_formats="jpg,png,webp",
    transformation=[{"width": 512, "height": 512, "crop": "fill", "gravity": "face"}],
)

# 2. Sign the request using only the preset name
params_to_sign = {
    "timestamp": int(time.time()), 
    "upload_preset": "user-avatars"
}

When handling upload results, it is critical to understand the difference between these two identifiers:

• asset_id: A unique, immutable identifier. It never changes, even if the asset is renamed or moved. You should store this in your database to reliably look up assets later using cloudinary.api.resource_by_asset_id(asset_id).
• public_id: A human-readable identifier that can change if the asset is renamed or moved. While useful for constructing URLs, it is not a permanent reference.

Recommended storage pattern:

# Store both, but rely on asset_id for permanent references
record = {"asset_id": result["asset_id"], "public_id": result["public_id"]}

When managing assets, you must choose the correct API based on your goal to avoid confusion:

• Search (cloudinary.Search): Use this for querying. It allows you to find assets matching specific criteria across fields, tags, folders, and dates (e.g., "Find all images tagged 'catalog'").
• Admin (cloudinary.api): Use this for direct manipulation. It is intended for reading, updating, organizing, or deleting specific assets or listing assets by a single axis like a folder or tag (e.g., "Update the tags on this specific asset").

To use Cloudinary's Django-specific features like template tags and bundled static files, add "cloudinary" to your INSTALLED_APPS.

Configure your credentials using the CLOUDINARY dictionary in settings.py. Note that this dictionary is read before environment variables; if you provide a partial dictionary, it will mask a working CLOUDINARY_URL environment variable.

Alternatively, you can set the CLOUDINARY_URL environment variable (recommended).

# settings.py
INSTALLED_APPS = [
    # ...
    "cloudinary",
]

# Credentials configuration
CLOUDINARY = {
    "cloud_name": "my-cloud",
    "api_key": "123456789012345",
    "api_secret": os.environ["CLOUDINARY_API_SECRET"],
    "secure": True,
}