Python image and video upload

Cloudinary provides an API for uploading images, videos, and any other kind of file to the cloud. Files uploaded to Cloudinary are stored safely in the cloud with secure backups and revision history. Cloudinary's APIs allow secure uploading from your servers, directly from your visitors' browsers or mobile applications, or fetched via remote public URLs.

Cloudinary's Python SDK wraps Cloudinary's upload API and simplifies the integration. Python methods are available for easily performing Python image and video uploads to the cloud and Python view helper methods are available for uploading directly from a browser to Cloudinary.

This page covers common usage patterns for Python image and video upload with Cloudinary.

For details on all available upload options and parameters, see the Media upload documentation, and the upload method of the Upload API Reference.

Server-side upload

You can upload images, videos, or any other raw file to Cloudinary from your Python code. Uploading is done over HTTPS using a secure protocol based on your product environment's api_key and api_secret parameters.

Python image upload

The following method uploads an image to the cloud:

def upload(file, **options)

For example, uploading a local image file named 'my_image.jpg':

cloudinary.uploader.upload("my_image.jpg")

The file to upload can be specified as a local path, a remote HTTP or HTTPS URL, a whitelisted storage bucket (S3 or Google Storage) URL, a base64 data URI, or an FTP URL. For details, see File source options.

For details on all available upload options and parameters, see the Media upload documentation, and the upload method of the Upload API Reference.

Python video upload

You upload videos in exactly the same way as images. However, the upload method supports uploading files only up to 100 MB. To upload larger videos, use the upload_large method, which uploads large files to the cloud in chunks.

The upload_large method has the identical signature and options as the upload method, with the addition of an optional chunk_size parameter (default 20 MB).

The following example uploads dog.mp4 to Cloudinary and stores it in a bi-level folder structure with the public ID dog_closeup. It also performs two eager transformations that resize the video to a square and a small rectangle.

cloudinary.uploader.upload_large("dog.mp4", 
  resource_type = "video",
  public_id = "myfolder/mysubfolder/dog_closeup",
  chunk_size = 6000000,
  eager = [
    { "width": 300, "height": 300, "crop": "pad", "audio_codec": "none"},
    { "width": 160, "height": 100, "crop": "crop", "gravity": "south",
        "audio_codec": "none"}],
  eager_async = True,
  eager_notification_url = "https://mysite.example.com/notify_endpoint")

Upload response

By default, uploading is performed synchronously. Once finished, the uploaded image or video is immediately available for transformation and delivery. An upload call returns a Hash with content similar to the following:

{   
  u'bytes': 29802,
  u'created_at': u'2017-06-25T17:20:30Z',
  u'format': u'jpg',
  u'height': 282,
  u'public_id': u'hl22acprlomnycgiudor',
  u'resource_type': u'image',
  u'secure_url': u'https://res.cloudinary.com/demo/image/upload/v1571218039/hl22acprlomnycgiudor.jpg',
  u'signature': u'10594f028dbc23e920fd084f8482394798edbc68',
  u'type': u'upload',
  u'url': u'http://res.cloudinary.com/demo/image/upload/v1571218039/hl22acprlomnycgiudor.jpg',
  u'version': 1571218039,
  u'width': 292
}

The response includes HTTP and HTTPS URLs for accessing the uploaded media asset as well as additional information regarding the uploaded asset: public ID, resource type, width and height, file format, file size in bytes, a signature for verifying the response and more.

Data uploading options

Cloudinary's Python library supports uploading files from various sources.

• You can upload an image by specifying a local path of an image file. For example:

  Copy to clipboard

  cloudinary.uploader.upload('/home/my_image.jpg')

• You can provide an IO object that you created:

  Copy to clipboard

  cloudinary.uploader.upload(open('/tmp/image1.jpg', 'rb'))

• If your images are already publicly available online, you can specify their remote HTTP URLs instead of uploading the actual data. In this case, Cloudinary will fetch the image from its remote URL for you. This option allows for a much faster migration of your existing images. Here's an example:

  Copy to clipboard

  cloudinary.uploader.upload('https://www.example.com/image.jpg')

• If you have existing images in an Amazon S3 bucket, you can point Cloudinary to their S3 URLs. Note - this option requires a quick manual setup. Contact us and we'll guide you on how to allow Cloudinary access to your relevant S3 buckets.

  Copy to clipboard

  cloudinary.uploader.upload('s3://my-bucket/my-path/my-file.jpg')

  Note

  If you are coding an application in Django where users upload images through a web form, you can pass the parameter of your Django's request.FILES to the upload method:

  Copy to clipboard

  cloudinary.uploader.upload(request.FILES['file'])

Django forms and models

If you are using Django, you can integrate Cloudinary's uploading capabilities into your forms and models using Cloudinary's helper classes. As shown in the example below, you can define a model class Photo in your models.py file. This class has an image field of the CloudinaryField class.

from django.db import models
from cloudinary.models import CloudinaryField

class Photo(models.Model):
  image = CloudinaryField('image')

In the forms.py file we define a PhotoForm class that has a form field named image of the CloudinaryFileField class (by default).

from django.forms import ModelForm      
from .models import Photo

class PhotoForm(ModelForm):
  class Meta:
      model = Photo

The views.py file defines a view named upload which displays an HTML upload form and also handles posting of image files. Such images are uploaded to Cloudinary from your Django server by the CloudinaryFileField class.

from django import forms
from django.http import HttpResponse

from cloudinary.forms import cl_init_js_callbacks      
from .models import Photo
from .forms import PhotoForm

def upload(request):
  context = dict( backend_form = PhotoForm())

  if request.method == 'POST':
    form = PhotoForm(request.POST, request.FILES)
    context['posted'] = form.instance
    if form.is_valid():
        form.save()

  return render(request, 'upload.html', context)

The following HTML templates includes a form that uploads images to your server for uploading to Cloudinary:

{% load cloudinary %}
{% load url from future %}

{% block body %}
  <div id='backend_upload'>
    <form action="{% url "photo_album.views.upload" %}" method="post"
          enctype="multipart/form-data">
      {% csrf_token %}
      {{ backend_form }}
      <input type="submit" value="Upload">
    </form>
  </div>  
{% endblock %}

Having stored the image ID, you can now embed the image or a transformed version of it using the cloudinary template tag:

{% load cloudinary %}      
{% cloudinary photo.image format="jpg" width=120 height=80 crop="fill" %}

In addition, you can assign tags, apply transformation or specify any Cloudinary's upload options when initializing the CloudinaryFileField class.

from django.forms import ModelForm      
from cloudinary.forms import CloudinaryFileField      
from .models import Photo

class PhotoForm(ModelForm):
  class Meta:
    model = Photo
  image = CloudinaryFileField(
    attrs = { 'style': "margin-top: 30px" }, 
    options = { 
      'tags': "directly_uploaded",
      'crop': 'limit', 'width': 1000, 'height': 1000,
      'eager': [{ 'crop': 'fill', 'width': 150, 'height': 100 }]
    })

Direct uploading from the browser

The upload samples shown above allow your server-side Python code to upload media assets to Cloudinary. In this flow, if you have a web form that allows your users to upload images or videos, the media file's data is first sent to your server and then uploaded to Cloudinary.

A more efficient and powerful option is to allow your users to upload images and videos in your client-side code directly from the browser to Cloudinary instead of going through your servers. This method allows for faster uploading and a better user experience. It also reduces load from your servers and reduces the complexity of your Python applications.

You can upload files directly from the browser using signed or unsigned calls to the upload endpoint, as shown in the Upload multiple files using a form examples.

For signed uploads from your client-side code, a secure signature must be generated in your server-side Python code. You can use the api_sign_request method to generate SHA signatures:

cloudinary.utils.api_sign_request(params_to_sign, api_secret)

For the full list of parameters available for signed uploads, see the upload method in the Upload API Reference.