Cloudinary Python SDK

Warnings

• breaking Python 2.x reached End of Life in January 2020. While older SDK versions might have supported Python 2.7, current and actively maintained versions of the Cloudinary Python SDK are developed for Python 3.x. Using Python 2.x may lead to compatibility issues and security vulnerabilities.
  Fix: Upgrade your Python environment to Python 3.8+ for full compatibility and security. (Recommended Python 3.8+)
• gotcha Cloudinary API Key and Secret are sensitive credentials. Exposing them in source code or version control (e.g., directly in `settings.py` or `.env` files committed to Git) is a significant security risk.
  Fix: Always use environment variables (e.g., `CLOUDINARY_URL` or `CLOUDINARY_CLOUD_NAME`, `CLOUDINARY_API_KEY`, `CLOUDINARY_API_SECRET`) and ensure your `.env` files are excluded from version control (via `.gitignore`). Load them using libraries like `python-dotenv`.
• gotcha When configuring Cloudinary globally (e.g., with `cloudinary.config()`) and using advanced settings like a proxy, the `cloudinary.config()` call must occur *before* importing `cloudinary.uploader` and `cloudinary.api` to ensure the settings are applied correctly for those modules.
  Fix: Structure your imports and configuration: `import cloudinary`, then `cloudinary.config(...)`, then `import cloudinary.uploader`, `import cloudinary.api`.
• gotcha Direct browser uploads (from client-side code) should primarily use 'unsigned upload presets'. Unsigned requests have a restricted set of parameters for security reasons. Other desired transformations or settings should be defined within the upload preset itself, rather than directly in the unsigned upload call.
  Fix: Define and utilize signed or unsigned upload presets via the Cloudinary Console or Admin API to manage upload options and transformations securely for client-side uploads. Use `upload_preset` parameter in your upload calls.

Install

• pip install cloudinary Install core SDK
• pip install python-dotenv Optional: For local .env configuration

Imports

• cloudinary

  import cloudinary

• uploader

  import cloudinary.uploader

• api

  import cloudinary.api

• CloudinaryImage

  from cloudinary import CloudinaryImage

  Used for simplified image URL generation.
• CloudinaryField

  from cloudinary.models import CloudinaryField

  Django-specific model field for storing Cloudinary asset URLs.
• CloudinaryFileField

  from cloudinary.forms import CloudinaryFileField

  Django-specific form field for uploading files to Cloudinary.

Quickstart

This quickstart demonstrates how to configure the Cloudinary Python SDK, upload an image from a remote URL, generate a transformed URL, and retrieve asset details using the Admin API. It emphasizes using environment variables (especially `CLOUDINARY_URL`) for secure configuration. For local development, `python-dotenv` is used to load these variables from a `.env` file.

import os
from dotenv import load_dotenv
import cloudinary
import cloudinary.uploader
import cloudinary.api

# Load environment variables from .env file (for local development)
load_dotenv()

# Configure Cloudinary using the CLOUDINARY_URL environment variable
# Example: CLOUDINARY_URL=cloudinary://<api_key>:<api_secret>@<cloud_name>
# Ensure this variable is set in your environment or .env file.
cloudinary.config(secure=True) # Forces HTTPS URLs

# Check if configuration is successful (optional, for debugging)
if not cloudinary.config().cloud_name:
    print("Cloudinary configuration missing. Please set CLOUDINARY_URL.")
    exit(1)

print("Cloudinary configured. Cloud name:", cloudinary.config().cloud_name)

# --- Example: Upload an image ---
# Replace 'my_local_image.jpg' with a path to a local image or a remote URL.
# For a real application, handle file paths dynamically.
try:
    upload_result = cloudinary.uploader.upload(
        "https://cloudinary-devs.github.io/cld-docs-assets/assets/images/butterfly.jpeg",
        public_id="quickstart_butterfly_example",
        unique_filename=False,
        overwrite=True
    )
    print("\nUpload successful:")
    print("Public ID:", upload_result['public_id'])
    print("Secure URL:", upload_result['secure_url'])

    # --- Example: Generate a transformed URL ---
    transformed_url = cloudinary.utils.cloudinary_url(
        upload_result['public_id'],
        width=100,
        height=150,
        crop="fill"
    )[0]
    print("Transformed URL (fill 100x150):", transformed_url)

    # --- Example: Get asset details (Admin API) ---
    asset_details = cloudinary.api.resource(upload_result['public_id'])
    print("\nAsset details:")
    print(f"Format: {asset_details['format']}, Bytes: {asset_details['bytes']}")

except Exception as e:
    print(f"An error occurred: {e}")