0
# Cloudinary Python SDK
1

2
A comprehensive Python and Django SDK for Cloudinary, a cloud-based image and video management service. The SDK provides complete integration for uploading, transforming, optimizing, and delivering media assets with extensive transformation capabilities, automatic optimization, and seamless Django integration.
3

4
## Package Information
5

6
- **Package Name**: cloudinary
7
- **Language**: Python
8
- **Installation**: `pip install cloudinary`
9
- **Repository**: https://github.com/cloudinary/pycloudinary
10

11
## Core Imports
12

13
```python
14
import cloudinary
15
```
16

17
Common for configuration and basic usage:
18

19
```python
20
from cloudinary import config, CloudinaryImage, CloudinaryVideo
21
```
22

23
Common for uploading media:
24

25
```python
26
from cloudinary import uploader
27
```
28

29
Common for Admin API operations:
30

31
```python
32
from cloudinary import api
33
```
34

35
## Basic Usage
36

37
```python
38
import cloudinary
39
from cloudinary import uploader
40
from cloudinary.utils import cloudinary_url
41

42
# Configure your account
43
cloudinary.config(
44
    cloud_name="your_cloud_name",
45
    api_key="your_api_key",
46
    api_secret="your_api_secret"
47
)
48

49
# Upload an image
50
upload_result = uploader.upload("path/to/image.jpg")
51
public_id = upload_result['public_id']
52

53
# Generate a transformation URL
54
url, options = cloudinary_url(
55
    public_id,
56
    width=300,
57
    height=200,
58
    crop="fill",
59
    format="webp"
60
)
61

62
# Create CloudinaryImage object for advanced operations
63
image = CloudinaryImage(public_id)
64
transformed_url = image.build_url(
65
    width=400,
66
    height=300,
67
    crop="scale",
68
    quality="auto"
69
)
70
```
71

72
## Architecture
73

74
The SDK is organized around several key components:
75

76
- **Configuration**: Global and account-specific settings management
77
- **Resource Classes**: CloudinaryImage and CloudinaryVideo for media manipulation
78
- **Upload API**: Functions for uploading media files with preprocessing
79
- **Admin API**: Complete resource management and account administration
80
- **Transformation Engine**: URL-based image and video transformation system
81
- **Django Integration**: Models, forms, and template tags for web applications
82
- **Caching System**: Performance optimization for repeated operations
83
- **Search API**: Advanced asset discovery and filtering
84

85
## Capabilities
86

87
### Configuration and Setup
88

89
Global configuration management for Cloudinary account credentials, default transformation parameters, and SDK behavior settings.
90

91
```python { .api }
92
def config(**keywords):
93
    """Configure Cloudinary account settings and defaults.
94
    
95
    Args:
96
        cloud_name (str): Your Cloudinary cloud name
97
        api_key (str): Your API key
98
        api_secret (str): Your API secret
99
        secure (bool): Use HTTPS URLs (default: True)
100
        cdn_subdomain (bool): Use multiple CDN subdomains
101
        **kwargs: Additional configuration options
102
    
103
    Returns:
104
        Config: Configuration object
105
    """
106

107
def reset_config():
108
    """Reset configuration to defaults."""
109

110
class Config:
111
    """Configuration object for Cloudinary settings."""
112

113
class CloudinaryResource:
114
    """Base class for Cloudinary media resources."""
115

116
class CloudinaryImage(CloudinaryResource):
117
    """Image-specific resource class with transformation capabilities."""
118

119
class CloudinaryVideo(CloudinaryResource):
120
    """Video-specific resource class with transformation capabilities."""
121
```
122

123
[Configuration and Setup](./configuration.md)
124

125
### Upload API
126

127
Comprehensive media upload functionality with preprocessing options, format conversion, and metadata extraction for images, videos, and raw files.
128

129
```python { .api }
130
def upload(file, **options):
131
    """Upload a file to Cloudinary.
132
    
133
    Args:
134
        file: File path, file object, or URL to upload
135
        public_id (str, optional): Custom public ID
136
        folder (str, optional): Folder to store the asset
137
        use_filename (bool, optional): Use original filename
138
        unique_filename (bool, optional): Add unique suffix
139
        overwrite (bool, optional): Overwrite existing asset
140
        **options: Additional upload parameters
141
    
142
    Returns:
143
        dict: Upload result with public_id, url, secure_url, etc.
144
    """
145

146
def destroy(public_id, **options):
147
    """Delete an uploaded asset.
148
    
149
    Args:
150
        public_id (str): Public ID of asset to delete
151
        **options: Additional deletion options
152
    
153
    Returns:
154
        dict: Deletion result
155
    """
156

157
def rename(from_public_id, to_public_id, **options):
158
    """Rename an uploaded asset.
159
    
160
    Args:
161
        from_public_id (str): Current public ID
162
        to_public_id (str): New public ID
163
        **options: Additional options
164
    
165
    Returns:
166
        dict: Rename result
167
    """
168
```
169

170
[Upload API](./upload-api.md)
171

172
### Admin API
173

174
Complete resource management including asset discovery, metadata operations, transformation management, and account administration.
175

176
```python { .api }
177
def resources(**options):
178
    """List uploaded resources with filtering options.
179
    
180
    Args:
181
        resource_type (str, optional): Filter by resource type
182
        type (str, optional): Filter by delivery type
183
        prefix (str, optional): Filter by public_id prefix
184
        max_results (int, optional): Maximum results to return
185
        **options: Additional filtering options
186
    
187
    Returns:
188
        dict: List of resources with metadata
189
    """
190

191
def resource(public_id, **options):
192
    """Get details of a specific resource.
193
    
194
    Args:
195
        public_id (str): Public ID of the resource
196
        **options: Additional options
197
    
198
    Returns:
199
        dict: Resource details and metadata
200
    """
201

202
def delete_resources(public_ids, **options):
203
    """Delete multiple resources.
204
    
205
    Args:
206
        public_ids (list): List of public IDs to delete
207
        **options: Additional deletion options
208
    
209
    Returns:
210
        dict: Deletion results
211
    """
212
```
213

214
[Admin API](./admin-api.md)
215

216
### URL Generation and Transformations
217

218
Powerful URL-based transformation system for images and videos with automatic optimization, responsive delivery, and format conversion.
219

220
```python { .api }
221
def cloudinary_url(public_id, **options):
222
    """Generate Cloudinary URL with transformations.
223
    
224
    Args:
225
        public_id (str): Public ID of the resource
226
        width (int, optional): Target width
227
        height (int, optional): Target height
228
        crop (str, optional): Crop mode ('fill', 'scale', 'fit', etc.)
229
        quality (str|int, optional): Quality setting or 'auto'
230
        format (str, optional): Output format or 'auto'
231
        secure (bool, optional): Use HTTPS
232
        **options: Additional transformation parameters
233
    
234
    Returns:
235
        tuple: (url, options_dict)
236
    """
237

238
def cloudinary_tag(public_id, **options):
239
    """Generate HTML img tag with Cloudinary URL.
240
    
241
    Args:
242
        public_id (str): Public ID of the resource
243
        **options: Transformation and HTML attributes
244
    
245
    Returns:
246
        str: HTML img tag
247
    """
248
```
249

250
[URL Generation and Transformations](./transformations.md)
251

252
### Search API
253

254
Advanced asset discovery with filtering, sorting, and aggregation capabilities for finding specific resources in your Cloudinary account.
255

256
```python { .api }
257
class Search:
258
    """Search for resources using various criteria."""
259
    
260
    def expression(self, value):
261
        """Set search expression."""
262
    
263
    def max_results(self, value):
264
        """Set maximum results to return."""
265
    
266
    def next_cursor(self, value):
267
        """Set cursor for pagination."""
268
    
269
    def sort_by(self, field, direction="desc"):
270
        """Add sort criteria."""
271
    
272
    def aggregate(self, value):
273
        """Add aggregation."""
274
    
275
    def with_field(self, value):
276
        """Include additional fields in results."""
277
    
278
    def execute(self, **options):
279
        """Execute the search query."""
280
```
281

282
[Search API](./search-api.md)
283

284
### Provisioning API
285

286
Complete account provisioning and management including sub-account creation, user management, access key generation, and multi-tenant environment setup.
287

288
```python { .api }
289
def create_sub_account(name, **options):
290
    """Create a new sub-account for multi-tenant environments.
291
    
292
    Args:
293
        name (str): Name for the sub-account
294
        **options: Additional sub-account configuration
295
    
296
    Returns:
297
        dict: Sub-account details with cloud_name and credentials
298
    """
299

300
def create_user(name, email, role, **options):
301
    """Create a new user with specified permissions.
302
    
303
    Args:
304
        name (str): User's display name
305
        email (str): User's email address  
306
        role (str): User role (Admin, Developer, Billing, etc.)
307
        **options: Additional user configuration
308
    
309
    Returns:
310
        dict: User details with ID and access credentials
311
    """
312

313
def generate_access_key(name, **options):
314
    """Generate API access keys for programmatic access.
315
    
316
    Args:
317
        name (str): Descriptive name for the access key
318
        **options: Key configuration and permissions
319
    
320
    Returns:
321
        dict: Access key details with api_key and api_secret
322
    """
323
```
324

325
[Provisioning API](./provisioning-api.md)
326

327
### Django Integration
328

329
Complete Django framework integration including model fields, form widgets, template tags, and admin interface components.
330

331
```python { .api }
332
class CloudinaryField(models.Field):
333
    """Django model field for Cloudinary resources."""
334

335
class CloudinaryInput(forms.TextInput):
336
    """Django form widget for Cloudinary file input."""
337

338
class CloudinaryFileField(forms.FileField):
339
    """Django form field for Cloudinary file uploads."""
340

341
def cloudinary_url():
342
    """Django template tag for generating Cloudinary URLs."""
343

344
def cloudinary_tag():
345
    """Django template tag for generating Cloudinary image tags."""
346
```
347

348
[Django Integration](./django-integration.md)
349

350
### Exception Handling
351

352
Comprehensive exception hierarchy for handling API errors, authentication issues, and operational failures.
353

354
```python { .api }
355
class Error(Exception):
356
    """Base exception class for Cloudinary errors."""
357

358
class NotFound(Error):
359
    """Resource not found exception."""
360

361
class NotAllowed(Error):
362
    """Operation not allowed exception."""
363

364
class BadRequest(Error):
365
    """Bad request exception."""
366

367
class AuthorizationRequired(Error):
368
    """Authorization required exception."""
369
```
370

371
[Exception Handling](./exceptions.md)