tessl/pypi-cloudinary
Python and Django SDK for Cloudinary, a cloud-based image and video management service with comprehensive transformation, optimization, and delivery capabilities
Overall
score
94%
admin-api.mddocs/
Admin API
Complete resource management including asset discovery, metadata operations, transformation management, and account administration.
Capabilities
Resource Discovery
List and search for uploaded resources with comprehensive filtering options.
def resources(**options):
"""List uploaded resources with filtering options.
Args:
resource_type (str, optional): Filter by resource type ('image', 'video', 'raw')
type (str, optional): Filter by delivery type ('upload', 'private', 'authenticated', 'fetch', 'multi', 'text', 'asset')
prefix (str, optional): Filter by public_id prefix
public_ids (list, optional): Specific public IDs to retrieve
tags (bool, optional): Include tags in response
context (bool, optional): Include context in response
metadata (bool, optional): Include metadata in response
moderations (bool, optional): Include moderation status
direction (str, optional): Sort direction ('asc', 'desc', default: 'desc')
max_results (int, optional): Maximum results to return (default: 10, max: 500)
next_cursor (str, optional): Cursor for pagination
start_at (str, optional): Start listing from this public_id
**kwargs: Additional filtering options
Returns:
dict: Response containing:
- resources (list): List of resource objects with details
- next_cursor (str): Cursor for next page (if more results exist)
- rate_limit_allowed (int): Rate limit quota
- rate_limit_reset_at (str): Rate limit reset time
- rate_limit_remaining (int): Remaining rate limit quota
"""
def resources_by_tag(tag, **options):
"""List resources filtered by a specific tag.
Args:
tag (str): Tag to filter by
**options: Same options as resources()
Returns:
dict: Response containing resources with the specified tag
"""
def resources_by_context(key, value=None, **options):
"""List resources filtered by context key-value pairs.
Args:
key (str): Context key to filter by
value (str, optional): Context value to filter by (if not provided, matches any value for the key)
**options: Same options as resources()
Returns:
dict: Response containing resources matching the context criteria
"""
def resources_by_moderation(kind, status, **options):
"""List resources filtered by moderation status.
Args:
kind (str): Moderation kind ('manual', 'webpurify', 'aws_rek', 'metascan')
status (str): Moderation status ('pending', 'approved', 'rejected')
**options: Same options as resources()
Returns:
dict: Response containing resources with specified moderation status
"""
def resources_by_ids(public_ids, **options):
"""Get resources by their public IDs.
Args:
public_ids (list): List of public IDs to retrieve
**options: Additional options
Returns:
dict: Response containing the specified resources
"""Individual Resource Management
Get details and update properties of specific resources.
def resource(public_id, **options):
"""Get details of a specific resource.
Args:
public_id (str): Public ID of the resource
resource_type (str, optional): Type of resource ('image', 'video', 'raw')
type (str, optional): Delivery type ('upload', 'private', 'authenticated')
exif (bool, optional): Include EXIF data
colors (bool, optional): Include color information
faces (bool, optional): Include face detection data
quality_analysis (bool, optional): Include quality analysis
accessibility_analysis (bool, optional): Include accessibility analysis
cinemagraph_analysis (bool, optional): Include cinemagraph analysis
coordinates (bool, optional): Include custom coordinates
max_results (int, optional): Maximum derived resources to return
derived_next_cursor (str, optional): Cursor for derived resources pagination
**kwargs: Additional options
Returns:
dict: Detailed resource information including:
- public_id (str): Public identifier
- format (str): File format
- version (int): Version number
- resource_type (str): Type of resource
- type (str): Delivery type
- created_at (str): Creation timestamp
- bytes (int): File size
- width (int): Width in pixels
- height (int): Height in pixels
- url (str): Public URL
- secure_url (str): HTTPS URL
- tags (list): Applied tags
- context (dict): Context metadata
- metadata (dict): Structured metadata
- derived (list): Derived versions/transformations
- And additional analysis data based on options
"""
def update(public_id, **options):
"""Update properties of an existing resource.
Args:
public_id (str): Public ID of the resource to update
resource_type (str, optional): Type of resource
type (str, optional): Delivery type
tags (list, optional): Tags to replace existing tags
context (dict, optional): Context to replace existing context
metadata (dict, optional): Metadata to replace existing metadata
face_coordinates (str, optional): Face coordinates to set
custom_coordinates (str, optional): Custom coordinates to set
auto_tagging (float, optional): Apply auto-tagging with confidence threshold
categorization (str, optional): Apply categorization
detection (str, optional): Apply object detection
background_removal (str, optional): Apply background removal
moderation_status (str, optional): Set moderation status
raw_convert (str, optional): Convert raw file format
quality_override (str, optional): Override quality analysis
**kwargs: Additional update options
Returns:
dict: Updated resource information
"""Resource Deletion
Delete resources individually or in bulk with various filtering criteria.
def delete_resources(public_ids, **options):
"""Delete multiple resources by public IDs.
Args:
public_ids (list): List of public IDs to delete
resource_type (str, optional): Type of resources to delete
type (str, optional): Delivery type of resources
keep_original (bool, optional): Keep original files, delete only derivatives
invalidate (bool, optional): Invalidate CDN cache
next_cursor (str, optional): Cursor for batch processing
Returns:
dict: Deletion results with details of deleted and failed resources
"""
def delete_resources_by_prefix(prefix, **options):
"""Delete resources by public_id prefix.
Args:
prefix (str): Public ID prefix to match
**options: Same options as delete_resources()
Returns:
dict: Deletion results
"""
def delete_resources_by_tag(tag, **options):
"""Delete resources by tag.
Args:
tag (str): Tag to match for deletion
**options: Same options as delete_resources()
Returns:
dict: Deletion results
"""
def delete_all_resources(**options):
"""Delete all resources in the account.
Args:
**options: Same options as delete_resources()
Returns:
dict: Deletion results
"""
def delete_derived_resources(derived_resource_ids, **options):
"""Delete specific derived resources.
Args:
derived_resource_ids (list): List of derived resource IDs to delete
**options: Additional deletion options
Returns:
dict: Deletion results
"""Tag Management
Manage tags across your resources.
def tags(**options):
"""List all tags in your account.
Args:
max_results (int, optional): Maximum results to return
next_cursor (str, optional): Cursor for pagination
prefix (str, optional): Filter tags by prefix
Returns:
dict: Response containing:
- tags (list): List of tag names
- next_cursor (str): Cursor for next page
"""Transformation Management
Manage named transformations and eager transformations.
def transformations(**options):
"""List all named transformations.
Args:
max_results (int, optional): Maximum results to return
next_cursor (str, optional): Cursor for pagination
Returns:
dict: Response containing:
- transformations (list): List of transformation objects
- next_cursor (str): Cursor for next page
"""
def transformation(transformation, **options):
"""Get details of a specific transformation.
Args:
transformation (str|dict): Transformation name or definition
**options: Additional options
Returns:
dict: Transformation details including usage statistics
"""
def create_transformation(name, definition, **options):
"""Create a named transformation.
Args:
name (str): Name for the transformation
definition (dict): Transformation parameters
**options: Additional options
Returns:
dict: Created transformation details
"""
def update_transformation(transformation, **options):
"""Update an existing transformation.
Args:
transformation (str|dict): Transformation to update
allowed_for_strict (bool, optional): Allow in strict mode
**options: Update options
Returns:
dict: Updated transformation details
"""
def delete_transformation(transformation, **options):
"""Delete a named transformation.
Args:
transformation (str|dict): Transformation to delete
**options: Additional options
Returns:
dict: Deletion result
"""Account Information
Get account usage and configuration information.
def ping(**options):
"""Test API connectivity and authentication.
Args:
**options: Additional options
Returns:
dict: Response indicating API status
"""
def usage(**options):
"""Get account usage statistics.
Args:
date (str, optional): Specific date for usage (YYYY-MM-DD format)
**options: Additional options
Returns:
dict: Usage statistics including:
- plan (str): Account plan type
- last_updated (str): Last update timestamp
- objects (dict): Object counts by type
- bandwidth (dict): Bandwidth usage
- storage (dict): Storage usage
- requests (dict): API request counts
- resources (dict): Resource counts
- derived_resources (dict): Derived resource counts
"""Visual Search
Find resources based on visual similarity using images or text descriptions.
def visual_search(image_url=None, image_asset_id=None, text=None, image_file=None, **options):
"""Find images based on their visual content.
Args:
image_url (str, optional): URL of an image to use as search query
image_asset_id (str, optional): Asset ID of an image in your account to use as search query
text (str, optional): Textual description to search for (e.g., "cat", "red car")
image_file (str|bytes|Path|callable, optional): Local image file to use as search query
**options: Additional search options
Returns:
dict: Response containing:
- resources (list): List of visually similar resources
- next_cursor (str): Cursor for pagination (if more results exist)
"""Extended Resource Management
Advanced resource retrieval methods including asset ID and folder-based access.
def resource_by_asset_id(asset_id, **options):
"""Get details of a specific resource by asset ID.
Args:
asset_id (str): Asset ID of the resource
exif (bool, optional): Include EXIF data
faces (bool, optional): Include face detection data
colors (bool, optional): Include color information
image_metadata (bool, optional): Include image metadata
media_metadata (bool, optional): Include extended media metadata
cinemagraph_analysis (bool, optional): Include cinemagraph analysis
pages (bool, optional): Include page count for multi-page files
phash (bool, optional): Include perceptual hash data
coordinates (bool, optional): Include custom and face coordinates
max_results (int, optional): Maximum derived resources to return
quality_analysis (bool, optional): Include quality analysis
derived_next_cursor (str, optional): Cursor for derived resources pagination
accessibility_analysis (bool, optional): Include accessibility analysis
versions (bool, optional): Include version information
related (bool, optional): Include related assets
related_next_cursor (str, optional): Cursor for related assets pagination
**kwargs: Additional options
Returns:
dict: Detailed resource information
"""
def resources_by_asset_folder(asset_folder, **options):
"""List resources in a specific asset folder.
Args:
asset_folder (str): The asset folder path
direction (str, optional): Sort direction ('asc', 'desc')
max_results (int, optional): Maximum results to return
next_cursor (str, optional): Cursor for pagination
**options: Additional filtering options
Returns:
dict: Response containing resources in the specified folder
"""
def resources_by_asset_ids(asset_ids, **options):
"""Get resources by their asset IDs.
Args:
asset_ids (list): List of asset IDs to retrieve
direction (str, optional): Sort direction ('asc', 'desc')
max_results (int, optional): Maximum results to return
next_cursor (str, optional): Cursor for pagination
**options: Additional options
Returns:
dict: Response containing the specified resources
"""Asset Relationship Management
Manage relationships between assets for content organization and discovery.
def add_related_assets(public_id, assets_to_relate, resource_type="image", type="upload", **options):
"""Add related assets to a resource by public IDs.
Args:
public_id (str): Public ID of the main asset
assets_to_relate (list): List of up to 10 fully qualified public IDs (resource_type/type/public_id)
resource_type (str, optional): Resource type (default: "image")
type (str, optional): Upload type (default: "upload")
**options: Additional options
Returns:
dict: Result of the relationship addition
"""
def add_related_assets_by_asset_ids(asset_id, assets_to_relate, **options):
"""Add related assets to a resource by asset IDs.
Args:
asset_id (str): Asset ID of the main asset
assets_to_relate (list): List of up to 10 asset IDs to relate
**options: Additional options
Returns:
dict: Result of the relationship addition
"""
def delete_related_assets(public_id, assets_to_unrelate, resource_type="image", type="upload", **options):
"""Remove related assets from a resource by public IDs.
Args:
public_id (str): Public ID of the main asset
assets_to_unrelate (list): List of up to 10 fully qualified public IDs to unrelate
resource_type (str, optional): Resource type (default: "image")
type (str, optional): Upload type (default: "upload")
**options: Additional options
Returns:
dict: Result of the relationship removal
"""
def delete_related_assets_by_asset_ids(asset_id, assets_to_unrelate, **options):
"""Remove related assets from a resource by asset IDs.
Args:
asset_id (str): Asset ID of the main asset
assets_to_unrelate (list): List of up to 10 asset IDs to unrelate
**options: Additional options
Returns:
dict: Result of the relationship removal
"""Advanced Deletion Operations
Specialized deletion methods for different use cases and asset types.
def delete_resources_by_asset_ids(asset_ids, **options):
"""Delete resources by their asset IDs.
Args:
asset_ids (list): List of asset IDs to delete
transformations (list, optional): Specific transformations to delete
keep_original (bool, optional): Keep original files, delete only derivatives
next_cursor (str, optional): Cursor for batch processing
invalidate (bool, optional): Invalidate CDN cache
**options: Additional deletion options
Returns:
dict: Deletion results with details of deleted and failed resources
"""
def delete_derived_by_transformation(public_ids, transformations, resource_type='image', type='upload', invalidate=None, **options):
"""Delete derived resources by transformation for specific public IDs.
Args:
public_ids (list): List of public IDs or single public ID
transformations (list): List of transformations (dict or str) to delete
resource_type (str, optional): Resource type (default: "image")
type (str, optional): Upload type (default: "upload")
invalidate (bool, optional): Invalidate CDN cache
**options: Additional options
Returns:
dict: Deletion results including public IDs for which derived resources were deleted
"""
def delete_backed_up_assets(asset_id, version_ids, **options):
"""Delete backed up versions of a resource.
Args:
asset_id (str): Asset ID of the resource
version_ids (list): List of version IDs to delete
**options: Additional options
Returns:
dict: Result of the backup deletion
"""Publishing Operations
Manage resource publication from private to public delivery.
def publish_by_ids(public_ids, **options):
"""Publish specific resources by their public IDs.
Args:
public_ids (list): List of public IDs to publish
resource_type (str, optional): Resource type (default: "image")
type (str, optional): Asset type (default: "upload")
overwrite (bool, optional): Overwrite existing published assets
invalidate (bool, optional): Invalidate CDN cache
**options: Additional options
Returns:
dict: Result of the publish operation
"""
def publish_by_prefix(prefix, **options):
"""Publish resources by public ID prefix.
Args:
prefix (str): Public ID prefix to match for publishing
resource_type (str, optional): Resource type (default: "image")
type (str, optional): Asset type (default: "upload")
overwrite (bool, optional): Overwrite existing published assets
invalidate (bool, optional): Invalidate CDN cache
**options: Additional options
Returns:
dict: Result of the publish operation
"""
def publish_by_tag(tag, **options):
"""Publish resources by tag.
Args:
tag (str): Tag to match for publishing
resource_type (str, optional): Resource type (default: "image")
type (str, optional): Asset type (default: "upload")
overwrite (bool, optional): Overwrite existing published assets
invalidate (bool, optional): Invalidate CDN cache
**options: Additional options
Returns:
dict: Result of the publish operation
"""Upload Preset Management
Manage upload presets for standardized upload configurations.
def upload_presets(**options):
"""List all upload presets in your account.
Args:
next_cursor (str, optional): Cursor for pagination
max_results (int, optional): Maximum results to return
**options: Additional options
Returns:
dict: Response containing:
- presets (list): List of upload preset objects
- next_cursor (str): Cursor for next page
"""
def upload_preset(name, **options):
"""Get details of a specific upload preset.
Args:
name (str): Name of the upload preset
max_results (int, optional): Maximum details to return
**options: Additional options
Returns:
dict: Upload preset details and configuration
"""
def create_upload_preset(**options):
"""Create a new upload preset.
Args:
name (str, optional): Name for the new upload preset
unsigned (bool, optional): Whether preset is unsigned (public)
disallow_public_id (bool, optional): Prevent public ID override during upload
live (bool, optional): Whether preset is for live (video) usage
**options: Upload configuration parameters (folder, tags, transformations, etc.)
Returns:
dict: Created upload preset details
"""
def update_upload_preset(name, **options):
"""Update an existing upload preset.
Args:
name (str): Name of the upload preset to update
unsigned (bool, optional): Whether preset is unsigned (public)
disallow_public_id (bool, optional): Prevent public ID override during upload
live (bool, optional): Whether preset is for live (video) usage
**options: Upload configuration parameters to update
Returns:
dict: Updated upload preset details
"""
def delete_upload_preset(name, **options):
"""Delete an upload preset.
Args:
name (str): Name of the upload preset to delete
**options: Additional options
Returns:
dict: Result of the deletion
"""Folder Management
Organize resources using folder structures and hierarchies.
def root_folders(**options):
"""List all top-level folders in your account.
Args:
next_cursor (str, optional): Cursor for pagination
max_results (int, optional): Maximum results to return
**options: Additional options
Returns:
dict: Response containing:
- folders (list): List of top-level folder objects
- next_cursor (str): Cursor for next page
"""
def subfolders(of_folder_path, **options):
"""List subfolders of a given folder path.
Args:
of_folder_path (str): Path of the parent folder
next_cursor (str, optional): Cursor for pagination
max_results (int, optional): Maximum results to return
**options: Additional options
Returns:
dict: Response containing subfolders of the specified path
"""
def create_folder(path, **options):
"""Create a new folder at the specified path.
Args:
path (str): Path for the new folder
**options: Additional options
Returns:
dict: Result of the folder creation
"""
def rename_folder(from_path, to_path, **options):
"""Rename/move a folder from one path to another.
Args:
from_path (str): Current full path of the folder
to_path (str): New full path for the folder
**options: Additional options
Returns:
dict: Result of the rename operation
"""
def delete_folder(path, **options):
"""Delete a folder (must be empty).
Args:
path (str): Path of the folder to delete
skip_backup (bool, optional): Skip backing up before deletion
**options: Additional options
Returns:
dict: Result of the folder deletion
"""Backup and Restore Operations
Manage resource backups and restore deleted assets.
def restore(public_ids, **options):
"""Restore deleted resources by public IDs from backups.
Args:
public_ids (list): List of public IDs to restore
versions (list, optional): Specific version IDs to restore
resource_type (str, optional): Resource type (default: "image")
type (str, optional): Upload type (default: "upload")
**options: Additional options
Returns:
dict: Result of the restore operation
"""
def restore_by_asset_ids(asset_ids, **options):
"""Restore deleted resources by asset IDs from backups.
Args:
asset_ids (list): List of asset IDs to restore
versions (list, optional): Specific version IDs to restore
**options: Additional options
Returns:
dict: Result of the restore operation
"""Upload Mapping Management
Configure custom upload URL mappings for folder organization.
def upload_mappings(**options):
"""List all upload mappings in your account.
Args:
next_cursor (str, optional): Cursor for pagination
max_results (int, optional): Maximum results to return
**options: Additional options
Returns:
dict: Response containing:
- mappings (list): List of upload mapping objects
- next_cursor (str): Cursor for next page
"""
def upload_mapping(name, **options):
"""Get details of a specific upload mapping by folder name.
Args:
name (str): Folder name of the upload mapping
**options: Additional options
Returns:
dict: Upload mapping details
"""
def create_upload_mapping(name, **options):
"""Create a new upload mapping.
Args:
name (str): Folder name for the mapping
template (str, optional): URL template for the folder
**options: Additional options
Returns:
dict: Created upload mapping details
"""
def update_upload_mapping(name, **options):
"""Update an existing upload mapping.
Args:
name (str): Folder name of the mapping to update
template (str, optional): URL template for the folder
**options: Additional update options
Returns:
dict: Updated upload mapping details
"""
def delete_upload_mapping(name, **options):
"""Delete an upload mapping by folder name.
Args:
name (str): Folder name of the mapping to delete
**options: Additional options
Returns:
dict: Result of the deletion
"""Streaming Profile Management
Manage adaptive streaming profiles for video delivery optimization.
def list_streaming_profiles(**options):
"""List all custom and built-in streaming profiles.
Args:
**options: Additional options
Returns:
dict: Response containing:
- data (list): List of streaming profile objects
"""
def get_streaming_profile(name, **options):
"""Get details of a specific streaming profile.
Args:
name (str): Name of the streaming profile
**options: Additional options
Returns:
dict: Streaming profile details and configuration
"""
def create_streaming_profile(name, **options):
"""Create a new custom streaming profile.
Args:
name (str): Name for the new streaming profile
display_name (str, optional): Display name for the profile
representations (list, optional): List of transformation objects or strings
**options: Additional options
Returns:
dict: Created streaming profile details
"""
def update_streaming_profile(name, **options):
"""Update an existing streaming profile.
Args:
name (str): Name of the streaming profile to update
display_name (str, optional): Display name for the profile
representations (list, optional): List of transformation objects or strings
**options: Additional update options
Returns:
dict: Updated streaming profile details
"""
def delete_streaming_profile(name, **options):
"""Delete a streaming profile (or revert built-in profile to default).
Args:
name (str): Name of the streaming profile to delete
**options: Additional options
Returns:
dict: Result of the deletion
"""Metadata Field Management
Define and manage structured metadata fields for resource organization.
def list_metadata_fields(**options):
"""List all metadata field definitions.
Args:
**options: Additional options
Returns:
dict: Response containing:
- metadata_fields (list): List of metadata field definitions
"""
def metadata_field_by_field_id(field_external_id, **options):
"""Get a specific metadata field by external ID.
Args:
field_external_id (str): External ID of the metadata field
**options: Additional options
Returns:
dict: Metadata field details and configuration
"""
def add_metadata_field(field, **options):
"""Create a new metadata field definition.
Args:
field (dict): Field definition containing:
- type (str): Field type ('string', 'integer', 'date', 'enum', etc.)
- external_id (str): External identifier for the field
- label (str): Display label for the field
- mandatory (bool, optional): Whether field is required
- restrictions (dict, optional): Field validation rules
- default_value (any, optional): Default value for the field
- default_disabled (bool, optional): Whether field is disabled by default
- validation (dict, optional): Additional validation rules
- datasource (dict, optional): Data source configuration for enum fields
- allow_dynamic_list_values (bool, optional): Allow dynamic values for list fields
**options: Additional options
Returns:
dict: Created metadata field details
"""
def update_metadata_field(field_external_id, field, **options):
"""Update an existing metadata field.
Args:
field_external_id (str): External ID of the field to update
field (dict): Updated field definition (same structure as add_metadata_field)
**options: Additional options
Returns:
dict: Updated metadata field details
"""
def delete_metadata_field(field_external_id, **options):
"""Delete a metadata field definition.
Args:
field_external_id (str): External ID of the field to delete
**options: Additional options
Returns:
dict: Result of the deletion with "message" key
"""
def delete_datasource_entries(field_external_id, entries_external_id, **options):
"""Delete entries from a metadata field datasource.
Args:
field_external_id (str): External ID of the metadata field
entries_external_id (list): List of entry external IDs to delete
**options: Additional options
Returns:
dict: Result of the datasource entry deletion
"""
def update_metadata_field_datasource(field_external_id, entries_external_id, **options):
"""Update or add entries to a metadata field datasource.
Args:
field_external_id (str): External ID of the metadata field
entries_external_id (list): List of entry objects with 'external_id' and 'value' keys
**options: Additional options
Returns:
dict: Updated metadata field details
"""
def restore_metadata_field_datasource(field_external_id, entries_external_ids, **options):
"""Restore (unblock) entries in a metadata field datasource.
Args:
field_external_id (str): External ID of the metadata field
entries_external_ids (list): List of entry external IDs to restore
**options: Additional options
Returns:
dict: Result of the restore operation
"""
def reorder_metadata_field_datasource(field_external_id, order_by, direction=None, **options):
"""Reorder entries in a metadata field datasource.
Args:
field_external_id (str): External ID of the metadata field
order_by (str): Ordering criteria (currently supports 'value')
direction (str, optional): Sort direction ('asc' or 'desc')
**options: Additional options
Returns:
dict: Result of the reordering operation
"""
def reorder_metadata_fields(order_by, direction=None, **options):
"""Reorder metadata fields.
Args:
order_by (str): Ordering criteria ('label', 'external_id', 'created_at')
direction (str, optional): Sort direction ('asc' or 'desc')
**options: Additional options
Returns:
dict: Result of the reordering operation
"""Metadata Rules Management
Create and manage automated metadata rules for dynamic asset tagging.
def list_metadata_rules(**options):
"""List all metadata rule definitions.
Args:
**options: Additional options
Returns:
dict: Response containing:
- metadata_rules (list): List of metadata rule definitions
"""
def add_metadata_rule(rule, **options):
"""Create a new metadata rule definition.
Args:
rule (dict): Rule definition containing:
- external_id (str): External identifier for the rule
- metadata_field_id (str): ID of the target metadata field
- condition (dict): Rule condition configuration
- result (dict): Rule result/action configuration
- name (str): Display name for the rule
- state (str, optional): Rule state ('active', 'inactive')
**options: Additional options
Returns:
dict: Created metadata rule details
"""
def update_metadata_rule(rule_external_id, rule, **options):
"""Update an existing metadata rule.
Args:
rule_external_id (str): External ID of the rule to update
rule (dict): Updated rule definition (same structure as add_metadata_rule)
**options: Additional options
Returns:
dict: Updated metadata rule details
"""
def delete_metadata_rule(rule_external_id, **options):
"""Delete a metadata rule definition.
Args:
rule_external_id (str): External ID of the rule to delete
**options: Additional options
Returns:
dict: Result of the deletion with "success" key
"""Advanced Configuration
Access account configuration and resource type information.
def config(**options):
"""Get account configuration details.
Args:
settings (bool, optional): Include extended settings in response
**options: Additional options
Returns:
dict: Detailed account configuration information including:
- cloud_name (str): Account cloud name
- api_key (str): API key (masked)
- settings (dict): Extended configuration settings (if requested)
"""
def resource_types(**options):
"""Get available resource types in your account.
Args:
**options: Additional options
Returns:
dict: Response containing:
- resource_types (list): List of available resource types
"""Analysis Operations
Perform AI-powered analysis on resources for enhanced metadata and insights.
def analyze(input_type, analysis_type, uri=None, **options):
"""Analyze an asset with the specified analysis type.
Args:
input_type (str): Type of input for the asset ('uri')
analysis_type (str): Type of analysis ('google_tagging', 'captioning', 'fashion', 'coco', 'lvis', 'unidet', 'shop')
uri (str, optional): URI of the asset to analyze
parameters (dict, optional): Additional analysis parameters
**options: Additional options
Returns:
dict: Analysis results containing extracted information based on analysis type
"""Usage Examples
Resource Discovery
from cloudinary import api
# List recent resources
result = api.resources(max_results=50)
for resource in result['resources']:
print(f"{resource['public_id']}: {resource['format']} ({resource['bytes']} bytes)")
# List resources with full metadata
result = api.resources(
tags=True,
context=True,
metadata=True,
max_results=20
)
# List resources by tag
result = api.resources_by_tag("featured", max_results=100)
# List resources by prefix
result = api.resources(prefix="products/", max_results=100)
# Paginate through all resources
next_cursor = None
all_resources = []
while True:
result = api.resources(
max_results=500,
next_cursor=next_cursor
)
all_resources.extend(result['resources'])
next_cursor = result.get('next_cursor')
if not next_cursor:
breakResource Details and Updates
# Get detailed resource information
resource = api.resource(
"sample_image",
colors=True,
faces=True,
quality_analysis=True,
coordinates=True
)
print(f"Dimensions: {resource['width']}x{resource['height']}")
print(f"Colors: {resource.get('colors', [])}")
print(f"Faces: {resource.get('faces', [])}")
# Update resource metadata
result = api.update(
"sample_image",
tags=["updated", "processed"],
context={"status": "processed", "version": "2.0"},
metadata={"category": "electronics", "featured": "true"}
)
# Apply auto-tagging
result = api.update(
"sample_image",
auto_tagging=0.8,
categorization="google_tagging"
)Bulk Operations
# Delete multiple resources
result = api.delete_resources([
"old_image_1",
"old_image_2",
"old_image_3"
])
# Delete by prefix
result = api.delete_resources_by_prefix("temp/")
# Delete by tag
result = api.delete_resources_by_tag("to_delete")
# Get all tags
result = api.tags(max_results=1000)
all_tags = result['tags']Transformation Management
# List all transformations
result = api.transformations()
for trans in result['transformations']:
print(f"Transformation: {trans['name']}")
# Create named transformation
result = api.create_transformation(
"product_thumb",
{"width": 300, "height": 300, "crop": "fill", "quality": "auto"}
)
# Get transformation details
trans_info = api.transformation("product_thumb")
print(f"Used: {trans_info['used']} times")
# Update transformation
api.update_transformation(
"product_thumb",
allowed_for_strict=True
)
# Delete transformation
api.delete_transformation("old_transformation")Account Management
# Test API connection
result = api.ping()
print(f"Status: {result['status']}")
# Get usage statistics
usage = api.usage()
print(f"Plan: {usage['plan']}")
print(f"Credits used: {usage['credits']['used']}/{usage['credits']['limit']}")
print(f"Bandwidth: {usage['bandwidth']['bytes']} bytes")
print(f"Storage: {usage['storage']['bytes']} bytes")
print(f"Resources: {usage['resources']} total")Visual Search and Discovery
# Search for similar images using an uploaded image
similar_results = api.visual_search(
image_asset_id="sample_image_id"
)
for resource in similar_results['resources']:
print(f"Similar image: {resource['public_id']} (score: {resource.get('score', 'N/A')})")
# Search using an external image URL
url_results = api.visual_search(
image_url="https://example.com/search-image.jpg"
)
# Search using text description
text_results = api.visual_search(
text="red sports car"
)
# Search with local image file
with open("search_image.jpg", "rb") as f:
file_results = api.visual_search(image_file=f)Extended Resource Management
# Get resource by asset ID with full details
asset_details = api.resource_by_asset_id(
"abc123def456",
exif=True,
colors=True,
faces=True,
quality_analysis=True,
accessibility_analysis=True,
related=True
)
print(f"Asset: {asset_details['public_id']}")
print(f"Quality score: {asset_details.get('quality_analysis', {}).get('focus')}")
# List resources in a specific asset folder
folder_resources = api.resources_by_asset_folder(
"product_images/electronics",
max_results=100
)
print(f"Found {len(folder_resources['resources'])} resources in folder")
# Get multiple resources by their asset IDs
asset_ids = ["abc123", "def456", "ghi789"]
multi_assets = api.resources_by_asset_ids(
asset_ids,
tags=True,
context=True
)Asset Relationships
# Add related assets to create content associations
api.add_related_assets(
"main_product_image",
[
"image/upload/product_detail_1",
"image/upload/product_detail_2",
"video/upload/product_demo"
]
)
# Add related assets using asset IDs
api.add_related_assets_by_asset_ids(
"main_asset_id",
["related_asset_1", "related_asset_2"]
)
# Remove asset relationships
api.delete_related_assets(
"main_product_image",
["image/upload/old_related_image"]
)Advanced Deletion and Publishing
# Delete resources by asset IDs
api.delete_resources_by_asset_ids(
["asset1", "asset2", "asset3"],
invalidate=True
)
# Delete specific derived transformations
api.delete_derived_by_transformation(
["product_1", "product_2"],
[
{"width": 300, "height": 300, "crop": "fill"},
{"width": 150, "height": 150, "crop": "thumb"}
],
invalidate=True
)
# Publish private resources to make them publicly accessible
api.publish_by_prefix(
"products/featured/",
overwrite=True,
invalidate=True
)
# Publish resources with specific tag
api.publish_by_tag(
"ready_for_production",
resource_type="image"
)Upload Presets and Configuration
# List all upload presets
presets = api.upload_presets()
for preset in presets['presets']:
print(f"Preset: {preset['name']} (unsigned: {preset.get('unsigned', False)})")
# Create a new upload preset for product images
api.create_upload_preset(
name="product_images",
folder="products",
tags=["product", "auto-uploaded"],
transformation=[
{"width": 800, "height": 600, "crop": "limit"},
{"quality": "auto", "format": "auto"}
],
auto_tagging=0.7,
categorization="google_tagging"
)
# Update existing upload preset
api.update_upload_preset(
"product_images",
tags=["product", "auto-uploaded", "v2"],
context={"version": "2.0", "department": "marketing"}
)Folder Organization
# List top-level folders
folders = api.root_folders()
for folder in folders['folders']:
print(f"Folder: {folder['name']} (path: {folder['path']})")
# Create folder hierarchy
api.create_folder("products/electronics/smartphones")
# List subfolders
electronics_subfolders = api.subfolders("products/electronics")
# Rename/move folder
api.rename_folder("products/old_category", "products/electronics/legacy")
# Delete empty folder
api.delete_folder("products/temp_folder")Backup and Restore
# Restore deleted resources from backup
restored = api.restore([
"accidentally_deleted_1",
"accidentally_deleted_2"
])
print(f"Restored {len(restored['restored'])} resources")
# Restore specific versions
api.restore(
["resource_with_versions"],
versions=["v1234567890", "v0987654321"]
)
# Restore by asset IDs
api.restore_by_asset_ids([
"asset_id_1",
"asset_id_2"
])Streaming Profiles (Video)
# List all streaming profiles
profiles = api.list_streaming_profiles()
for profile in profiles['data']:
print(f"Profile: {profile['name']} - {profile.get('display_name', '')}")
# Create custom streaming profile for mobile optimization
api.create_streaming_profile(
"mobile_optimized",
display_name="Mobile Optimized Streaming",
representations=[
{"bit_rate": "500k", "height": 360, "video_codec": "h264"},
{"bit_rate": "1000k", "height": 720, "video_codec": "h264"},
{"bit_rate": "2000k", "height": 1080, "video_codec": "h264"}
]
)
# Update streaming profile
api.update_streaming_profile(
"mobile_optimized",
display_name="Mobile & Tablet Optimized"
)Metadata Fields and Rules
# List all metadata fields
fields = api.list_metadata_fields()
for field in fields['metadata_fields']:
print(f"Field: {field['label']} ({field['type']}) - ID: {field['external_id']}")
# Create a new enum metadata field
api.add_metadata_field({
"type": "enum",
"external_id": "product_category",
"label": "Product Category",
"mandatory": True,
"datasource": {
"values": [
{"external_id": "electronics", "value": "Electronics"},
{"external_id": "clothing", "value": "Clothing"},
{"external_id": "books", "value": "Books"}
]
}
})
# Create metadata rule for auto-tagging
api.add_metadata_rule({
"external_id": "auto_tag_products",
"name": "Auto-tag Product Images",
"metadata_field_id": "product_category",
"condition": {
"type": "and",
"conditions": [
{"field": "folder", "operator": "starts_with", "value": "products/"},
{"field": "width", "operator": "greater_than", "value": 500}
]
},
"result": {
"metadata_field_id": "product_category",
"value": "electronics"
}
})
# Update metadata field datasource
api.update_metadata_field_datasource(
"product_category",
[
{"external_id": "home_garden", "value": "Home & Garden"},
{"external_id": "sports", "value": "Sports & Recreation"}
]
)Analysis and AI Features
# Perform Google tagging analysis
tagging_result = api.analyze(
"uri",
"google_tagging",
uri="image/upload/sample_image",
parameters={"confidence_threshold": 0.7}
)
print("Detected tags:", tagging_result.get('tags', []))
# Generate image captions
caption_result = api.analyze(
"uri",
"captioning",
uri="image/upload/sample_image"
)
print("Generated caption:", caption_result.get('caption'))
# Fashion analysis for clothing images
fashion_result = api.analyze(
"uri",
"fashion",
uri="image/upload/clothing_item"
)
print("Fashion attributes:", fashion_result.get('attributes', []))Install with Tessl CLI
npx tessl i tessl/pypi-cloudinarydocs
evals
scenario-1
scenario-2
scenario-3
scenario-4
scenario-5
scenario-6
scenario-7
scenario-8
scenario-9
scenario-10