Upload API

def upload(file, **options):
    """Upload a file to Cloudinary.
    
    Args:
        file: File path (str), file object, URL (str), or base64 data URI
        public_id (str, optional): Custom public ID for the uploaded asset
        folder (str, optional): Folder path to store the asset
        use_filename (bool, optional): Use original filename as public_id
        unique_filename (bool, optional): Add unique suffix to prevent conflicts
        overwrite (bool, optional): Overwrite existing asset with same public_id
        resource_type (str, optional): Type of resource ('image', 'video', 'raw', 'auto')
        type (str, optional): Delivery type ('upload', 'private', 'authenticated')
        tags (list, optional): List of tags to assign to the asset
        context (dict, optional): Key-value pairs of contextual metadata
        metadata (dict, optional): Structured metadata key-value pairs
        transformation (dict, optional): Eager transformation to apply
        eager (list, optional): List of transformations to generate immediately
        eager_async (bool, optional): Generate eager transformations asynchronously
        eager_notification_url (str, optional): URL for eager transformation notifications
        format (str, optional): Convert to specified format during upload
        allowed_formats (list, optional): Restrict upload to specific formats
        async (bool, optional): Return immediately, process upload asynchronously
        backup (bool, optional): Create backup copy
        faces (bool, optional): Extract face coordinates
        colors (bool, optional): Extract predominant colors
        image_metadata (bool, optional): Extract image metadata (EXIF, IPTC, XMP)
        media_metadata (bool, optional): Extract media metadata
        auto_tagging (float, optional): Automatic tagging confidence threshold
        categorization (str, optional): Automatic categorization model
        detection (str, optional): Object detection model
        ocr (str, optional): Optical Character Recognition model
        **kwargs: Additional upload parameters
    
    Returns:
        dict: Upload result containing:
            - public_id (str): The public ID of the uploaded asset
            - version (int): Version identifier
            - signature (str): Unique signature
            - width (int): Image/video width in pixels
            - height (int): Image/video height in pixels
            - format (str): File format
            - resource_type (str): Type of resource
            - created_at (str): Upload timestamp
            - url (str): HTTP URL for accessing the asset
            - secure_url (str): HTTPS URL for accessing the asset
            - bytes (int): File size in bytes
            - etag (str): Entity tag
            - tags (list): Applied tags
            - context (dict): Contextual metadata
            - metadata (dict): Structured metadata
            - faces (list): Detected face coordinates (if faces=True)
            - colors (list): Predominant colors (if colors=True)
            - info (dict): Additional asset information
            - eager (list): Generated eager transformations
    """

def unsigned_upload(file, upload_preset, **options):
    """Upload a file using an unsigned upload preset.
    
    Args:
        file: File to upload (same formats as upload())
        upload_preset (str): Name of the unsigned upload preset
        **options: Additional upload options (subset of upload() options)
    
    Returns:
        dict: Upload result (same format as upload())
    """

def destroy(public_id, **options):
    """Delete an uploaded asset.
    
    Args:
        public_id (str): Public ID of the asset to delete
        resource_type (str, optional): Type of resource ('image', 'video', 'raw')
        type (str, optional): Delivery type ('upload', 'private', 'authenticated')
        invalidate (bool, optional): Invalidate CDN cache
    
    Returns:
        dict: Deletion result containing:
            - result (str): 'ok' if successful
            - partial (bool): Whether deletion was partial
    """

def rename(from_public_id, to_public_id, **options):
    """Rename an uploaded asset.
    
    Args:
        from_public_id (str): Current public ID
        to_public_id (str): New public ID
        resource_type (str, optional): Type of resource
        type (str, optional): Delivery type
        to_type (str, optional): Target delivery type
        overwrite (bool, optional): Overwrite existing asset at destination
        invalidate (bool, optional): Invalidate CDN cache
    
    Returns:
        dict: Rename result
    """

def explicit(public_id, **options):
    """Perform explicit operations on an already uploaded asset.
    
    Args:
        public_id (str): Public ID of the asset
        resource_type (str, optional): Type of resource
        type (str, optional): Delivery type
        eager (list, optional): Transformations to generate
        eager_async (bool, optional): Generate transformations asynchronously
        eager_notification_url (str, optional): Notification URL for completion
        headers (dict, optional): Custom headers for generated URLs
        tags (list, optional): Tags to assign/replace
        face_coordinates (str, optional): Custom face coordinates
        custom_coordinates (str, optional): Custom crop coordinates
        context (dict, optional): Contextual metadata to assign/replace
        metadata (dict, optional): Structured metadata to assign/replace
        background_removal (str, optional): Background removal mode
        **kwargs: Additional transformation options
    
    Returns:
        dict: Operation result with generated transformations and URLs
    """

def generate_sprite(tag=None, urls=None, **options):
    """Generate sprites by merging multiple images into a single large image.
    
    Args:
        tag (str, optional): Images with this tag will be used to create the sprite
        urls (list, optional): List of URLs to create a sprite from (if tag not set)
        transformation (dict, optional): Transformation to apply to each image before merging
        format (str, optional): Format of the generated sprite (png, jpg, etc.)
        mode (str, optional): Sprite generation mode ('horizontal', 'vertical', 'packed')
        notification_url (str, optional): URL to notify when sprite generation completes
        async (bool, optional): Generate sprite asynchronously
        **kwargs: Additional sprite configuration options
    
    Returns:
        dict: Sprite generation result containing:
            - public_id (str): Public ID of the generated sprite
            - version (int): Version identifier
            - url (str): HTTP URL for accessing the sprite
            - secure_url (str): HTTPS URL for accessing the sprite
            - css_url (str): URL to generated CSS file with sprite coordinates
            - image_infos (list): Information about each image in the sprite
    """

def download_generated_sprite(tag=None, urls=None, **options):
    """Generate a downloadable URL for the sprite.
    
    Args:
        tag (str, optional): Images with this tag will be used to create the sprite
        urls (list, optional): List of URLs to create a sprite from (if tag not set)
        **options: Same options as generate_sprite()
    
    Returns:
        str: Signed URL to download the sprite
    """

def multi(tag=None, urls=None, **options):
    """Create an animated image, video, or PDF from a set of images.
    
    Args:
        tag (str, optional): Assets with this tag will be used
        urls (list, optional): List of image URLs (if no tag is set)
        format (str, optional): Output format ('gif', 'pdf', 'mp4', 'webm')
        transformation (dict, optional): Transformation to apply to each image
        delay (int, optional): Delay between frames in milliseconds (for animations)
        notification_url (str, optional): URL to notify when processing completes
        async (bool, optional): Process asynchronously
        **kwargs: Additional multi-configuration options
    
    Returns:
        dict: Multi generation result containing:
            - public_id (str): Public ID of the generated multi-asset
            - version (int): Version identifier
            - url (str): HTTP URL for accessing the multi-asset
            - secure_url (str): HTTPS URL for accessing the multi-asset
            - format (str): Format of the generated asset
            - resource_type (str): Type of resource created
    """

def download_multi(tag=None, urls=None, **options):
    """Generate a downloadable URL for the multi-asset.
    
    Args:
        tag (str, optional): Assets with this tag will be used
        urls (list, optional): List of image URLs (if no tag is set)
        **options: Same options as multi()
    
    Returns:
        str: Signed URL to download the multi-asset
    """

def upload_large(file, **options):
    """Upload large files using chunked upload.
    
    Args:
        file: Large file to upload
        chunk_size (int, optional): Size of each chunk in bytes (default: 20MB)
        **options: Same options as upload()
    
    Returns:
        dict: Upload result (same format as upload())
    """

def create_archive(**options):
    """Create an archive (ZIP/TAR) from multiple assets.
    
    Args:
        public_ids (list, optional): List of public IDs to include
        prefixes (list, optional): List of prefixes to match
        tags (list, optional): List of tags to match
        target_format (str, optional): Archive format ('zip', 'tgz')
        flatten_folders (bool, optional): Flatten folder structure
        keep_derived (bool, optional): Include derived assets
        resource_type (str, optional): Type of resources to include
        type (str, optional): Delivery type of resources
        mode (str, optional): Archive creation mode
        **kwargs: Additional archive options
    
    Returns:
        dict: Archive creation result with download URL
    """

def create_zip(**options):
    """Create a ZIP archive from multiple assets.
    
    Args:
        **options: Same options as create_archive() with target_format='zip'
    
    Returns:
        dict: ZIP creation result
    """
def explode(public_id, **options):
    """Create derived images for all individual pages in a multi-page file.
    
    Args:
        public_id (str): Public ID of the multi-page file to explode
        format (str, optional): Format for the generated page images
        transformation (dict, optional): Transformation to apply to each page
        notification_url (str, optional): URL to notify when explode completes
        **kwargs: Additional explode configuration options
    
    Returns:
        dict: Explode operation result containing:
            - batch_id (str): ID of the batch operation
            - status (str): Operation status
    """

def create_slideshow(**options):
    """Create an auto-generated video slideshow from existing assets.
    
    Args:
        manifest_json (dict, optional): JSON specification for slideshow creation
        transformation (list, optional): Transformations to apply to the slideshow
        manifest_transformation (list, optional): Transformations for the manifest
        tags (list, optional): Tags to assign to the generated slideshow
        public_id (str, optional): Public ID for the generated slideshow
        overwrite (bool, optional): Overwrite existing slideshow with same public_id
        notification_url (str, optional): URL to notify when processing completes
        upload_preset (str, optional): Upload preset to apply
        resource_type (str, optional): Resource type, defaults to "video"
        **kwargs: Additional slideshow options
    
    Returns:
        dict: Slideshow creation result containing:
            - public_id (str): Public ID of the generated slideshow
            - version (int): Version identifier
            - url (str): HTTP URL for accessing the slideshow
            - secure_url (str): HTTPS URL for accessing the slideshow
            - resource_type (str): Type of resource created
    """

def text(text, **options):
    """Dynamically generate an image of a given text string.
    
    Args:
        text (str): Text string to generate an image for
        public_id (str, optional): Public ID for the generated text image
        font_family (str, optional): Font family name
        font_size (int, optional): Font size in pixels
        font_color (str, optional): Font color (hex, rgb, or named color)
        font_weight (str, optional): Font weight ('normal', 'bold', etc.)
        font_style (str, optional): Font style ('normal', 'italic', etc.)
        text_align (str, optional): Text alignment ('left', 'center', 'right')
        text_decoration (str, optional): Text decoration ('none', 'underline', etc.)
        background (str, optional): Background color
        opacity (int, optional): Text opacity (0-100)
        **kwargs: Additional text styling options
    
    Returns:
        dict: Text generation result containing:
            - public_id (str): Public ID of the generated text image
            - version (int): Version identifier
            - url (str): HTTP URL for accessing the text image
            - secure_url (str): HTTPS URL for accessing the text image
            - width (int): Image width in pixels
            - height (int): Image height in pixels
    """

def upload_image(file, **options):
    """Upload a file and return a CloudinaryImage object.
    
    Args:
        file: File to upload (same formats as upload())
        **options: Same options as upload()
    
    Returns:
        CloudinaryImage: CloudinaryImage object referencing the uploaded image
    """

def upload_resource(file, **options):
    """Upload a file and return a CloudinaryResource object.
    
    Args:
        file: File to upload (same formats as upload())
        **options: Same options as upload()
    
    Returns:
        CloudinaryResource: CloudinaryResource object (image, video, or raw)
    """

def upload_large_part(file, **options):
    """Upload a large chunk (part) of a file to Cloudinary.
    
    Args:  
        file (tuple): Tuple of (filename, chunk_data) for the file part
        http_headers (dict, optional): HTTP headers including Content-Range
        resource_type (str, optional): Type of resource (defaults to "raw")
        **options: Additional parameters for the chunk upload
    
    Returns:
        dict: Chunk upload result (same format as upload())
    """

def add_tag(tag, public_ids, **options):
    """Add a tag to multiple assets.
    
    Args:
        tag (str): Tag to add
        public_ids (list): List of public IDs to tag
        resource_type (str, optional): Type of resources
        type (str, optional): Delivery type
    
    Returns:
        dict: Operation result
    """

def remove_tag(tag, public_ids, **options):
    """Remove a tag from multiple assets.
    
    Args:
        tag (str): Tag to remove
        public_ids (list): List of public IDs to untag
        resource_type (str, optional): Type of resources
        type (str, optional): Delivery type
    
    Returns:
        dict: Operation result
    """

def replace_tag(tag, public_ids, **options):
    """Replace all tags on multiple assets with a single tag.
    
    Args:
        tag (str): Tag to set (replaces all existing tags)
        public_ids (list): List of public IDs
        resource_type (str, optional): Type of resources
        type (str, optional): Delivery type
    
    Returns:
        dict: Operation result
    """

def remove_all_tags(public_ids, **options):
    """Remove all tags from the specified assets.
    
    Args:
        public_ids (list): List of public IDs to remove all tags from
        resource_type (str, optional): Type of resources
        type (str, optional): Delivery type
    
    Returns:
        dict: Operation result
    """

def update_metadata(metadata, public_ids, **options):
    """Populate or update metadata fields with given values.
    
    Args:
        metadata (dict): Key-value pairs for custom metadata fields (by external_id)
        public_ids (list): List of public IDs to update
        resource_type (str, optional): Type of resources (default: "image")
        type (str, optional): Delivery type
        clear_invalid (bool, optional): Remove keys that are not valid
    
    Returns:
        dict: List of public IDs that were updated
    """

def add_context(context, public_ids, **options):
    """Add contextual metadata (key-value pairs) to specified assets.
    
    Args:
        context (dict): Dictionary of context key-value pairs
        public_ids (list): List of public IDs to update
        resource_type (str, optional): Type of resources
        type (str, optional): Delivery type
    
    Returns:
        dict: Operation result with list of updated public IDs
    """

def remove_all_context(public_ids, **options):
    """Remove all custom contextual metadata from specified assets.
    
    Args:
        public_ids (list): List of public IDs to update
        resource_type (str, optional): Type of resources  
        type (str, optional): Delivery type
    
    Returns:
        dict: Operation result with list of updated public IDs
    """

from cloudinary import uploader

# Upload from local file path
result = uploader.upload("path/to/image.jpg")
print(f"Uploaded: {result['public_id']}")
print(f"URL: {result['secure_url']}")

# Upload from URL
result = uploader.upload("https://example.com/image.jpg")

# Upload with custom public ID
result = uploader.upload(
    "image.jpg",
    public_id="my_custom_id",
    overwrite=True
)

# Upload to specific folder
result = uploader.upload(
    "image.jpg",
    folder="products/featured",
    use_filename=True,
    unique_filename=False
)

# Upload with transformations and metadata
result = uploader.upload(
    "image.jpg",
    public_id="sample_product",
    transformation=[
        {"width": 1000, "height": 1000, "crop": "limit"},
        {"quality": "auto", "format": "auto"}
    ],
    tags=["product", "featured"],
    context={"category": "electronics", "brand": "acme"},
    metadata={"sku": "12345", "price": "99.99"},
    eager=[
        {"width": 300, "height": 300, "crop": "thumb"},
        {"width": 800, "height": 600, "crop": "fill"}
    ],
    eager_async=True
)

# Upload with AI features
result = uploader.upload(
    "image.jpg",
    faces=True,
    colors=True,
    image_metadata=True,
    auto_tagging=0.7,
    categorization="google_tagging",
    detection="adv_face",
    ocr="adv_ocr"
)

# Upload video file
result = uploader.upload(
    "video.mp4",
    resource_type="video",
    public_id="sample_video",
    eager=[
        {"width": 640, "height": 480, "crop": "pad", "format": "mp4"},
        {"width": 300, "height": 300, "crop": "thumb", "format": "jpg"}
    ]
)

# Upload large video with chunked upload
result = uploader.upload_large(
    "large_video.mov",
    resource_type="video",
    chunk_size=50 * 1024 * 1024,  # 50MB chunks
    eager_async=True
)

# Delete an asset
result = uploader.destroy("sample_image")
print(f"Deleted: {result['result']}")

# Rename an asset
result = uploader.rename("old_public_id", "new_public_id")

# Generate additional transformations
result = uploader.explicit(
    "sample_image",
    type="upload",
    eager=[
        {"width": 400, "height": 300, "crop": "pad"},
        {"width": 200, "height": 200, "crop": "thumb", "radius": "max"}
    ]
)

# Add tags to multiple assets
result = uploader.add_tag(
    "summer_sale",
    ["product_1", "product_2", "product_3"]
)

# Create ZIP archive
result = uploader.create_zip(
    tags=["product"],
    resource_type="image",
    flatten_folders=True
)
archive_url = result['url']

# Unsigned upload (requires upload preset)
result = uploader.unsigned_upload(
    "image.jpg",
    "my_upload_preset",
    tags=["unsigned"]
)

# Generate sprite from tagged images
result = uploader.generate_sprite(
    tag="product_thumbnails",
    transformation={"width": 100, "height": 100, "crop": "fill"}
)
sprite_url = result['url']
css_url = result['css_url']

# Create animated GIF from images
result = uploader.multi(
    tag="slideshow_images",
    format="gif",
    delay=1000  # 1 second delay between frames
)

# Create PDF from multiple images
result = uploader.multi(
    urls=[
        "https://res.cloudinary.com/.../image1.jpg",
        "https://res.cloudinary.com/.../image2.jpg"
    ],
    format="pdf"
)

# Generate simple text image
result = uploader.text(
    "Hello World",
    font_family="Arial",
    font_size=48,
    font_color="blue"
)

# Generate styled text with background
result = uploader.text(
    "SALE 50% OFF",
    font_family="Helvetica",
    font_size=72,
    font_weight="bold",
    font_color="white",
    background="red",
    text_align="center",
    public_id="sale_banner"
)

# Create slideshow from tagged videos
result = uploader.create_slideshow(
    manifest_json={
        "w": 1280,
        "h": 720,
        "fps": 30,
        "vars": {
            "slides": [
                {"media": "i:slide1", "duration": 3000},
                {"media": "i:slide2", "duration": 3000}
            ]
        }
    },
    public_id="my_slideshow",
    overwrite=True
)

# Explode PDF into individual page images
result = uploader.explode(
    "sample.pdf",
    format="jpg",
    transformation={"width": 800, "quality": "auto"}
)

# Update metadata for multiple assets
result = uploader.update_metadata(
    {"product_id": "12345", "category": "electronics"},
    ["asset1", "asset2", "asset3"]
)

# Add contextual information
result = uploader.add_context(
    {"alt": "Product photo", "caption": "New arrival"},
    ["product_photo_1", "product_photo_2"]
)

# Remove all tags from assets
result = uploader.remove_all_tags(
    ["old_asset_1", "old_asset_2"]
)