0
# Upload API
1

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

4
## Capabilities
5

6
### File Upload
7

8
Upload files to Cloudinary with extensive customization options.
9

10
```python { .api }
11
def upload(file, **options):
12
    """Upload a file to Cloudinary.
13
    
14
    Args:
15
        file: File path (str), file object, URL (str), or base64 data URI
16
        public_id (str, optional): Custom public ID for the uploaded asset
17
        folder (str, optional): Folder path to store the asset
18
        use_filename (bool, optional): Use original filename as public_id
19
        unique_filename (bool, optional): Add unique suffix to prevent conflicts
20
        overwrite (bool, optional): Overwrite existing asset with same public_id
21
        resource_type (str, optional): Type of resource ('image', 'video', 'raw', 'auto')
22
        type (str, optional): Delivery type ('upload', 'private', 'authenticated')
23
        tags (list, optional): List of tags to assign to the asset
24
        context (dict, optional): Key-value pairs of contextual metadata
25
        metadata (dict, optional): Structured metadata key-value pairs
26
        transformation (dict, optional): Eager transformation to apply
27
        eager (list, optional): List of transformations to generate immediately
28
        eager_async (bool, optional): Generate eager transformations asynchronously
29
        eager_notification_url (str, optional): URL for eager transformation notifications
30
        format (str, optional): Convert to specified format during upload
31
        allowed_formats (list, optional): Restrict upload to specific formats
32
        async (bool, optional): Return immediately, process upload asynchronously
33
        backup (bool, optional): Create backup copy
34
        faces (bool, optional): Extract face coordinates
35
        colors (bool, optional): Extract predominant colors
36
        image_metadata (bool, optional): Extract image metadata (EXIF, IPTC, XMP)
37
        media_metadata (bool, optional): Extract media metadata
38
        auto_tagging (float, optional): Automatic tagging confidence threshold
39
        categorization (str, optional): Automatic categorization model
40
        detection (str, optional): Object detection model
41
        ocr (str, optional): Optical Character Recognition model
42
        **kwargs: Additional upload parameters
43
    
44
    Returns:
45
        dict: Upload result containing:
46
            - public_id (str): The public ID of the uploaded asset
47
            - version (int): Version identifier
48
            - signature (str): Unique signature
49
            - width (int): Image/video width in pixels
50
            - height (int): Image/video height in pixels
51
            - format (str): File format
52
            - resource_type (str): Type of resource
53
            - created_at (str): Upload timestamp
54
            - url (str): HTTP URL for accessing the asset
55
            - secure_url (str): HTTPS URL for accessing the asset
56
            - bytes (int): File size in bytes
57
            - etag (str): Entity tag
58
            - tags (list): Applied tags
59
            - context (dict): Contextual metadata
60
            - metadata (dict): Structured metadata
61
            - faces (list): Detected face coordinates (if faces=True)
62
            - colors (list): Predominant colors (if colors=True)
63
            - info (dict): Additional asset information
64
            - eager (list): Generated eager transformations
65
    """
66

67
def unsigned_upload(file, upload_preset, **options):
68
    """Upload a file using an unsigned upload preset.
69
    
70
    Args:
71
        file: File to upload (same formats as upload())
72
        upload_preset (str): Name of the unsigned upload preset
73
        **options: Additional upload options (subset of upload() options)
74
    
75
    Returns:
76
        dict: Upload result (same format as upload())
77
    """
78
```
79

80
### Asset Management
81

82
Delete, rename, and manage uploaded assets.
83

84
```python { .api }
85
def destroy(public_id, **options):
86
    """Delete an uploaded asset.
87
    
88
    Args:
89
        public_id (str): Public ID of the asset to delete
90
        resource_type (str, optional): Type of resource ('image', 'video', 'raw')
91
        type (str, optional): Delivery type ('upload', 'private', 'authenticated')
92
        invalidate (bool, optional): Invalidate CDN cache
93
    
94
    Returns:
95
        dict: Deletion result containing:
96
            - result (str): 'ok' if successful
97
            - partial (bool): Whether deletion was partial
98
    """
99

100
def rename(from_public_id, to_public_id, **options):
101
    """Rename an uploaded asset.
102
    
103
    Args:
104
        from_public_id (str): Current public ID
105
        to_public_id (str): New public ID
106
        resource_type (str, optional): Type of resource
107
        type (str, optional): Delivery type
108
        to_type (str, optional): Target delivery type
109
        overwrite (bool, optional): Overwrite existing asset at destination
110
        invalidate (bool, optional): Invalidate CDN cache
111
    
112
    Returns:
113
        dict: Rename result
114
    """
115

116
def explicit(public_id, **options):
117
    """Perform explicit operations on an already uploaded asset.
118
    
119
    Args:
120
        public_id (str): Public ID of the asset
121
        resource_type (str, optional): Type of resource
122
        type (str, optional): Delivery type
123
        eager (list, optional): Transformations to generate
124
        eager_async (bool, optional): Generate transformations asynchronously
125
        eager_notification_url (str, optional): Notification URL for completion
126
        headers (dict, optional): Custom headers for generated URLs
127
        tags (list, optional): Tags to assign/replace
128
        face_coordinates (str, optional): Custom face coordinates
129
        custom_coordinates (str, optional): Custom crop coordinates
130
        context (dict, optional): Contextual metadata to assign/replace
131
        metadata (dict, optional): Structured metadata to assign/replace
132
        background_removal (str, optional): Background removal mode
133
        **kwargs: Additional transformation options
134
    
135
    Returns:
136
        dict: Operation result with generated transformations and URLs
137
    """
138
```
139

140
### Sprite and Multi-Image Generation
141

142
Create sprites, collages, and multi-format outputs from multiple images.
143

144
```python { .api }
145
def generate_sprite(tag=None, urls=None, **options):
146
    """Generate sprites by merging multiple images into a single large image.
147
    
148
    Args:
149
        tag (str, optional): Images with this tag will be used to create the sprite
150
        urls (list, optional): List of URLs to create a sprite from (if tag not set)
151
        transformation (dict, optional): Transformation to apply to each image before merging
152
        format (str, optional): Format of the generated sprite (png, jpg, etc.)
153
        mode (str, optional): Sprite generation mode ('horizontal', 'vertical', 'packed')
154
        notification_url (str, optional): URL to notify when sprite generation completes
155
        async (bool, optional): Generate sprite asynchronously
156
        **kwargs: Additional sprite configuration options
157
    
158
    Returns:
159
        dict: Sprite generation result containing:
160
            - public_id (str): Public ID of the generated sprite
161
            - version (int): Version identifier
162
            - url (str): HTTP URL for accessing the sprite
163
            - secure_url (str): HTTPS URL for accessing the sprite
164
            - css_url (str): URL to generated CSS file with sprite coordinates
165
            - image_infos (list): Information about each image in the sprite
166
    """
167

168
def download_generated_sprite(tag=None, urls=None, **options):
169
    """Generate a downloadable URL for the sprite.
170
    
171
    Args:
172
        tag (str, optional): Images with this tag will be used to create the sprite
173
        urls (list, optional): List of URLs to create a sprite from (if tag not set)
174
        **options: Same options as generate_sprite()
175
    
176
    Returns:
177
        str: Signed URL to download the sprite
178
    """
179

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

203
def download_multi(tag=None, urls=None, **options):
204
    """Generate a downloadable URL for the multi-asset.
205
    
206
    Args:
207
        tag (str, optional): Assets with this tag will be used
208
        urls (list, optional): List of image URLs (if no tag is set)
209
        **options: Same options as multi()
210
    
211
    Returns:
212
        str: Signed URL to download the multi-asset
213
    """
214
```
215

216
### Multi-file Operations
217

218
Upload multiple files and perform batch operations.
219

220
```python { .api }
221
def upload_large(file, **options):
222
    """Upload large files using chunked upload.
223
    
224
    Args:
225
        file: Large file to upload
226
        chunk_size (int, optional): Size of each chunk in bytes (default: 20MB)
227
        **options: Same options as upload()
228
    
229
    Returns:
230
        dict: Upload result (same format as upload())
231
    """
232

233
def create_archive(**options):
234
    """Create an archive (ZIP/TAR) from multiple assets.
235
    
236
    Args:
237
        public_ids (list, optional): List of public IDs to include
238
        prefixes (list, optional): List of prefixes to match
239
        tags (list, optional): List of tags to match
240
        target_format (str, optional): Archive format ('zip', 'tgz')
241
        flatten_folders (bool, optional): Flatten folder structure
242
        keep_derived (bool, optional): Include derived assets
243
        resource_type (str, optional): Type of resources to include
244
        type (str, optional): Delivery type of resources
245
        mode (str, optional): Archive creation mode
246
        **kwargs: Additional archive options
247
    
248
    Returns:
249
        dict: Archive creation result with download URL
250
    """
251

252
def create_zip(**options):
253
    """Create a ZIP archive from multiple assets.
254
    
255
    Args:
256
        **options: Same options as create_archive() with target_format='zip'
257
    
258
    Returns:
259
        dict: ZIP creation result
260
    """
261
def explode(public_id, **options):
262
    """Create derived images for all individual pages in a multi-page file.
263
    
264
    Args:
265
        public_id (str): Public ID of the multi-page file to explode
266
        format (str, optional): Format for the generated page images
267
        transformation (dict, optional): Transformation to apply to each page
268
        notification_url (str, optional): URL to notify when explode completes
269
        **kwargs: Additional explode configuration options
270
    
271
    Returns:
272
        dict: Explode operation result containing:
273
            - batch_id (str): ID of the batch operation
274
            - status (str): Operation status
275
    """
276

277
def create_slideshow(**options):
278
    """Create an auto-generated video slideshow from existing assets.
279
    
280
    Args:
281
        manifest_json (dict, optional): JSON specification for slideshow creation
282
        transformation (list, optional): Transformations to apply to the slideshow
283
        manifest_transformation (list, optional): Transformations for the manifest
284
        tags (list, optional): Tags to assign to the generated slideshow
285
        public_id (str, optional): Public ID for the generated slideshow
286
        overwrite (bool, optional): Overwrite existing slideshow with same public_id
287
        notification_url (str, optional): URL to notify when processing completes
288
        upload_preset (str, optional): Upload preset to apply
289
        resource_type (str, optional): Resource type, defaults to "video"
290
        **kwargs: Additional slideshow options
291
    
292
    Returns:
293
        dict: Slideshow creation result containing:
294
            - public_id (str): Public ID of the generated slideshow
295
            - version (int): Version identifier
296
            - url (str): HTTP URL for accessing the slideshow
297
            - secure_url (str): HTTPS URL for accessing the slideshow
298
            - resource_type (str): Type of resource created
299
    """
300
```
301

302
### Text Generation
303

304
Generate dynamic text images with customizable styling.
305

306
```python { .api }
307
def text(text, **options):
308
    """Dynamically generate an image of a given text string.
309
    
310
    Args:
311
        text (str): Text string to generate an image for
312
        public_id (str, optional): Public ID for the generated text image
313
        font_family (str, optional): Font family name
314
        font_size (int, optional): Font size in pixels
315
        font_color (str, optional): Font color (hex, rgb, or named color)
316
        font_weight (str, optional): Font weight ('normal', 'bold', etc.)
317
        font_style (str, optional): Font style ('normal', 'italic', etc.)
318
        text_align (str, optional): Text alignment ('left', 'center', 'right')
319
        text_decoration (str, optional): Text decoration ('none', 'underline', etc.)
320
        background (str, optional): Background color
321
        opacity (int, optional): Text opacity (0-100)
322
        **kwargs: Additional text styling options
323
    
324
    Returns:
325
        dict: Text generation result containing:
326
            - public_id (str): Public ID of the generated text image
327
            - version (int): Version identifier
328
            - url (str): HTTP URL for accessing the text image
329
            - secure_url (str): HTTPS URL for accessing the text image
330
            - width (int): Image width in pixels
331
            - height (int): Image height in pixels
332
    """
333
```
334

335
### Advanced Upload Variations
336

337
Specialized upload functions for different use cases.
338

339
```python { .api }
340
def upload_image(file, **options):
341
    """Upload a file and return a CloudinaryImage object.
342
    
343
    Args:
344
        file: File to upload (same formats as upload())
345
        **options: Same options as upload()
346
    
347
    Returns:
348
        CloudinaryImage: CloudinaryImage object referencing the uploaded image
349
    """
350

351
def upload_resource(file, **options):
352
    """Upload a file and return a CloudinaryResource object.
353
    
354
    Args:
355
        file: File to upload (same formats as upload())
356
        **options: Same options as upload()
357
    
358
    Returns:
359
        CloudinaryResource: CloudinaryResource object (image, video, or raw)
360
    """
361

362
def upload_large_part(file, **options):
363
    """Upload a large chunk (part) of a file to Cloudinary.
364
    
365
    Args:  
366
        file (tuple): Tuple of (filename, chunk_data) for the file part
367
        http_headers (dict, optional): HTTP headers including Content-Range
368
        resource_type (str, optional): Type of resource (defaults to "raw")
369
        **options: Additional parameters for the chunk upload
370
    
371
    Returns:
372
        dict: Chunk upload result (same format as upload())
373
    """
374
```
375

376
### Preprocessing and Analysis
377

378
Extract metadata, perform analysis, and preprocess uploads.
379

380
```python { .api }
381
def add_tag(tag, public_ids, **options):
382
    """Add a tag to multiple assets.
383
    
384
    Args:
385
        tag (str): Tag to add
386
        public_ids (list): List of public IDs to tag
387
        resource_type (str, optional): Type of resources
388
        type (str, optional): Delivery type
389
    
390
    Returns:
391
        dict: Operation result
392
    """
393

394
def remove_tag(tag, public_ids, **options):
395
    """Remove a tag from multiple assets.
396
    
397
    Args:
398
        tag (str): Tag to remove
399
        public_ids (list): List of public IDs to untag
400
        resource_type (str, optional): Type of resources
401
        type (str, optional): Delivery type
402
    
403
    Returns:
404
        dict: Operation result
405
    """
406

407
def replace_tag(tag, public_ids, **options):
408
    """Replace all tags on multiple assets with a single tag.
409
    
410
    Args:
411
        tag (str): Tag to set (replaces all existing tags)
412
        public_ids (list): List of public IDs
413
        resource_type (str, optional): Type of resources
414
        type (str, optional): Delivery type
415
    
416
    Returns:
417
        dict: Operation result
418
    """
419

420
def remove_all_tags(public_ids, **options):
421
    """Remove all tags from the specified assets.
422
    
423
    Args:
424
        public_ids (list): List of public IDs to remove all tags from
425
        resource_type (str, optional): Type of resources
426
        type (str, optional): Delivery type
427
    
428
    Returns:
429
        dict: Operation result
430
    """
431

432
def update_metadata(metadata, public_ids, **options):
433
    """Populate or update metadata fields with given values.
434
    
435
    Args:
436
        metadata (dict): Key-value pairs for custom metadata fields (by external_id)
437
        public_ids (list): List of public IDs to update
438
        resource_type (str, optional): Type of resources (default: "image")
439
        type (str, optional): Delivery type
440
        clear_invalid (bool, optional): Remove keys that are not valid
441
    
442
    Returns:
443
        dict: List of public IDs that were updated
444
    """
445
```
446

447
### Context Management
448

449
Manage contextual metadata for assets.
450

451
```python { .api }
452
def add_context(context, public_ids, **options):
453
    """Add contextual metadata (key-value pairs) to specified assets.
454
    
455
    Args:
456
        context (dict): Dictionary of context key-value pairs
457
        public_ids (list): List of public IDs to update
458
        resource_type (str, optional): Type of resources
459
        type (str, optional): Delivery type
460
    
461
    Returns:
462
        dict: Operation result with list of updated public IDs
463
    """
464

465
def remove_all_context(public_ids, **options):
466
    """Remove all custom contextual metadata from specified assets.
467
    
468
    Args:
469
        public_ids (list): List of public IDs to update
470
        resource_type (str, optional): Type of resources  
471
        type (str, optional): Delivery type
472
    
473
    Returns:
474
        dict: Operation result with list of updated public IDs
475
    """
476
```
477

478
## Usage Examples
479

480
### Basic File Upload
481

482
```python
483
from cloudinary import uploader
484

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

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

493
# Upload with custom public ID
494
result = uploader.upload(
495
    "image.jpg",
496
    public_id="my_custom_id",
497
    overwrite=True
498
)
499

500
# Upload to specific folder
501
result = uploader.upload(
502
    "image.jpg",
503
    folder="products/featured",
504
    use_filename=True,
505
    unique_filename=False
506
)
507
```
508

509
### Advanced Upload Options
510

511
```python
512
# Upload with transformations and metadata
513
result = uploader.upload(
514
    "image.jpg",
515
    public_id="sample_product",
516
    transformation=[
517
        {"width": 1000, "height": 1000, "crop": "limit"},
518
        {"quality": "auto", "format": "auto"}
519
    ],
520
    tags=["product", "featured"],
521
    context={"category": "electronics", "brand": "acme"},
522
    metadata={"sku": "12345", "price": "99.99"},
523
    eager=[
524
        {"width": 300, "height": 300, "crop": "thumb"},
525
        {"width": 800, "height": 600, "crop": "fill"}
526
    ],
527
    eager_async=True
528
)
529

530
# Upload with AI features
531
result = uploader.upload(
532
    "image.jpg",
533
    faces=True,
534
    colors=True,
535
    image_metadata=True,
536
    auto_tagging=0.7,
537
    categorization="google_tagging",
538
    detection="adv_face",
539
    ocr="adv_ocr"
540
)
541
```
542

543
### Video Upload
544

545
```python
546
# Upload video file
547
result = uploader.upload(
548
    "video.mp4",
549
    resource_type="video",
550
    public_id="sample_video",
551
    eager=[
552
        {"width": 640, "height": 480, "crop": "pad", "format": "mp4"},
553
        {"width": 300, "height": 300, "crop": "thumb", "format": "jpg"}
554
    ]
555
)
556

557
# Upload large video with chunked upload
558
result = uploader.upload_large(
559
    "large_video.mov",
560
    resource_type="video",
561
    chunk_size=50 * 1024 * 1024,  # 50MB chunks
562
    eager_async=True
563
)
564
```
565

566
### Asset Management
567

568
```python
569
# Delete an asset
570
result = uploader.destroy("sample_image")
571
print(f"Deleted: {result['result']}")
572

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

576
# Generate additional transformations
577
result = uploader.explicit(
578
    "sample_image",
579
    type="upload",
580
    eager=[
581
        {"width": 400, "height": 300, "crop": "pad"},
582
        {"width": 200, "height": 200, "crop": "thumb", "radius": "max"}
583
    ]
584
)
585
```
586

587
### Batch Operations
588

589
```python
590
# Add tags to multiple assets
591
result = uploader.add_tag(
592
    "summer_sale",
593
    ["product_1", "product_2", "product_3"]
594
)
595

596
# Create ZIP archive
597
result = uploader.create_zip(
598
    tags=["product"],
599
    resource_type="image",
600
    flatten_folders=True
601
)
602
archive_url = result['url']
603

604
# Unsigned upload (requires upload preset)
605
result = uploader.unsigned_upload(
606
    "image.jpg",
607
    "my_upload_preset",
608
    tags=["unsigned"]
609
)
610
```
611

612
### Sprite and Multi-Image Examples
613

614
```python
615
# Generate sprite from tagged images
616
result = uploader.generate_sprite(
617
    tag="product_thumbnails",
618
    transformation={"width": 100, "height": 100, "crop": "fill"}
619
)
620
sprite_url = result['url']
621
css_url = result['css_url']
622

623
# Create animated GIF from images
624
result = uploader.multi(
625
    tag="slideshow_images",
626
    format="gif",
627
    delay=1000  # 1 second delay between frames
628
)
629

630
# Create PDF from multiple images
631
result = uploader.multi(
632
    urls=[
633
        "https://res.cloudinary.com/.../image1.jpg",
634
        "https://res.cloudinary.com/.../image2.jpg"
635
    ],
636
    format="pdf"
637
)
638
```
639

640
### Text Generation Examples
641

642
```python
643
# Generate simple text image
644
result = uploader.text(
645
    "Hello World",
646
    font_family="Arial",
647
    font_size=48,
648
    font_color="blue"
649
)
650

651
# Generate styled text with background
652
result = uploader.text(
653
    "SALE 50% OFF",
654
    font_family="Helvetica",
655
    font_size=72,
656
    font_weight="bold",
657
    font_color="white",
658
    background="red",
659
    text_align="center",
660
    public_id="sale_banner"
661
)
662
```
663

664
### Advanced Operations Examples
665

666
```python
667
# Create slideshow from tagged videos
668
result = uploader.create_slideshow(
669
    manifest_json={
670
        "w": 1280,
671
        "h": 720,
672
        "fps": 30,
673
        "vars": {
674
            "slides": [
675
                {"media": "i:slide1", "duration": 3000},
676
                {"media": "i:slide2", "duration": 3000}
677
            ]
678
        }
679
    },
680
    public_id="my_slideshow",
681
    overwrite=True
682
)
683

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

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

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

703
# Remove all tags from assets
704
result = uploader.remove_all_tags(
705
    ["old_asset_1", "old_asset_2"]
706
)
707
```