API Endpoints

The API Endpoints for OpenShot Cloud API are discoverable and browsable on your local instance. The best way to learn and play with them is with your browser, and access the interface: http://YourInstanceIP/.

_static/root-ui.png

Authentication

Each request must be authenticated before it will be processed. OpenShot Cloud API supports multiple user accounts, each with their own credentials. You can create multiple user accounts, and data created in one account, can only be accessed by that same user account. Each user has a username, password, and token.

OpenShot Cloud API supports 3 different types of authentication.

Basic Authentication

A username and password are sent via clear text. This is fine if you are not exposing your private cloud to external clients (such as mobile or desktop apps), otherwise always use HTTPS. You can create a new user with the /cloud-admin/auth/user/ URL.

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

# Python Example
r = requests.get(CLOUD_URL + end_point, auth=HTTPBasicAuth('demo-cloud', 'demo-password'))

Session Authentication

Once authenticated, a sessionid is returned. This sessionid must be included on every request until it expires. This method is used with our discoverable html interface.

Token Authentication

A token is automatically created for each user account. That token can be sent in a header instead of username and password. For clients to authenticate, the token key should be included in the Authorization HTTP header. The key should be prefixed by the string literal “Token”, with whitespace separating the two strings. This is fine if you are not exposing your private cloud to external clients (such as mobile or desktop apps), otherwise always use HTTPS. You can locate a user’s token using the /cloud-admin/authtoken/token/ URL.

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

# Python Example
headers = {'Authorization': 'Token 9054f7aa9305e012b3c2300408c3dfdf390fcddf'}
r = requests.get(url, headers=headers)

Security

By default, OpenShot Cloud API requests and responses are unsecured and use port 80. If you do not need external access to the API, please close port 80 and ensure the server is only internally accessible. However, if you do need external access to the API, HTTPS is a must to protect your credentials when making requests. There are 2 basic approaches for enabling SSL for OpenShot Cloud API.

SSL (EC2 Load Balancer)

This is the recommended approach for enabling SSL for OpenShot Cloud API. Launch an EC2 Load Balancer, configure it with your SSL certificate, and connect the load balancer to your OpenShot Cloud API server instance. Use the load balancer’s DNS with HTTPS for making requests, thus keeping the OpenShot Cloud API instance internal, private, and safe. This also requires no changes to the OpenShot Cloud API instance.

SSL (Configure Apache)

This approach requires OpenShot Cloud API servers be manually configured with SSL (Apache web server). Edit the following file, and point to your specific SSL certificate files (which will need to be uploaded, put in a folder, and secured with file permissions):

nano /etc/apache2/sites-available/openshot-ssl.conf

SSLCertificateFile    /etc/ssl/certs/SITENAME.crt
SSLCACertificateFile  /etc/ssl/certs/SITENAME.ca-bundle
SSLCertificateKeyFile /etc/ssl/private/SITENAME.key

Once configured, restart Apache and other API services:

$ sudo supervisorctl restart all
$ sudo service apache2 restart

Now that Apache is manually configured with SSL, be sure to make all requests using HTTPS, to protect your credentials.

Methods

REST is a design pattern for web services modeled around HTTP requests. Each operation uses its own HTTP method:

Method Description
GET Get data from the API (i.e. request a project, clip, or export)
POST Create data on the API (i.e. create a project, clip, or export)
PUT Update existing data from the API (i.e. update a project, clip, or export)
PATCH Update partial existing data from the API (i.e. update only a Clip’s position)
DELETE Delete existing data from the API (i.e. delete a project, clip, or export)

Responses

OpenShot Cloud API uses HTTP status codes to indicate the following things:

Status Code Name
200 Successful request, good job!
400 Bad request, something is wrong with your request
403 Forbidden, permission denied
500 Server error, something broke while processing the request

Informational responses, such as success and failure messages use the following JSON payload syntax, and include a “detail” attribute.

Response Data
 {
    "detail": "Important success or failure message"
 }

Other responses return actual JSON data structures, with no “detail” attribute.

Response Data
 [
     {
         "url": "http://127.0.0.1:8008/projects/21/",
         "id": 21,
         "name": "Example Project",
         "width": 1920,
         "height": 1080,
         "fps_num": 30,
         "fps_den": 1,
         "sample_rate": 44100,
         "channels": 2,
         "channel_layout": 3,
         "video_format": "mp4",
         "video_codec": "libx264",
         "video_bitrate": 8000000,
         "audio_codec": "ac3",
         "audio_bitrate": 1920000,
         "files": [],
         "clips": [],
         "effects": [],
         "json": {}
     }
 ]

Endpoints

Here are the primary API Endpoints for OpenShot Cloud API and a short description of what they do. For more details on parameters and implementation specific details, visit your local instance: http://YourInstanceIP/.

/projects/

API endpoint that manages projects. A project is the top level object that represents a video editing project. All files, clips, effects, and edits will refer back to a project. For convenience, a project file from OpenShot Video Editor can also be loaded as the initial template.

Response Data
{
    "url": "http://cloud.openshot.org/projects/65/",
    "id": 65,
    "name": "Example Project",
    "width": 1920,
    "height": 1080,
    "fps_num": 30,
    "fps_den": 1,
    "sample_rate": 44100,
    "channels": 2,
    "channel_layout": 3,
    "files": [],
    "clips": [],
    "effects": [],
    "exports": [],
    "actions": [
        "http://cloud.openshot.org/projects/65/load/",
        "http://cloud.openshot.org/projects/65/files/",
        "http://cloud.openshot.org/projects/65/files/find/",
        "http://cloud.openshot.org/projects/65/clips/",
        "http://cloud.openshot.org/projects/65/effects/",
        "http://cloud.openshot.org/projects/65/exports/",
        "http://cloud.openshot.org/projects/65/thumbnail/",
        "http://cloud.openshot.org/projects/65/title/",
        "http://cloud.openshot.org/projects/65/validate/",
        "http://cloud.openshot.org/projects/65/json/"
    ],
    "json": {},
    "date_created": "2017-11-07T04:14:46.896016Z",
    "date_updated": "2017-11-07T04:14:46.896048Z"
}

/projects/<id>/

API endpoint to manage a specific project.

Request Paramaters:

Name Description
name (string) The name of your video project
width (int) The width of your video output
height (int) The height of your video output
fps_num (int) Frames per second (numerator)
fps_den (int) Frames per second (denominator)
sample_rate (int) Audio samples per second
channels (int) Audio channels (2 = stereo)
channel_layout (int) Channel layout type (3=stereo, 4=mono, 7=Surround)
json (string) Optional JSON (escaped as a string)
Request Data
{
    "name": "Example Project",
    "width": 1920,
    "height": 1080,
    "fps_num": 30,
    "fps_den": 1,
    "sample_rate": 44100,
    "channels": 2,
    "channel_layout": 3,
    "json": "{}",
}

/projects/<id>/clips/

API endpoint to list and manage clips for a specific project.

/projects/<id>/copy/

API endpoint that copies/duplicates a project, including all File and Clip objects and all local file assets. A duplicated project can be deleted or changed without affecting the original project. This is especially useful for using another project as a template, including all it’s assets.

Request Data
{
    "name": "New Project Name"
}

/projects/<id>/download/

API endpoint that returns a Zip archive of an entire project JSON and associated assets (returns binary zip file). This is useful for downloading an entire project for offline testing with OpenShot Video Editor (desktop editor). Only GET method is supported on this endpoint.

See /projects/<id>/load/ for uploading a ZIP archive of an entire cloud project.

/projects/<id>/effects/

API endpoint to list and manage effects for a specific project.

/projects/<id>/exports/

API endpoint that exports your video project for rendering. Rendering converts your project into a final video file, which can then be accessed, downloaded, or deleted. See Export / Render.

/projects/<id>/files/

API endpoint to list and manage files for a specific project.

/projects/<id>/files/find/

API endpoint to return a list of matching File objects for a specific time range with an optional filename filter. Useful if you need to get just the files in a section of the timeline, or a file object with a specific name.

Request Data
{
    "position_in_seconds": 0.0,
    "length_in_seconds": 10.0,
    "filename_contains": ""
}
Response Data
[
    {
        "media": "http://cloud.openshot.org/media/video/files/48/file1.JPG",
        "download": "http://cloud.openshot.org/files/165/download/"
        "url": "http://cloud.openshot.org/files/165/"
    },
    {
        "media": "http://cloud.openshot.org/media/video/files/48/file2.mp4",
        "download": "http://cloud.openshot.org/files/166/download/"
        "url": "http://cloud.openshot.org/files/166/"
    },
    {
        "media": "http://cloud.openshot.org/media/video/files/48/file3.mp4",
        "download": "http://cloud.openshot.org/files/167/download/"
        "url": "http://cloud.openshot.org/files/167/"
    }
]

/projects/<id>/json/

API endpoint that outputs your OpenShot Cloud API project as an OpenShot Video Editor project file (JSON format). This is especially useful for testing and debugging your cloud project files. OpenShot Video Editor is our award-winning open-source video editor, and is compatible with Linux, Mac, and Windows.

/projects/<id>/load/

API endpoint that loads/initializes a project using an OpenShot Video Editor project file (JSON format). NOTE: This will remove all existing files, clips, and effects, and re-initialize the project to exactly match the project data you are loading. OpenShot Video Editor is our award-winning open-source desktop video editor, and is compatible with Linux, Mac, and Windows.

You can optionally upload a ZIP archive containing all media files used by a project, which is usually much faster than uploading each File object separately. The ZIP should contain all files used in the project (MP4, PNG, SVG, etc…), and also the OpenShot Project file (*.osp or *.json).

Also, you can combine these 2 approaches, and upload the project data JSON using the “json” field, and also attach a ZIP archive with all media files used by that project.

See /projects/<id>/download/ for downloading a ZIP archive of an entire cloud project.

Request Data (for loading JSON project data)
{
    "json": "{...}",
}
Request Data (for loading an entire project from a ZIP archive)
{
    "archive": null
}
Request Data (for loading JSON project data and ZIP archive of all media assets)
{
    "json": "{ ...  Project JSON ...}",
    "archive": null
}

/projects/<id>/thumbnail/

API endpoint to return a thumbnail image of a specific project frame (returns binary image). Image formats supported: BMP, JPG, JPEG, PNG, PPM, XBM, XPM.

Request Data
{
    "frame_number": 1,
    "width": 1920,
    "height": 1080,
    "image_format": "JPG",
    "image_quality": 100
}

/projects/<id>/title/

API endpoint to create new SVG title File objects. It is a quick way to generate dynamic SVG titles, and automatically add them to your project’s File list. Templates are loaded from the /api/api_app/static/titles/ folder. See Titles / Text.

Request Data
{
    "template": "Center-Text.svg",
    "text": "Text of title",
    "font_size": 100.0,
    "font_name": "Bitstream Vera Sans",
    "fill_color": "#ffcc00",
    "fill_opacity": 1.0,
    "stroke_color": "#000000",
    "stroke_size": 3.0,
    "stroke_opacity": 1.0,
    "drop_shadow": true,
    "background_color": "#000000",
    "background_opacity": 0.0
}

/projects/<id>/validate/

API endpoint that validates your current video project. It checks for missing file resources, missing properties, missing clips, and many other critical data points. Only valid projects can be rendered.

/files/

API endpoint that manages file objects. These can be images, videos, or audio files. File objects belong to both a project and a clip object. All assets used in your video must be added as file objects before they can be added as clips. Also, multiple clips can refer to a single file object.

File objects are rich with metadata, and include all kinds of interesting attributes about the file (and its content). Also, you will notice many technical attributes and embedded metadata (camera info, artist/album info, device rotation, etc…).

Request Data - Uploading binary file
{
    "media": null,
    "project": "http://127.0.0.1:8001/projects/36/",
    "json": {}
}
Request Data - Optional URL (to be downloaded by the server)
{
    "media": null,
    "project": "http://127.0.0.1:8001/projects/36/",
    "json": { "url": "http://example/file/path.jpg", "name": "Custom-Filename.mp4" }
}
Request Data - Optional S3 PATH (to be downloaded from Amazon S3). S3 must be configured first in api/api/settings.py, and requires credentials.
{
    "media": null,
    "project": "http://127.0.0.1:8001/projects/36/",
    "json": { "url": "my/S3/path/FILE.MP4", "bucket": "MyS3Bucket", "name": "Custom-Filename.mp4"  }
}
Request Data - Optional Azure Blob Storage PATH (to be downloaded from Azure). Azure must be configured first in api/api/settings.py, and requires credentials.
{
    "media": null,
    "project": "http://127.0.0.1:8001/projects/36/",
    "json": { "url": "my/path/FILE.MP4", "container": "MyContainerName", "name": "Custom-Filename.mp4"  }
}
Request Data - Optional File PATH (to be located on the server)
{
    "media": null,
    "project": "http://127.0.0.1:8001/projects/36/",
    "json": { "url": "video/files/36/LOCAL-FILE.MP4", "name": "Custom-Filename.mp4"  }
}
Response Data for a video file
{
  "url": "http://cloud.openshot.org/files/721/",
  "id": 721,
  "media": "http://cloud.openshot.org/media/video/files/292/sintel_trailer-720p.mp4",
  "project": "http://cloud.openshot.org/projects/292/",
  "actions": [
      "http://cloud.openshot.org/files/721/thumbnail/"
  ],
  "json": {
      "channel_layout": 3,
      "has_video": true,
      "pixel_ratio": {
          "num": 1,
          "den": 1
      },
      "height": 720,
      "audio_stream_index": 1,
      "vcodec": "h264",
      "top_field_first": true,
      "video_stream_index": 0,
      "file_size": "7610368",
      "media_type": "video",
      "interlaced_frame": false,
      "has_audio": true,
      "path": "/home/ubuntu/api/video/files/292/sintel_trailer-720p.mp4",
      "fps": {
          "num": 24,
          "den": 1
      },
      "duration": 51.9466667175293,
      "audio_bit_rate": 126694,
      "acodec": "aac",
      "type": "FFmpegReader",
      "video_timebase": {
          "num": 1,
          "den": 24
      },
      "sample_rate": 48000,
      "width": 1280,
      "audio_timebase": {
          "num": 1,
          "den": 48000
      },
      "video_bit_rate": 1166138,
      "has_single_image": false,
      "display_ratio": {
          "num": 16,
          "den": 9
      },
      "metadata": {
          "major_brand": "isom",
          "artist": "Durian Open Movie Team",
          "encoder": "Lavf52.62.0",
          "copyright": "(c) copyright Blender Foundation | durian.blender.org",
          "creation_time": "1970-01-01 00:00:00",
          "minor_version": "512",
          "language": "und",
          "handler_name": "SoundHandler",
          "compatible_brands": "isomiso2avc1mp41",
          "title": "Sintel Trailer",
          "description": "Trailer for the Sintel open movie project"
      },
      "video_length": "1253",
      "pixel_format": 0,
      "channels": 2
  },
  "date_created": "2018-02-25T22:03:22.323107Z",
  "date_updated": "2018-02-25T22:03:22.589635Z"
}
Response Data for an audio file (with metadata)
{
  "url": "http://cloud.openshot.org/files/719/",
  "id": 719,
  "media": "http://cloud.openshot.org/media/video/files/292/01_-_Universal_Fanfare_From__Pitch_Perfect_2__Soundtrack.mp3",
  "project": "http://cloud.openshot.org/projects/292/",
  "actions": [
      "http://cloud.openshot.org/files/292/copy/",
      "http://cloud.openshot.org/files/292/download/",
      "http://cloud.openshot.org/files/292/text-replace/",
      "http://cloud.openshot.org/files/292/thumbnail/"
  ],
  "json": {
      "interlaced_frame": false,
      "height": 600,
      "metadata": {
          "album": "Pitch Perfect 2 (Original Motion Picture Soundtrack)",
          "date": "2015",
          "track": "1/18",
          "artist": "Elizabeth Banks and John Michael Higgins",
          "copyright": "(C) 2015 Universal Music Enterprises, a Division of UMG Recordings, Inc.",
          "title": "Universal Fanfare (From \"Pitch Perfect 2\" Soundtrack)",
          "comment": "Cover (front)",
          "composer": "Jerry Goldsmith",
          "genre": "Soundtracks",
          "album_artist": "Various artists",
          "disc": "1/1"
      },
      "width": 600,
      "video_length": "793",
      "duration": 33.044898986816406,
      "pixel_format": 12,
      "acodec": "mp3",
      "video_bit_rate": 269082,
      "path": "/home/ubuntu/api/video/files/292/01_-_Universal_Fanfare_From__Pitch_Perfect_2__Soundtrack.mp3",
      "media_type": "video",
      "audio_stream_index": 0,
      "sample_rate": 44100,
      "has_single_image": false,
      "video_stream_index": 1,
      "top_field_first": true,
      "display_ratio": {
          "den": 1,
          "num": 1
      },
      "video_timebase": {
          "den": 24,
          "num": 1
      },
      "channels": 2,
      "vcodec": "mjpeg",
      "has_video": true,
      "has_audio": true,
      "fps": {
          "den": 1,
          "num": 24
      },
      "type": "FFmpegReader",
      "audio_timebase": {
          "den": 14112000,
          "num": 1
      },
      "pixel_ratio": {
          "den": 1,
          "num": 1
      },
      "file_size": "1111476",
      "channel_layout": 3,
      "audio_bit_rate": 250729
  },
  "date_created": "2018-02-25T21:58:11.920072Z",
  "date_updated": "2018-02-25T21:58:12.190887Z"
}

/files/<id>/

API endpoint to manage a specific file.

Request Paramaters:

Name Description
media (file) Source media file (video, image, or audio)
project (int) Video project url
json (string) Optional JSON object (advanced properties and attributes, escaped as a string)
Request Data
file_data = {
    "media": null,
    "project": "http://cloud.openshot.org/projects/292/",
    "json": "{}"
}
post(CLOUD_URL + end_point, data=file_data, files={"media": (source_name, open(source_path, "rb"))})

/files/<id>/copy/

API endpoint that copies/duplicates a file, including the local file asset. A duplicated file can be deleted or changed without affecting the original file. This is useful for duplicating SVG title files, and other text-based assets.

Request Paramaters:

Name Description
name (string) Name of copied file
project (string) Optional project URL or project ID number. This can be used to copy a File into another project.
Request Data
{
    "name": "NewFileName.mp4",
    "project": "123"
}

/files/<id>/download/

API endpoint that downloads a file with authentication. If you need secure access to your File media, this endpoint can be used to download the file securely, however the media folder is still exposed in Apache and will need to be disabled manually (for fully secure media).

To disable the Apache media path, edit /etc/apache2/sites-available/openshot.conf and remove the Alias /media /home/ubuntu/api/ line.

When you GET the file from this endpoint, it will return the correct content_type of the file and the actual file bytes. No JSON is returned. Using this endpoint is slower than directly accessing the media file with Apache. So you are trading security for speed.

/files/<id>/text-replace/

API endpoint for replacing text in text-based files, such as replacing words and phrases in an SVG file. This is especially useful for editing text in a template SVG file. See /files/<id>/copy/ endpoint for making a copy of an SVG file before replacing the text.

Request Data
{
    "search": "Find Me",
    "replace": "Replacement"
}

/files/<id>/thumbnail/

API endpoint to return a thumbnail image of a specific file frame (returns binary image). Image formats supported: BMP, JPG, JPEG, PNG, PPM, XBM, XPM.

Request Data
{
    "frame_number": 1,
    "width": 1920,
    "height": 1080,
    "image_format": "JPG",
    "image_quality": 100
}

/clips/

API endpoint that manages clips. A clip is a container for a file object, located on a specific layer, and at a specific position (in seconds) on the timeline. Clips can also manipulate their source file, by adjusting transparency, location, rotation, shearing, and scale. Most properties on a clip can also be animated, by adjusting the values over time, and choosing an interpolation type (linear, bezier, or constant). See Animation for more info on keyframes and animating.

Common Properties Description
alpha Alpha transparency (0=visible to 1=invisible)
scale_x Width as a percentage (0 to 1)
scale_y Height as a percentage (0 to 1)
location_x Left edge as a percentage (0 to 1)
location_y Top edge as a percentage (0 to 1)
rotation Rotation as degrees (0 to 360)
volume Volume as a percentage (0 to 1)
scale Scale mode (0=Crop, 1=Fit, 2=Stretch, 3=None)
gravity Alignment (0=Top Left, 1=Top, 2=Top Right, 3=Left, 4=Center, 5=Right, 6=Bottom Left, 7=Bottom, 8=Bottom Right)
has_audio Include audio stream (0 or 1)
has_video Include video stream (0 or 1)
time Curve representing frames (fast, slow, forward, backwards controls)
Response Data
{
    "url": "http://cloud.openshot.org/clips/87/",
    "file": "http://cloud.openshot.org/files/91/",
    "id": 87,
    "position": 0.0,
    "start": 0.0,
    "end": 10.0,
    "layer": 1,
    "actions": [
        "http://cloud.openshot.org/clips/87/presets/",
        "http://cloud.openshot.org/clips/87/keyframes/",
        "http://cloud.openshot.org/clips/87/reset/"
    ],
    "project": "http://cloud.openshot.org/projects/65/",
    "json": {
        "anchor": 0,
        "channel_filter": {
            "Points": [
                {
                    "co": {
                        "Y": -1,
                        "X": 1
                    },
                    "interpolation": 2
                }
            ]
        },
        "waveform": false,
        "scale_x": {
            "Points": [
                {
                    "co": {
                        "Y": 1,
                        "X": 1
                    },
                    "interpolation": 2
                }
            ]
        },
        "has_video": {
            "Points": [
                {
                    "co": {
                        "Y": -1,
                        "X": 1
                    },
                    "interpolation": 2
                }
            ]
        },
        "has_audio": {
            "Points": [
                {
                    "co": {
                        "Y": -1,
                        "X": 1
                    },
                    "interpolation": 2
                }
            ]
        },
        "location_y": {
            "Points": [
                {
                    "co": {
                        "Y": 0,
                        "X": 1
                    },
                    "interpolation": 2
                }
            ]
        },
        "alpha": {
            "Points": [
                {
                    "co": {
                        "Y": 1,
                        "X": 1
                    },
                    "interpolation": 2
                }
            ]
        },
        "image": "thumbnail/91.png",
        "shear_x": {
            "Points": [
                {
                    "co": {
                        "Y": 0,
                        "X": 1
                    },
                    "interpolation": 2
                }
            ]
        },
        "shear_y": {
            "Points": [
                {
                    "co": {
                        "Y": 0,
                        "X": 1
                    },
                    "interpolation": 2
                }
            ]
        },
        "rotation": {
            "Points": [
                {
                    "co": {
                        "Y": 0,
                        "X": 1
                    },
                    "interpolation": 2
                }
            ]
        },
        "reader": {
            "has_audio": true,
            "height": 720,
            "sample_rate": 48000,
            "pixel_format": 0,
            "interlaced_frame": false,
            "video_length": "1253",
            "has_single_image": false,
            "media_type": "video",
            "path": "/home/ubuntu/api/video/files/65/sintel_trailer-720p.mp4",
            "channels": 2,
            "top_field_first": true,
            "audio_bit_rate": 126694,
            "width": 1280,
            "display_ratio": {
                "num": 16,
                "den": 9
            },
            "file_size": "7610368",
            "duration": 51.9466667175293,
            "video_timebase": {
                "num": 1,
                "den": 24
            },
            "vcodec": "h264",
            "audio_timebase": {
                "num": 1,
                "den": 48000
            },
            "pixel_ratio": {
                "num": 1,
                "den": 1
            },
            "channel_layout": 3,
            "has_video": true,
            "video_bit_rate": 1166138,
            "video_stream_index": 0,
            "type": "FFmpegReader",
            "fps": {
                "num": 24,
                "den": 1
            },
            "audio_stream_index": 1,
            "acodec": "aac"
        },
        "scale": 1,
        "channel_mapping": {
            "Points": [
                {
                    "co": {
                        "Y": -1,
                        "X": 1
                    },
                    "interpolation": 2
                }
            ]
        },
        "gravity": 4,
        "scale_y": {
            "Points": [
                {
                    "co": {
                        "Y": 1,
                        "X": 1
                    },
                    "interpolation": 2
                }
            ]
        },
        "volume": {
            "Points": [
                {
                    "co": {
                        "Y": 1,
                        "X": 1
                    },
                    "interpolation": 2
                }
            ]
        },
        "title": "sintel_trailer-720p.mp4",
        "wave_color": {
            "blue": {
                "Points": [
                    {
                        "handle_type": 0,
                        "handle_right": {
                            "Y": 0,
                            "X": 0.5
                        },
                        "handle_left": {
                            "Y": 1,
                            "X": 0.5
                        },
                        "co": {
                            "Y": 255,
                            "X": 1
                        },
                        "interpolation": 0
                    }
                ]
            },
            "alpha": {
                "Points": [
                    {
                        "handle_type": 0,
                        "handle_right": {
                            "Y": 0,
                            "X": 0.5
                        },
                        "handle_left": {
                            "Y": 1,
                            "X": 0.5
                        },
                        "co": {
                            "Y": 255,
                            "X": 1
                        },
                        "interpolation": 0
                    }
                ]
            },
            "green": {
                "Points": [
                    {
                        "handle_type": 0,
                        "handle_right": {
                            "Y": 0,
                            "X": 0.5
                        },
                        "handle_left": {
                            "Y": 1,
                            "X": 0.5
                        },
                        "co": {
                            "Y": 123,
                            "X": 1
                        },
                        "interpolation": 0
                    }
                ]
            },
            "red": {
                "Points": [
                    {
                        "handle_type": 0,
                        "handle_right": {
                            "Y": 0,
                            "X": 0.5
                        },
                        "handle_left": {
                            "Y": 1,
                            "X": 0.5
                        },
                        "co": {
                            "Y": 0,
                            "X": 1
                        },
                        "interpolation": 0
                    }
                ]
            }
        },
        "display": 0,
        "time": {
            "Points": [
                {
                    "co": {
                        "Y": 1,
                        "X": 1
                    },
                    "interpolation": 2
                }
            ]
        },
        "location_x": {
            "Points": [
                {
                    "co": {
                        "Y": 0,
                        "X": 1
                    },
                    "interpolation": 2
                }
            ]
        }
    },
    "date_created": "2017-11-07T04:24:25.632357Z",
    "date_updated": "2017-11-07T04:24:25.635518Z"
}

/clips/<id>/

API endpoint to manage a specific clip.

Request Paramaters:

Name Description
position (float) Position (in seconds)
start (float) Start of clip (in seconds)
end (float) End of clip (in seconds)
layer (int) Layer / Track number (lower tracks are hidden by higher tracks)
file (string) Source media file url
project (string) Video project url
json (string) Optional JSON object (advanced properties and attributes, escaped as a string)
Request Data
{
    "file": "http://cloud.openshot.org/files/421/",
    "position": 0.0,
    "start": 0.0,
    "end": 10.0,
    "layer": 1,
    "project": "http://cloud.openshot.org/projects/147/",
    "json": "{}"
}

/clips/<id>/keyframes/

API endpoint to create custom keyframes for any clip property which supports keyframes and animation. See Animation.

Request Data
{
    "property": "alpha",
    "position_in_seconds": 3.0,
    "curve": "Linear",
    "value": "1.0",
}

/clips/<id>/presets/

API endpoint to apply a variety of common keyframe presets to a clip, including fading in/out, scaling in/out, rotation, etc… See Animation.

Request Data
{
    "preset": "Fade In",
    "length_in_seconds": 3.0,
    "curve": "Ease (Default)"
}

/clips/<id>/reset/

API endpoint to reset keyframes for common clip properties (such as alpha, scale, location, and rotation). See Animation.

/effects/

API endpoint that manages effects. An effect manipulates the image or audio of a frame, and is located on a specific layer, and at a specific position (in seconds) on the timeline. Most properties on an effect can also be animated, by adjusting the values over time, and choosing an interpolation type (linear, bezier, or constant). For details on all available effects, see /info/effects/.

Response Data
{
    "url": "http://cloud.openshot.org/effects/16/",
    "id": 16,
    "title": "Transition",
    "type": "Mask",
    "position": 0.0,
    "start": 0.0,
    "end": 10.0,
    "layer": 1,
    "project": "http://cloud.openshot.org/projects/78/",
    "json": {
        "name": "Alpha Mask / Wipe Transition",
        "brightness": {
            "Points": []
        },
        "contrast": {
            "Points": []
        },
        "short_name": "Mask",
        "description": "Uses a grayscale mask image to gradually wipe / transition between 2 images.",
        "reader": {},
        "class_name": "Mask",
        "replace_image": false,
        "has_audio": false,
        "has_video": true,
        "order": 0
    },
    "date_created": "2017-11-07T04:26:48.353239Z",
    "date_updated": "2017-11-07T04:26:48.379193Z"
}

/effects/<id>/

API endpoint to manage a specific effect.

Request Paramaters:

Name Description
position (float) Position (in seconds)
start (float) Start of effect (in seconds)
end (float) End of effect (in seconds)
layer (int) Layer / Track number (lower tracks are hidden by higher tracks)
title (string) Name of effect
type (string) Type of effect
project (string) Video project url
json (string) Optional JSON object (advanced properties and attributes, escaped as a string)
Request Data
{
    "title": "Negative Effect",
    "type": "Negate",
    "position": 0.0,
    "start": 0.0,
    "end": 10.0,
    "layer": 1,
    "project": "http://cloud.openshot.org/projects/147/",
    "json": "{}"
}

/exports/

API endpoint that manages video rendering exports. An export is a final rendered output of a video project, which converts all clips, transitions, and effects into a final output file (or files). An Export can be a video, audio, image, image sequence, or waveform. See Export / Render. See Frame Numbers for more information on calculating frame numbers (i.e. start_frame, end_frame).

Response Data
{
    "url": "http://cloud.openshot.org/exports/1/",
    "id": 1,
    "output": "http://cloud.openshot.org/media/video/output/1/output-1-1-2a40f424.mp4",
    "export_type": "video",
    "video_format": "mp4",
    "video_codec": "libx264",
    "video_bitrate": 8000000,
    "audio_codec": "ac3",
    "audio_bitrate": 1920000,
    "start_frame": 1,
    "end_frame": 301,
    "actions": [
        "http://cloud.openshot.org/exports/1/retry/"
    ],
    "project": "http://cloud.openshot.org/projects/1/",
    "webhook": "http://myserver.com/video-export/",
    "json": { },
    "progress": 100.0,
    "status": "completed",
    "date_created": "2017-11-07T07:21:33.397002Z",
    "date_updated": "2017-11-07T07:40:26.458371Z"
}

By default an export uses the parent project settings for width, height, FPS (frames per second), sample_rate, channels, and channel_layout. But all these attributes can be overwritten on any Export, by using the json attribute, for example:

Override project settings
"json": {"height": 640, "width": 480, "fps": {"num": 30, "den": 1}}

Exports also support a webhook, which is an optional, custom URL that is requested once an export has succeeded or failed. The Export data is sent as a POST, including a "json": { "status": "success", "webhook": "200: Your webhook response data"}

Webhook Request
{
  "export_type": "video",
  "video_format": "mp4",
  "video_codec": "libx264",
  "video_bitrate": 8000000,
  "audio_codec": "ac3",
  "audio_bitrate": 1920000,
  "start_frame": 1,
  "end_frame": 301,
  "project": "http://cloud.openshot.org/projects/1/",
  "webhook": "http://myserver.com/video-export/",
  "json": {
    "status": "success",
    "webhook": "200: Your webhook response data",
    "detail": "Optional error message if something broke"
  }
}

Exports can automatically upload your completed output file to Amazon S3 (which must be configured with config-openshot-cloud command first or manually in api/api/settings.py, and requires credentials). The Export data is sent as a POST, including the following "json": { "url": "my/S3/path/FILE.MP4", "bucket": "MyS3Bucket", "acl": "public-read" }.

S3 Export Request
{
  "export_type": "video",
  "video_format": "mp4",
  "video_codec": "libx264",
  "video_bitrate": 8000000,
  "audio_codec": "ac3",
  "audio_bitrate": 1920000,
  "start_frame": 1,
  "end_frame": 301,
  "project": "http://cloud.openshot.org/projects/1/",
  "webhook": "",
  "json": {
    "bucket": "MyS3Bucket",
    "url": "my/S3/path/FILE.MP4",
    "acl": "public-read"
  }
}

Exports can also automatically upload your completed output file to Azure Blob Storage (which must be configured with config-openshot-cloud command first or manually in api/api/settings.py, and requires credentials). The Export data is sent as a POST, including the following "json": { "url": "my/path/FILE.MP4", "container": "MyBlobContainer", "public": "blob" }.

Azure Blob Storage Export Request
{
  "export_type": "video",
  "video_format": "mp4",
  "video_codec": "libx264",
  "video_bitrate": 8000000,
  "audio_codec": "ac3",
  "audio_bitrate": 1920000,
  "start_frame": 1,
  "end_frame": 301,
  "project": "http://cloud.openshot.org/projects/1/",
  "webhook": "",
  "json": {
    "container": "MyBlobContainer",
    "url": "my/path/FILE.MP4",
    "public": "blob"
  }
}

/exports/<id>/

API endpoint to manage a specific export.

Request Paramaters:

Name Description
output (string) Final rendered video file url
export_type (string) Export type (video, audio, image, waveform)
video_format (string) Video format (mp4, avi, %05d.png, jpg, etc…)
video_codec (string) Video codec (h.264, mp4video, etc…)
video_bitrate (int) Video bitrate in bytes (i.e. 8000000 = 7.6/MB sec)
audio_codec (string) Audio codec (libmp3lame, ac3, libfdk_aac, etc…)
audio_bitrate (int) Audio bitrate in bytes (i.e. 1920000 = 192/KB sec)
start_frame (int) Starting frame of final video render
end_frame (int) Ending frame of final video render (blank = auto detect length)
webhook (string) Optional URL to be HTTP POST requested upon success or failure (export data POSTed to this url)
json (string) Optional JSON object (width, height, fps[num/den], sample_rate, channels, channel_layout, wave_color, wave_background_color, escaped as a string)
Request Data
{
    "video_format": "mp4",
    "video_codec": "libx264",
    "video_bitrate": 8000000,
    "audio_codec": "ac3",
    "audio_bitrate": 1920000,
    "start_frame": 1,
    "end_frame": -1,
    "project": "http://cloud.openshot.org/projects/147/",
    "json": "{}"
}

/exports/<id>/download/

API endpoint that downloads the Export output file with authentication. If you need secure access to your Export output, this endpoint can be used to download the file securely, however the media folder is still exposed in Apache and will need to be disabled manually (for fully secure media).

To disable the Apache media path, edit /etc/apache2/sites-available/openshot.conf and remove the Alias /media /home/ubuntu/api/ line.

When you GET the file from this endpoint, it will return the correct content_type of the file and the actual file bytes. No JSON is returned. Using this endpoint is slower than directly accessing the media file with Apache. So you are trading security for speed.

/exports/<id>/retry/

API endpoint to retry a failed export. Sometimes exports can fail while be processed on a worker. This endpoint simply re-queues the export for processing again.

/info/

API endpoint that lists information in JSON format, such as installed fonts and lists of effects and effect properties.

/info/fonts/

API endpoint to GET all available/installed font families and styles.

If you POST to this endpoint, it will clear the font cache and reload font data. You can also POST a font_file, which will add a new font to the system, and update the font cache.

Request Data
{
    "font_file": null
}

/info/fonts/thumbnail/

API endpoint to get a large JPEG thumbnail of all available fonts (useful for debugging font issues)

/info/effects/

API endpoint to list all effects and effect attributes/settings.