NAV
sh php JS python

Introduction

Publitio offers advanced APIs for Media (Video, Image, Audio and Document) Management in the cloud.

You can use our API endpoints to get information on various files, versions, players, adtags, and watermarks created and/or stored with us.

Here you will find documentation and reference to our REST and URL-based APIs.

You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Getting started

  1. Create an account
  2. Get API and Secret Keys at your Dashboard
  3. Choose SDK or Framework for integration
  4. Start testing

Authentication

The Publitio API supports two authentication methods:

Both your API Key and Secret, as well as personal access tokens, can be managed at the Dashboard.

API Keys Authentication

In order to authenticate an API call the following parameters are required:

Parameter Description
api_key API Key identifies the user to the API. It can be found in the Publitio Dashboard.
api_timestamp API timestamp is the current UNIX timestamp (32-bit signed integer). It is used to protect against replay-attacks.
api_nonce API nonce is an 8-digit random number. It is used to make sure that the API signature is always unique, even if the same call has been made twice within one second.
api_signature SHA-1 digest of the api_nonce, api_timestamp and api_secret.

API signature generation

The API signature is a SHA-1 digest and is generated similar to the OAuth Core 1.0 specification.

  1. Parameters (api_timestamp, api_nonce and api_secret) are concatenated together into a single string:

<api_timestamp><api_nonce><api_secret>

  1. SHA-1 digest is calculated. The calculated SHA-1 HEX digest for the above string will be:

4591350417a53c4656572ab14bd4f1759a48019b

An authenticated API call will look like this:

https://api.publit.io/v1/files/list?api_key=a73eda4c9cd05a757e05ac1557f62be7&api_nonce=35367098&api_signature=4591350417a53c4656572ab14bd4f1759a48019b&api_timestamp=1515580186

Protection against replay-attacks

When a signature-based method is used it is possible that the call can be captured by a malicious party and “replayed” later. To protect against this type of attack, the Publitio API implements the following measures:

Testing the API

For convenience of testing the Publitio API, you can generate a full API Signature at the Dashboard and use it via browser, Postman or curl for testing. Each API signature is valid for 1h and 1 API call. For multiple API calls and 24h TTL please append &api_test=true to the end of the API Signature.

An authenticated API call for testing will look like this:

https://api.publit.io/v1/files/list?api_key=a73eda4c9cd05a757e05ac1557f62be7&api_nonce=35367098&api_signature=4591350417a53c4656572ab14bd4f1759a48019b&api_timestamp=1515580186&api_test=true

Bearer Token Authentication

As an alternative to signature-based authentication, the Publitio API supports Bearer token authentication. Personal access tokens can be created and managed from the Dashboard and are suited for server-side integrations, team workflows, and scoped access control.

curl -X GET "https://api.publit.io/v1/files/list" \
-H "Accept: application/json" \
-H "Authorization: Bearer <your_access_token>"
// When using Bearer token, pass it as the Authorization header directly
$ch = curl_init('https://api.publit.io/v1/files/list');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Accept: application/json',
    'Authorization: Bearer <your_access_token>',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
import PublitioAPI from 'publitio_js_sdk'

// Pass the bearer token instead of API key/secret
fetch('https://api.publit.io/v1/files/list', {
    headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer <your_access_token>'
    }
}).then(res => res.json()).then(data => console.log(data))

To authenticate using a Bearer token, include it in the Authorization HTTP header of every request:

Authorization: Bearer <your_access_token>

Token Scopes

Each token can be issued with a set of permission scopes that restrict what operations it can perform. The following scopes are supported:

Scope Description
* Full access — equivalent to using your API Key/Secret directly.
read Read-only access. Allows listing and showing resources but not creating, updating or deleting.
create Allows creating new resources (e.g. uploading files).
update Allows updating existing resources.
delete Allows deleting resources.

Download SDK's

Here is a list of SDK's for the Publitio API that you can download and integrate with frameworks of your choice. We're working on adding more supported languages soon.

URL-Based Transformations

Publitio offers a URL-based form of API through which you can do all file transformations on the fly, just over the browser, by changing parameters in the file URL. You can use it to transcode your files between formats, for resizing, cropping, trimming, watermarking and/or quality adjustment.

The idea is identical to the Create Version method: you pass options and extension to the file URL and a new file version will be created on the fly.

https://media.publit.io/file/<options>/<file_id>.<extension>

List of supported file formats (extensions)

List of options for transformations

For options, you can use the following: w and h for resizing, c for cropping, wm for watermarking, q for quality adjustment, and t / so / eo for video/audio trimming. For image adjustments (images and video-to-image extractions): f (flip), rt (rotate), bl (blur), bri (brightness), ct (contrast), sh (sharpen), gs (grayscale), sep (sepia), px (pixelate), ti (tint), gm (gamma), g (crop gravity for c_fill). See the Create Version section for the full option reference.

Sample files

This is our sample Butterflies image: https://media.publit.io/file/butterflies.jpg

alt text

our sample video Tummy: https://media.publit.io/file/tummy.mp4

our sample audio Railgun: https://media.publit.io/file/railgun.wav

and our sample document: https://media.publit.io/file/doc.pdf

Let's see on a few examples how to use options and extensions parameters to do various transformations:

Resizing

To resize an image or video to 600 pixels in width append w_600 to the URL, as in:

https://media.publit.io/file/w_600/butterflies.jpg

alt text

To resize an image or video to 400x400 pixels in size append w_400,h_400 to the URL, as in:

https://media.publit.io/file/w_400,h_400/butterflies.jpg

alt text

Cropping

For cropping, please use the c parameter in combination with w (width) and h (height) parameters. Supported values are c_fit (fit), c_fill (fill) and c_limit (limit).

c_fill will resize the image or video to exact given width and height while retaining the original aspect ratio, using only a part of the original file that fills the given dimensions if necessary.

To create a 300x300 pixel thumbnail out of an image with c_fill, append w_300,h_300,c_fill to the URL as in:

https://media.publit.io/file/w_300,h_300,c_fill/butterflies.jpg

alt text

c_fit will resize the file so that it takes up as much space as possible within a bounding box defined by the given width and height parameters. Original aspect ratio is retained and all of the original file is visible. To create 300x300 pixel thumbnail out of our sample image with c_fit, append w_300,h_300,c_fit to the URL as in:

https://media.publit.io/file/w_300,h_300,c_fit/butterflies.jpg

alt text

c_limit is same as the c_fit mode but only if the original file is larger than the given limit (width and height), in which case the image or video is scaled down so that it takes up as much space as possible within a bounding box defined by the given width and height parameters.

When using c_fill, you can control which region of the image is preserved with the g (gravity) option. Supported values are: g_tl (top-left), g_t (top), g_tr (top-right), g_l (left), g_c (center, default), g_r (right), g_bl (bottom-left), g_b (bottom), g_br (bottom-right). For example, to crop to 300×300 keeping the top left of the image:

https://media.publit.io/file/w_300,h_300,c_fill,g_tl/butterflies.jpg

alt text

Watermarking

For watermarking of images and videos use the wm option. To watermark our sample image using a watermark with ID publitio append wm_publitio to the URL:

https://media.publit.io/file/wm_publitio,w_800/butterflies.jpg

alt text

You can use wm in combination with the rest of the options, for example w_800,h_600,c_fill,wm_publitio.

Trimming

For trimming (video and audio option) please use the so (start offset) and eo (end offset) parameters.

Option t (time) can be used for video to image transformation. For example, to get an image from the 3rd second of video, use t_3 as an option and set the extension to jpg in the URL:

https://media.publit.io/file/t_3,w_800/tummy.jpg

alt text

To create a 2 second long trimmed video out of the original video starting from 2nd second, use so_2,eo_2 in the URL. so_2 indicates from which second (2) to start trimming and eo_2 is making the trimmed video 2 seconds long:

https://media.publit.io/file/so_2,eo_2,h_480/tummy.mp4


To create a 2 second long trimmed audio from original audio starting at 1st second, use so_1,eo_2 in the URL. so_1 indicates at which second (1) to start trimming and eo_2 makes the trimmed audio 2 seconds long:

https://media.publit.io/file/so_1,eo_2/railgun.mp3

Transcoding

Here we will show how you can easily do image to image, image to video, video to video, video to image, video to audio, audio to audio, audio to video, audio to image (waveform) and document to image transformations with the URL-Based API.

Image to image

To transcode our sample image to png format, we just need to change the extension in the URL like this:

https://media.publit.io/file/butterflies.png

alt text

Image adjustment options like gs_1 (grayscale) can be combined with any extension. For example, to convert our sample image to a grayscale png:

https://media.publit.io/file/gs_1/butterflies.png

alt text

We can combine different extensions with all the options, so for example to create and image 500 pixels wide, with a watermark and in gif format, we can use w_500,wm_publitio as the options and gif as the extension:

https://media.publit.io/file/w_500,wm_publitio/butterflies.gif

alt text

Image to video

To create an mp4 video out of an image (useful for gif files and player integration), change the extension to mp4:

https://media.publit.io/file/w_800/butterflies.mp4

Video to video

Any video you upload can be transcoded to mp4, webm and ogv formats.

To create a 360p mp4 video out of our original sample Tummy video, format the URL as in:

https://media.publit.io/file/h_360/tummy.mp4

Transcoding can be done in combination with other available options, so for example to create a 480p mp4 watermarked video out of the original, we can add h_480,wm_publitio to the URL and set the extension to mp4:

https://media.publit.io/file/h_480,wm_publitio/tummy.mp4

Video to image

You can extract an image from any part of the video. To create a png image from the 2nd second of video, add t_2 (time = 2 seconds) to the URL as follows:

https://media.publit.io/file/t_2/tummy.png

alt text

This can be useful for generating thumbnails from the video, just by adding the right w (width) and different t (time) options to the URL:

https://media.publit.io/file/t_1,w_200/tummy.png

alt text

https://media.publit.io/file/t_2,w_200/tummy.png

alt text

https://media.publit.io/file/t_3,w_200/tummy.png

alt text

Video to audio

Any video you upload can be transcoded to mp3, wav and ogg audio formats.

To create mp3 audio out of our original sample Tummy video, format the URL as in:

https://media.publit.io/file/tummy.mp3


Video to audio transformations support so and eo parameters for trimming the audio. To create 2 seconds of mp3 audio, starting from the 2nd second of video, format the URL as:

https://media.publit.io/file/so_2,eo_2/tummy.mp3


Audio to audio

Any audio you upload can be transcoded to following audio formats: mp3, wav and ogg.

To create mp3 audio out of our original sample Railgun wav audio, format the URL as in:

https://media.publit.io/file/railgun.mp3


Audio to audio transformations support so and eo parameters for audio trimming. To create 2 seconds of mp3 audio, starting from the 2nd second of audio, format the URL as:

https://media.publit.io/file/so_2,eo_2/railgun.mp3


Audio to image

You can transcode uploaded audio files to images (waveforms) in following formats: jpg, png, gif and webp. This is useful if you need to have some visual representation of an audio file.

To create a png out of our original sample Railgun wav audio, format the URL as in:

https://media.publit.io/file/railgun.png

alt text

To control the waveform and background color, please use fc (foreground color) and bc (background color) parameters. Both fc and bc will accept any HEX color value (for example fc_66A8CC,bc_000000) or pre-defined color values like grey, blue, green, orange, pink, red, yellow, black and white. For example to generate a jpg waveform image from a wav audio file, with blue waveform and black background, use option fc_blue,bc_black and format the URL as in:

https://media.publit.io/file/fc_blue,bc_black/railgun.jpg

alt text

Audio to video

You can create videos out of audio files. Supported video from audio formats are: mp4, webm and ogv. This basically creates a video by combining the waveform and audio of our file, and is useful if you want to play audio within a video player and wish to monetize audio files through video ads.

To create an mp4 video out of our original sample Railgun wav audio, format the URL as in:

https://media.publit.io/file/railgun.mp4


Document to image

You may use the t option on documents to get a specific page. For example, imagine we have a file called doc.pdf. To get the second page of this document in png format, we could use t_2:

https://media.publit.io/file/t_2/doc.png

alt text

In this case, all options for images also apply. To get the second page in png format with 300x300 dimensions and cropped to fit, we could use:

https://media.publit.io/file/t_2,w_300,h_300,c_fit/doc.png

alt text

Quality

Quality adjustment of your images, videos and audio files can be controlled through the q parameter. This parameter represents the compression level to apply to a media file between 1 (smallest file size possible) and 100 (best quality). For example, to reduce the quality of our sample image to 50, please use q_50:

https://media.publit.io/file/q_50/butterflies.jpg

alt text

Files

The Files Class allows easy creation (uploading) and management of your images, videos, audio files and documents. With it you can use the Publitio API to upload, host, download and deliver your media files. Publitio goes a few steps further and allows transformations and transcoding of your files via the Versions Class, publishing via the HTML5 Media Player through the Players Class, monetization with ads thanks to the Adtags Class, and even copyright protection via the Watermarks Class.

Create File

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

$response = $publitio_api->upload_file(
    fopen('file.jpg'), 'file',
    array(
        'public_id' => 'mytestwm',
        'description' => 'some nice desc',
        'tags' => 'one, two, three'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X POST "https://api.publit.io/v1/files/create?{{api_signature}}" \
-H "Accept: application/json" \
--form public_id=mytestfile \
--form file=@/localpathtoimage/file.png
import PublitioAPI from 'publitio_js_sdk'
import { readFileSync } from 'fs'

// This could also be a ReadableStream in Node, a File in the browser or a string
const file = readFileSync('image.png')

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.uploadFile(file, 'file')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.create_file(file=open('path/to/file', 'rb'),
                         title='My title',
                         description='My description')

# Note that the file must be opened for binary reading.
# The publitio_api.create_file function will not close the file.
# Therefore, what you will probably want to do most of the time is:

with open('path/to/file.png', 'rb') as f:
    publitio_api.create_file(file=open('path/to/file', 'rb'),
                             title='My title',
                             description='My description')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 201,
  "message": "File uploaded",
  "id": "qAfRRgxx",
  "public_id": null,
  "folder": "Y2K/",
  "folder_id": "4vZsZBGa",
  "title": "sample file",
  "description": "",
  "tags": "",
  "type": "image",
  "extension": "jpg",
  "size": 26846,
  "width": 373,
  "height": 373,
  "privacy": "public",
  "option_download": "enabled",
  "option_ad": "enabled",
  "option_transform": "enabled",
  "wm_id": null,
  "url_preview": "https://media.publit.io/file/Y2K/qAfRRgxx.jpg",
  "url_thumbnail": "https://media.publit.io/file/w_300,h_200,c_fill/qAfRRgxx.jpg",
  "url_download": "https://media.publit.io/download/qAfRRgxx.jpg?at=eyJpdiI6Inc5NGg2TG1IZDB4bDJTUXpaUmRUd1E9PSIsInZhbHVlIjoiaVlIRmd3SFo5YTdOR1hMdENLZmErdGEyR3pWbk1IYmtoTHdwT0VsU25BWT0iLCJtYWMiOiI0MzlmMmYwM2IxY2YxNDE1ZmZmNjgxMGI1M2JmMjQ5NTgyZDk3N2JkN2M4ZDA1NzZhMzU1MjRiMGE2NDkwN2YyIn0=",
  "versions": 0,
  "hits": 0,
  "created_at": "2018-01-15 08:37:15",
  "updated_at": "2018-01-15 08:37:15"
}

This endpoint creates (uploads) a new file. You can upload the following file types:

HTTP Request

POST https://api.publit.io/v1/files/create

Query Parameters

Parameter Required Type Description
file yes file Image or video to upload.
file_url no URL Remote image or video URL if no file is present.
public_id no string Unique alphanumeric public ID of the file. Default is null (random public ID).
folder no string Folder ID to place the file in. Default is null (root folder).
title no string File title. Default is taken from the file name.
description no string File description.
tags no string File tags separated by spaces or commas. Used for search.
privacy no bool File privacy. Supported values are 0 (private) and 1 (public). Default is 0 (private).
option_download no bool Enable file download. Supported values are 0 (disabled) and 1 (enabled). Default is 1 (enabled).
option_transform no bool Enable URL-based transformations. Supported values are 0 (disabled) and 1 (enabled). Default is 1 (enabled).
option_ad no bool Enable ads on this file. Supported values are 0 (disabled), 1 (enabled) and 2 (new). Default is 1 (enabled).
option_hls no bool Enables HLS video encryption on the video file. Supported values are 0 (disabled), 1 (enabled).
wm no string Watermark ID. Default is null (no watermark).
cname no string Cname ID. Default is null.

List Files

$publitio_api = new \Publitio\API('<API Key>' '<API Secret>');
$response = $publitio_api->call('/files/list', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/files/list?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/files/list', 'GET', { offset: '0', limit: '10' })
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
response = publitio_api.list_files(offset=1)

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "limit": 100,
  "offset": 0,
  "files_total": 2,
  "files_count": 2,
  "files": [
    {
      "id": "RVsbVdyp",
      "public_id": null,
      "folder": null,
      "folder_id": null,
      "title": "rasa1",
      "description": "",
      "tags": "",
      "type": "image",
      "extension": "jpg",
      "size": 77008,
      "width": 1000,
      "height": 667,
      "privacy": "public",
      "option_download": "enabled",
      "option_ad": "enabled",
      "option_transform": "enabled",
      "wm_id": null,
      "url_preview": "https://media.publit.io/file/RVsbVdyp.jpg",
      "url_thumbnail": "https://media.publit.io/file/w_300,h_200,c_fill/RVsbVdyp.jpg",
      "url_download": "https://media.publit.io/download/RVsbVdyp.jpg?at=eyJpdiI6Ik5XT2t2QkRkeHNiUmxJZDR6QTBGcEE9PSIsInZhbHVlIjoiN01CXC9WYWxGdGRBZ29wak1jXC80d1B0TlVIWko0OCtIbjB3VXZIM0J2ZHlNPSIsIm1hYyI6IjA2MGFjYzI1Y2U0MTFkMzZmMGQyNjdmNTM0Mjk1MzI1NjQzZjk1ZmY2ODE4N2NhODRmYjE1MTZmZTgwY2VlOTgifQ==",
      "versions": 1,
      "hits": 13,
      "created_at": "2017-11-22 15:48:13",
      "updated_at": "2017-12-20 11:26:59"
    },
    {
      "id": "oZTuvJmJ",
      "public_id": null,
      "title": "rasa2",
      "folder": null,
      "folder_id": null,
      "description": "",
      "tags": "",
      "type": "image",
      "extension": "jpg",
      "size": 77785,
      "width": 1000,
      "height": 665,
      "privacy": "public",
      "option_download": "enabled",
      "option_ad": "enabled",
      "option_transform": "enabled",
      "wm_id": null,
      "url_preview": "https://media.publit.io/file/oZTuvJmJ.jpg",
      "url_thumbnail": "https://media.publit.io/file/w_300,h_200,c_fill/oZTuvJmJ.jpg",
      "url_download": "https://media.publit.io/download/oZTuvJmJ.jpg?at=eyJpdiI6IkZBU0VzSDZFZkFuYzdOcmZ0a213MVE9PSIsInZhbHVlIjoiT0R3K2FRZ2cxU1huUlpiNzFURDJkN3pBeTVxMzJMZTRRWjV3U3dEc21ncz0iLCJtYWMiOiJiZjQwODk0NmZkZThjYTQ0MzQ4MzU4NmFiNzgxNzRhYzE5ZWFhZTA4YWM5Mzg3MTYyOGFhYjlhMWMyOWU5NmUxIn0=",
      "versions": 1,
      "hits": 5,
      "created_at": "2017-11-22 15:48:14",
      "updated_at": "2017-12-20 11:27:30"
    }
  ]
}

This endpoint returns a list of all uploaded files.

HTTP Request

GET https://api.publit.io/v1/files/list

Query Parameters

Parameter Required Type Description
limit no int Maximum number of files to return. Default is 100. Maximum limit is 1000.
offset no int How many files should be skipped at the beginning of the result set. Default is 0.
order no string How the files should be ordered. Supported values are date, name, size and hits. You may also append :asc for an ascending sort order or :desc for a descending order (for example name:desc). By default, the files are sorted by date in ascending order.
filter_privacy no string Specifies which files should be returned based on their privacy. Supported values are all, private and public. Default is all.
filter_extension no string Specifies which files should be returned based on their extension. For a full list of extensions see supported extensions. Default is all.
filter_type no string Specifies which files should be returned based on their type. Supported values are all, image, video and audio. Default is all.
filter_ad no string Specifies which files should be returned based on their option_ad status. Supported values are all, enabled, disabled and new. Default is all.
tags no string Search query tags separated by + signs. You can append :any to list files which have any of the tags, or :all to list only files which have all of the tags. Default mode is all. For example, use dogs+cats:any to select all files which either have the dogs or the cats tag.
folder no string Folder ID or Path to list files from. Default is null (lists all files). Use / to list top (root) folder files.
search no string Search query to filter files by. Matches against file code, title, public_id and tags.

Show File

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Show file with id MvHX8Zx5
$response = $publitio_api->call('/files/show/MvHX8Zx5', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/files/show/MvHX8Zx5?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Show file with id MvHX8Zx5
publitio.call('/files/show/MvHX8Zx5', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Show file with ID MvHX8Zx5
publitio_api.show_file('MvHX8Zx5')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "id": "MvHX8Zx5",
  "public_id": null,
  "title": "rasa1",
  "description": "",
  "tags": "",
  "type": "image",
  "extension": "jpg",
  "size": 77008,
  "width": 1000,
  "height": 667,
  "privacy": "public",
  "option_download": "enabled",
  "option_ad": "enabled",
  "option_transform": "enabled",
  "wm_id": null,
  "url_preview": "https://media.publit.io/file/MvHX8Zx5.jpg",
  "url_thumbnail": "https://media.publit.io/file/w_300,h_200,c_fill/MvHX8Zx5.jpg",
  "url_download": "https://media.publit.io/download/MvHX8Zx5.jpg?at=eyJpdiI6IkhHK0o2SUp0Rmw0Ynh6WVU2T1diV2c9PSIsInZhbHVlIjoidlFcL3RERUZRaWRmbWVsTG9BQWdyTXozQWprR1VhSGVLN3RMR3RxUVVSd1k9IiwibWFjIjoiY2ZjNGQ2YmUzM2JiYzQ2YzRhZjkzMDRhMDY3NjBjNzNmMmM3YzZkMTlkN2ZkMDA4NGZkOTI1ZGJhZWQzMzI2YyJ9",
  "versions": 2,
  "hits": 14,
  "created_at": "2017-11-22 15:48:13",
  "updated_at": "2018-01-10 16:00:22"
}

This endpoint shows specific file info based on its ID.

HTTP Request

GET https://api.publit.io/v1/files/show/<file_id>

Query Parameters

Parameter Required Type Description
id yes string Target file ID.
cname no string Cname ID. Default is null.

Update File

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');
// Update file with id MvHX8Zx5
$response = $publitio_api->call(
    '/files/update/MvHX8Zx5',
    'PUT',
    array(
        'position' => 'top-left',
        'padding' => '10'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X PUT "https://api.publit.io/v1/files/update/MvHX8Zx5?{{api_signature}}" \
-H "Accept: application/json" \
--data title="New File Title" \
--data description="This id file description..."
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// update file with id MvHX8Zx5
publitio.call('/files/update/MvHX8Zx5', 'PUT', {
    title: 'some title',
    description: 'dome desc',
    tags: 'tag1 tag2',
    privacy: '1',
    option_download: '1',
    option_ad: '1'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Update file with id MvHX8Zx5
publitio_api.update_file('MvHX8Zx5', title='A better title')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The file with with id 'MvHX8Zx5' has been updated"
}

This endpoint updates file info.

HTTP Request

PUT https://api.publit.io/v1/files/update/<file_id>

Query Parameters

Parameter Required Type Description
id yes string Target file ID.
public_id no string Unique alphanumeric public ID of the file.
folder no string Folder ID to place the file in.
title no string File title.
description no string Optional file description.
tags no string Optional file tags separated by spaces or commas. Used for search.
privacy no bool File privacy. Supported values are 0 (private) and 1 (public).
option_download no bool Enable file download. Supported values are 0 (disabled) and 1 (enabled).
pdf_print no boolean Allow printing for PDF files. 0 (disabled) or 1 (enabled). Applies to PDF files only.
option_transform no bool Enable URL-based transformations. Supported values are 0 (disabled) and 1 (enabled).
option_ad no bool Enable ads on the file. Supported values are 0 (disabled), 1 (enabled) and 2 (new).
option_hls no bool Enables HLS video encryption on the video file. Supported values are 0 (disabled), 1 (enabled).
thumb_id no string Unique alphanumeric name (ID) of an image file to be used as the player thumbnail. To disable an existing thumbnail, use none. This option is only valid for video and audio files.
wm no string Watermark ID. Default is null.
cname no string Cname ID. Default is null.
password no string Password to protect the file. Minimum 6 characters. Pass an empty string to remove password protection.
direct_url no boolean Use direct URL for document files (non-PDF and non-VTT). 0 (disabled) or 1 (enabled).
metadata no object JSON object of embedded media metadata tags (e.g. title, artist, album, genre, comment, date, copyright). Applied via FFmpeg for video/audio files.
chapters no array JSON array of chapter markers for video files. Each chapter object contains start time and title.

Replace File

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Replace binary of file with code MvHX8Zx5
$response = $publitio_api->call('/files/MvHX8Zx5/replace', 'POST', array(), array('file' => '/path/to/new/file.mp4'));
# Please replace {{api_signature}} with your API signature
curl -X POST "https://api.publit.io/v1/files/MvHX8Zx5/replace?{{api_signature}}" \
-H "Accept: application/json" \
-F file=@/path/to/new/file.mp4
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/files/MvHX8Zx5/replace', 'POST', {}, { file: fileInput.files[0] })
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.call('/files/MvHX8Zx5/replace', 'POST', file=open('/path/to/new/file.mp4', 'rb'))

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": {
    "id": "MvHX8Zx5",
    "title": "My Video",
    "extension": "mp4",
    "size": 5242880,
    "width": 1280,
    "height": 720,
    "duration": 120.5,
    "url_preview": "https://media.publit.io/file/MvHX8Zx5.mp4",
    "updated_at": "2024-01-10 14:56:52"
  }
}

This endpoint replaces the binary content of an existing file while preserving all metadata (title, description, tags, settings, options, etc.). The replacement file must have the same extension as the original. Any existing versions (transcodes) are automatically re-queued for reconversion using the new source file.

HTTP Request

POST https://api.publit.io/v1/files/<file_code>/replace

URL Parameters

Parameter Required Type Description
file_code yes string The unique code of the file to replace.

Body Parameters

Parameter Required Type Description
file yes file The new file binary (multipart/form-data). Must have the same extension as the original file.

Delete File

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Delete file with id MvHX8Zx5
$response = $publitio_api->call('/files/delete/MvHX8Zx5', 'DELETE');
# Please replace {{api_signature}} with your API signature
curl -X DELETE "https://api.publit.io/v1/files/delete/MvHX8Zx5?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Delete file with id MvHX8Zx5
publitio.call('/files/delete/MvHX8Zx5', 'DELETE')
   .then((data) => { console.log(data) })
   .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Delete file with id MvHX8Zx5
publitio_api.delete_file('MvHX8Zx5')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The file with id 'MvHX8Zx5' has been deleted!"
}

This endpoint deletes a file based on its ID.

HTTP Request

DELETE https://api.publit.io/v1/files/delete/<file_id>

Query Parameters

Parameter Required Type Description
id yes string Target file ID.

Player File

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Get player for file with id mytestfile
$response = $publitio_api->call('/files/player/mytestfile', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/files/player/mytestfile?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Get player for file with id mytestfile
publitio.call('/files/player/mytestfile', 'GET', {
    player: 'myplayer',
    adtag: 'myadtag'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Get player for file with id mytestfile
publitio_api.get_file_player('mytestfile', player='myplayer')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "embed_url": "//media.publit.io/file/RVsbVdyp.html",
  "player_html": "<div id=\"publitio_RVsbVdyp\" class=\"publitioPlayer\" ><div id=\"publitio_ph_RVsbVdyp\" class=\"publitioPlaceHolder\" ><div id=\"publitio_phb_RVsbVdyp\" class=\"publitioPlaceHolderBtn\" ></div><img class=\"publitioPlaceHolderImg\" src=\"https://media.publit.io/file/RVsbVdyp.jpg\" ></div></div><link href=\"http://static.publit.io/css/publitio_player.min.css\" rel=\"stylesheet\" /><script src=\"http://static.publit.io/js/publitio_player.min.js\"></script><script src=\"//imasdk.googleapis.com/js/sdkloader/ima3.js\"></script><script type=\"text/javascript\">var publitio_RVsbVdyp = new Publitio({id: \"RVsbVdyp\", width: \"1000\", height: \"667\", fileSources: {mp4:\"https://media.publit.io/file/RVsbVdyp.mp4\", webm:\"https://media.publit.io/file/RVsbVdyp.webm\", ogv:\"https://media.publit.io/file/RVsbVdyp.ogv\", jpg:\"https://media.publit.io/file/RVsbVdyp.jpg\"}, adTag: \"\", autoPlay: 0, controlBar: \"false\", playerSkin: \"grey\"});</script>",
  "source_html": "<img src=\"https://media.publit.io/file/w_640/RVsbVdyp.jpg\" srcset=\"https://media.publit.io/file/w_320/RVsbVdyp.jpg 320w, https://media.publit.io/file/w_640/RVsbVdyp.jpg 640w\" sizes=\"100vw\" alt=\"xoxoxo\" />",
  "iframe_html": "<div><div  style=\"left: 0; width: 100%; height: 0; position: relative; padding-bottom: 62.5%;\"><iframe src=\"https://media.publit.io/file/RVsbVdyp.html?player=&adtag=\" scrolling=\"no\" style=\"border: 0; top: 0; left: 0; width: 100%; height: 100%; position: absolute; overflow:hidden;\" allowfullscreen=\"\" ></iframe></div></div>"
}

This endpoint shows the HTML5 Media Player containing the specified file. It returns source_html that you can insert directly into your HTML code.

HTTP Request

GET https://api.publit.io/v1/files/player/<file_id>

Query Parameters

Parameter Required Type Description
player yes string Target player ID.
adtag no string ID of adtag to load with the player.
adtag_url no string URL of VAST/IMA adtag to load with the player (overwrites the adtag parameter).
auto_play no int Auto-play content (overwrites player auto_play setting). Supported values are 0 (off), 1 (on) and 2 (onmouseover).
cname no string Cname ID. Default is null.

Embed URL

File Player call response will have an embed_url field. This is a direct URL that you can use to preview your files within the Publitio Player. To access it, just change the extension to html on any Preview URL you get for you files:

https://media.publit.io/file/<file_id>.html

For example, to preview our sample Tummy video, you can go to: https://media.publit.io/file/tummy.html.

You can pass the player query parameter to preview files with a different player setup, for example: https://media.publit.io/file/tummy.html?player=publitio.

Source Html

File Player call response will have a source_html field. In case of an image, this will be a <img src="..."> or <img srcset="..."> formatted tag you can insert directly into your HTML code. For videos, this will be a <video ... > tag with predefined sources (paths to video streams), and in case of audio files this will be a <audio ... > HTML5 tag.

For example, source_html for our sample image Butterflies behaves as:

Iframe HTML

File Player call response will have an iframe_html field. This is formatted HTML with responsive iframe code and embed URL - the easiest way to embed videos, images and audio into your webpage. For example, iframe from our sample Tummy video is embedded as:

Player HTML

File Player call response will have a player_html field. This code is the same as iframe_html, except it doesn't use iframe and embed URL, but instead provides formatted HTML code that crates/inserts a player directly into your webpage.

Apply Preset to File

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Apply preset to file with id MvHX8Zx5
$response = $publitio_api->call(
    '/files/preset/MvHX8Zx5',
    'PUT',
    array('preset' => 'mypreset')
);
# Please replace {{api_signature}} with your API signature
curl -X PUT "https://api.publit.io/v1/files/preset/MvHX8Zx5?{{api_signature}}" \
-H "Accept: application/json" \
--data preset="mypreset"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/files/preset/MvHX8Zx5', 'PUT', {
    preset: 'mypreset'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.call('/files/preset/MvHX8Zx5', 'PUT', {'preset': 'mypreset'})

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The file with with id 'MvHX8Zx5' has been updated"
}

This endpoint applies an upload preset configuration to an existing file. The preset settings (privacy, transformations, download options, ad options, watermark, HLS, and tags) are applied to the file immediately.

HTTP Request

PUT https://api.publit.io/v1/files/preset/<file_id>

Query Parameters

Parameter Required Type Description
id yes string Target file ID.
preset yes string Preset code to apply to the file.

Update Multiple Files Metadata

# Please replace {{api_signature}} with your API signature
curl -X POST "https://api.publit.io/v1/files/update_multiple_meta?{{api_signature}}" \
-H "Accept: application/json" \
--form files=@/path/to/file_codes.csv \
--form title="New Title" \
--form artist="Artist Name"

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "Metadata update job dispatched for X files"
}

This endpoint updates embedded media metadata for multiple video or audio files in bulk. You must upload a CSV file containing one file code per line. The update is processed asynchronously via a background job.

HTTP Request

POST https://api.publit.io/v1/files/update_multiple_meta

Query Parameters

Parameter Required Type Description
files yes file CSV file with one file code per line.
title no string Media title tag to apply to all files.
artist no string Artist name tag to apply to all files.
album no string Album name tag to apply to all files.
genre no string Genre tag to apply to all files.
comment no string Comment tag to apply to all files.
date no string Date/year tag to apply to all files.
copyright no string Copyright tag to apply to all files.

Multi-File Download

# Please replace {{api_signature}} with your API signature
curl -X POST "https://api.publit.io/v1/files/multidownload?{{api_signature}}" \
-H "Accept: application/json" \
--form files=@/path/to/file_codes.csv

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": {
    "status": "processing",
    "message": "Your files are being prepared."
  }
}

This endpoint creates a ZIP archive of multiple files for download. You must upload a CSV file containing one file code per line. The ZIP is created asynchronously — call this endpoint again with the same file list to check if the archive is ready. When ready, a status: "ready" response is returned.

HTTP Request

POST https://api.publit.io/v1/files/multidownload

Query Parameters

Parameter Required Type Description
files yes file CSV file with one file code per line. Maximum total size is 5 GB.

Subtitles

The Subtitles Class (a sub-class of Files) allows management of subtitle and caption tracks for your video files. Subtitles are stored as VTT files linked to a parent video file.

List Subtitles

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// List subtitles for file with id MvHX8Zx5
$response = $publitio_api->call('/files/subtitles/list/MvHX8Zx5', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/files/subtitles/list/MvHX8Zx5?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/files/subtitles/list/MvHX8Zx5', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.call('/files/subtitles/list/MvHX8Zx5', 'GET')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "limit": 100,
  "offset": 0,
  "subtitles_total": 1,
  "subtitles_count": 1,
  "subtitles": [
    {
      "id": "abcd1234",
      "public_id": "my-subtitle-en",
      "language": "English",
      "language_code": "en",
      "url": "https://media.publit.io/file/my-subtitle-en.vtt",
      "created_at": "2024-01-15 10:00:00",
      "updated_at": "2024-01-15 10:00:00"
    }
  ]
}

This endpoint lists all subtitle tracks associated with a specific video file.

HTTP Request

GET https://api.publit.io/v1/files/subtitles/list/<file_id>

Query Parameters

Parameter Required Type Description
id yes string Target video file ID.
limit no int Maximum number of subtitles to return. Default is 100. Maximum is 1000.
offset no int How many subtitles to skip at the beginning of the result set. Default is 0.
order no string How the subtitles should be ordered. Supported values are date, name, size and hits. You may append :asc or :desc. Default is date.

Create Subtitle

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Add a subtitle to file with id MvHX8Zx5
$response = $publitio_api->call(
    '/files/subtitles/create/MvHX8Zx5',
    'POST',
    array(
        'subtitle_id' => 'abcd1234',
        'language' => 'English',
        'language_code' => 'en'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X POST "https://api.publit.io/v1/files/subtitles/create/MvHX8Zx5?{{api_signature}}" \
-H "Accept: application/json" \
--data subtitle_id="abcd1234" \
--data language="English" \
--data language_code="en"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/files/subtitles/create/MvHX8Zx5', 'POST', {
    subtitle_id: 'abcd1234',
    language: 'English',
    language_code: 'en'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.call('/files/subtitles/create/MvHX8Zx5', 'POST', {
    'subtitle_id': 'abcd1234',
    'language': 'English',
    'language_code': 'en'
})

The above command returns JSON structured like this:

{
  "success": true,
  "code": 201,
  "message": "Subtitle added",
  "id": "abcd1234",
  "public_id": "my-subtitle-en",
  "language": "English",
  "language_code": "en",
  "url": "https://media.publit.io/file/my-subtitle-en.vtt",
  "created_at": "2024-01-15 10:00:00",
  "updated_at": "2024-01-15 10:00:00"
}

This endpoint links an existing VTT subtitle file to a video file. The subtitle file must already be uploaded with a .vtt extension.

HTTP Request

POST https://api.publit.io/v1/files/subtitles/create/<file_id>

Query Parameters

Parameter Required Type Description
id yes string Target video file ID to attach the subtitle to.
subtitle_id yes string File ID of the uploaded VTT subtitle file.
language yes string Human-readable language name (e.g. English, French).
language_code yes string ISO language code (e.g. en, fr).

Update Subtitle

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Update subtitle on file with id MvHX8Zx5
$response = $publitio_api->call(
    '/files/subtitles/update/MvHX8Zx5',
    'PUT',
    array(
        'subtitle_id' => 'abcd1234',
        'language' => 'Spanish',
        'language_code' => 'es'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X PUT "https://api.publit.io/v1/files/subtitles/update/MvHX8Zx5?{{api_signature}}" \
-H "Accept: application/json" \
--data subtitle_id="abcd1234" \
--data language="Spanish" \
--data language_code="es"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/files/subtitles/update/MvHX8Zx5', 'PUT', {
    subtitle_id: 'abcd1234',
    language: 'Spanish',
    language_code: 'es'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.call('/files/subtitles/update/MvHX8Zx5', 'PUT', {
    'subtitle_id': 'abcd1234',
    'language': 'Spanish',
    'language_code': 'es'
})

The above command returns JSON structured like this:

{
  "success": true,
  "code": 201,
  "message": "Subtitle updated",
  "id": "abcd1234",
  "public_id": "my-subtitle-en",
  "language": "Spanish",
  "language_code": "es",
  "url": "https://media.publit.io/file/my-subtitle-en.vtt",
  "created_at": "2024-01-15 10:00:00",
  "updated_at": "2024-01-15 11:00:00"
}

This endpoint updates the language name and language code of an existing subtitle track on a video file.

HTTP Request

PUT https://api.publit.io/v1/files/subtitles/update/<file_id>

Query Parameters

Parameter Required Type Description
id yes string Target video file ID.
subtitle_id yes string File ID of the subtitle to update.
language yes string Human-readable language name (e.g. English, Spanish).
language_code yes string ISO language code (e.g. en, es).

Delete Subtitle

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Remove subtitle from file with id MvHX8Zx5
$response = $publitio_api->call(
    '/files/subtitles/delete/MvHX8Zx5',
    'DELETE',
    array('subtitle_id' => 'abcd1234')
);
# Please replace {{api_signature}} with your API signature
curl -X DELETE "https://api.publit.io/v1/files/subtitles/delete/MvHX8Zx5?{{api_signature}}" \
-H "Accept: application/json" \
--data subtitle_id="abcd1234"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/files/subtitles/delete/MvHX8Zx5', 'DELETE', {
    subtitle_id: 'abcd1234'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.call('/files/subtitles/delete/MvHX8Zx5', 'DELETE', {
    'subtitle_id': 'abcd1234'
})

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The subtitle with id 'abcd1234' has been removed from file with id 'MvHX8Zx5'!"
}

This endpoint removes a subtitle track from a video file. It will not delete the actual .VTT file.

HTTP Request

DELETE https://api.publit.io/v1/files/subtitles/delete/<file_id>

Query Parameters

Parameter Required Type Description
id yes string Target video file ID.
subtitle_id yes string File ID of the subtitle to remove.

Versions

Versions Class (a sub-class of Files) allows easy creation and management of derived versions of your uploaded files. With it you can do transformations, transcoding between formats, cropping, resizing, watermarking, quality adjustment, and more.

Create Version

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Create a new version from file with ID mytestfile, with options width=320, height=240, crop=fill
$response = $publitio_api->call(
    '/files/versions/create/mytestfile',
    'POST',
    array(
        'extension' => 'mp4',
        'options' => 'w_320,h_240,c_fill'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X POST "https://api.publit.io/v1/files/versions/create/mytestfile?{{api_signature}}" \
-H "Accept: application/json" \
--data extension="mp4" \
--data options="w_320,h_240,c_fill"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Create a new version from file with ID mytestfile, with options width=320, height=240, crop=fit
publitio.call('/files/versions/create/mytestfile', 'POST', {
    extension: 'mp4',
    options: 'w_320,h_240,c_fit'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Create a new version from file with ID mytestfile, transcoded to webm
publitio_api.create_version('mytestfile', extension='.webm', ...)

The above command returns JSON structured like this:

{
  "success": true,
  "code": 201,
  "message": "File version created",
  "id": "JR78dfTh",
  "file_id": "RVsbVdyp",
  "extension": "png",
  "options": "h_250,w_250",
  "size": 90711,
  "status": "ready",
  "url": "https://media.publit.io/file/h_250,w_250/RVsbVdyp.png",
  "hits": 0,
  "created_at": "2018-01-10 16:00:19",
  "updated_at": "2018-01-10 16:00:21"
}

This endpoint creates a new file version from the original file. You can use it to transcode your files between formats, for resizing, cropping, watermarking and quality adjustment.

HTTP Request

POST https://api.publit.io/v1/files/versions/create/<file_id>

Query Parameters

Parameter Required Type Description
id yes string Original file ID.
extension yes string File extension (output format) for this version. For the list of supported formats, see below.
options yes string List of options you want to apply to this transformation. For the list of supported options, see below.
cname no string Cname ID. Default is null.

List of extensions (output formats)

With the Publitio API you can easily transcode your files between formats. Supported extensions (output formats) are:

List of options for transformations

Publitio API supports the following image, video and audio manipulations/transformations: resizing, cropping, watermarking, quality adjustment and trimming (video and audio files only). Here is a guide on how to use each of these options:

For resizing, please use w (width) and h (height) parameters. Both w and h accept integer values. For example, w_250 sets the width to exactly 250 pixels. You can resize the file by using both the width and height parameters or with only one of them: the other dimension is automatically updated to maintain the aspect ratio. For example, to resize an image or video to 800x600 pixels, use w_800,h_600

For cropping, please use the c (crop) parameter in combination with w (width) and h (height) parameters. Supported values are c_fit (fit), c_fill (fill) and c_limit (limit).

For watermarking of images and videos, use the wm parameter. For example, to protect your file using a watermark with ID publitio, format your option as wm_publitio. You can also use wm in combination with w, h and c parameters, for example w_800,h_600,c_fill,wm_publitio.

For quality adjustment of images and videos, use the q parameter. This parameter represents the compression level to apply to images or videos as a value between 1 (smallest file size possible) and 100 (best visual quality). For example, to reduce the quality of the file version to 60, use q_60. You can use q in combination with w, h, c and wm as well, for example w_800,h_600,c_fill,wm_publitio,q_60.

To trim videos, use t (time), so (start offset) and eo (end offset) parameters.

For waveform generation of audio files, use the fc (foreground color) and bc (background color) parameters.

The following image adjustment options are supported for image files and video-to-image frame extractions. They can be freely combined with w, h, c, wm, and q:

List Versions

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// List versions of file with id mytestfile
$response = $publitio_api->call('/files/versions/list/mytestfile', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/files/versions/list/mytestfile?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// List versions of file with id mytestfile
publitio.call('/files/versions/list/mytestfile', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.list_versions(file_id, limit=3)

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "limit": 100,
  "offset": 0,
  "versions_total": 2,
  "versions_count": 2,
  "versions": [
    {
      "id": "zoq6qNQy",
      "file_id": "RVsbVdyp",
      "extension": "mp4",
      "options": "",
      "size": 193136,
      "status": "ready",
      "url": "https://media.publit.io/file/RVsbVdyp.mp4",
      "hits": 14,
      "created_at": "2017-11-22 15:48:19",
      "updated_at": "2018-01-08 11:25:54"
    },
    {
      "id": "JR78dfTh",
      "file_id": "RVsbVdyp",
      "extension": "png",
      "options": "h_250,w_250",
      "size": 90711,
      "status": "ready",
      "url": "https://media.publit.io/file/h_250,w_250/RVsbVdyp.png",
      "hits": 0,
      "created_at": "2018-01-10 16:00:19",
      "updated_at": "2018-01-10 16:00:21"
    }
  ]
}

This endpoint lists all versions of a file.

HTTP Request

GET https://api.publit.io/v1/files/versions/list/<file_id>

Query Parameters

Parameter Required Type Description
id yes string Target file ID.
limit no int Maximum number of versions to return. Default is 100. Maximum limit is 1000.
offset no int How many files should be skipped at the beginning of the result set. Default is 0.
order no string How the versions should be ordered. Supported values are date, name, size and hits. You may also append :asc for an ascending sort order or :desc for a descending order (for example name:desc). By default, the versions are sorted by date in ascending order.
filter_status no string Specifies which versions should be returned based on their transformation status. Supported values are all, creating, ready and failed. Default is all.
filter_extension no string Specifies which versions should be returned based on their extension (output format). For the full list see supported extensions. Default is all.
filter_option no string Filter versions by their options/transformation string (e.g. h_360). Default is all.
cname no string Cname ID. Default is null.

Show Version

$publitio_api = new \Publitio\API('<API Key>' '<API Secret>');

// Show file version with id zoq6qNQy
$response = $publitio_api->call("/files/versions/show/zoq6qNQy", "GET");
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/files/versions/show/zoq6qNQy?{{api_signature}}" \
-H "Accept: application/json"
// Download JavaScript SDK from https://github.com/ob1y2k/publitio_js_sdk

// Include SDK
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// show file version with id zoq6qNQy
publitio.call('/files/versions/show/zoq6qNQy', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Show file version with id zoq6qNQy
publitio_api.show_version('zoq6qNQy')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "id": "zoq6qNQy",
  "file_id": "RVsbVdyp",
  "extension": "mp4",
  "options": "",
  "size": 193136,
  "status": "ready",
  "url": "https://media.publit.io/file/RVsbVdyp.mp4",
  "hits": 14,
  "created_at": "2017-11-22 15:48:19",
  "updated_at": "2018-01-08 11:25:54"
}

This endpoint shows version info based on its ID.

HTTP Request

GET https://api.publit.io/v1/files/versions/show/<version_id>

Query Parameters

Parameter Required Type Description
id yes string Target version ID.
cname no string Cname ID. Default is null.

Update Version

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Update file version with ID zoq6qNQy
$response = $publitio_api->call('/files/versions/update/zoq6qNQy', 'PUT');
# Please replace {{api_signature}} with your API signature
curl -X PUT "https://api.publit.io/v1/files/versions/update/zoq6qNQy?{{api_signature}}" \
-H "Accept: application/json" 
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Update file version with ID zoq6qNQy
publitio.call('/files/versions/update/zoq6qNQy', 'PUT')
   .then((data) => { console.log(data) })
   .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Update file version with ID zoq6qNQy
publitio_api.update_version('zoq6qNQy')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The file version with id 'zoq6qNQy' has been updated"
}

This endpoint updates file version info based on its ID.

HTTP Request

PUT https://api.publit.io/v1/files/versions/update/<version_id>

Query Parameters

This call does not support any parameters at this moment.

Reconvert Version

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Update file version with ID zoq6qNQy
$response = $publitio_api->call('/files/versions/reconvert/zoq6qNQy', 'PUT');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/files/versions/reconvert/zoq6qNQy?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Update version with ID zoq6qNQy
publitio.call('/files/versions/reconvert/zoq6qNQy', 'PUT')
   .then((data) => { console.log(data) })
   .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.reconvert_version('zoq6qNQy')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The file version with id 'zoq6qNQy' has been re-converted"
}

This endpoint re-converts a file version based on its ID. Useful for re-creating failed versions.

HTTP Request

PUT https://api.publit.io/v1/files/versions/reconvert/<version_id>

Query Parameters

This call does not support any parameters at this moment.

Delete Version

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Delete file version with ID zoq6qNQy
$response = $publitio_api->call('/files/versions/delete/zoq6qNQy', 'DELETE');
# Please replace {{api_signature}} with your API signature
curl -X DELETE "https://api.publit.io/v1/files/versions/delete/zoq6qNQy?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')

// Delete file version with id zoq6qNQy
publitio.call('/files/versions/delete/zoq6qNQy', 'DELETE')
  .then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
rom publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Delete file version with id zoq6qNQy
publitio_api.delete_version('zoq6qNQy')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The file version with id 'zoq6qNQy' has been deleted!"
}

This endpoint deletes a file version based on its ID.

HTTP Request

DELETE https://api.publit.io/v1/files/versions/delete/<version_id>

Query Parameters

Parameter Required Type Description
id yes string Target version ID.

Folders

The Folders Class allows easy creation and management of a virtual folder structure. Folders are really optional, but you can benefit from their use, as they will become a part of your file URLs and allow you to use unique public_id's for your files.

Create Folder

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Create a new folder, with options name=MyFolder, parent_id=4vZsZBGa
$response = $publitio_api->call(
    '/folders/create', 'POST',
    array(
        'parent_id' => '4vZsZBGa',
        'name' => 'MyFolder'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X POST "https://api.publit.io/v1/folders/create?{{api_signature}}" \
-H "Accept: application/json" \
--data parent_id="4vZsZBGa" \
--data name="MyFolder"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Create a new folder, with options name=MyFolder, parent_id=4vZsZBGa
publitio.call('/folders/create', 'POST', {
    parent_id: '4vZsZBGa',
    name: 'MyFolder'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.create_folder(name='MyFolder', parent_id='4vZsZBGa')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 201,
  "message": "Folder 'Y2K/MyFolder' created",
  "id": "aLLov3Dr",
  "name": "MyFolder",
  "path": "Y2K/MyFolder",
  "parent_id": "4vZsZBGa",
  "created_at": "2019-01-23 10:24:18",
  "updated_at": "2019-01-23 10:24:18"
}

This endpoint creates a new folder.

HTTP Request

POST https://api.publit.io/v1/folders/create

Query Parameters

Parameter Required Type Description
name yes string Unique alphanumeric folder name.
parent_id no string Parent folder ID. Default is null (root folder).

List Folders

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');
$response = $publitio_api->call('/folders/list', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/folders/list?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/folders/list', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.list_folders(order='name')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "parent_id": null,
  "parent_path": "/",
  "folders_count": 2,
  "folders": [
    {
      "id": "4vZsZBGa",
      "name": "Y2K",
      "path": "Y2K",
      "parent_id": null,
      "created_at": "2018-11-27 17:21:23",
      "updated_at": "2018-11-27 17:21:23"
    },
    {
      "id": "kMtns78W",
      "name": "Publitio",
      "path": "Publitio",
      "parent_id": null,
      "created_at": "2018-11-28 21:30:29",
      "updated_at": "2018-11-28 21:30:29"
    }
  ]
}

This endpoint lists folders.

HTTP Request

GET https://api.publit.io/v1/folders/list

Query Parameters

Parameter Required Type Description
parent_id no string Folder ID you wish to retrieve (sub) folders for. Default us null (root folder).
order no string How the folders should be ordered. Supported values are date and name. You may also append :asc for an ascending sort order or :desc for a descending order (for example name:desc). By default, the files are sorted by date in ascending order.
tags no string Search query tags separated by + signs. You can append :any to list folders which have any of the tags, or :all to list only folders which have all of the tags. Default mode is :all. For example, use dogs+cats:any to select files which either have the dogs or the cats tag.

Show Folder

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Show folder with id zoq6qNQy
$response = $publitio_api->call('/folders/show/4vZsZBGa', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/folders/show/4vZsZBGa?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Show folder with id 4vZsZBGa
publitio.call('/folders/show/4vZsZBGa', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Show folder with id 4vZsZBGa
publitio_api.show_folder('4vZsZBGa')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "id": "4vZsZBGa",
  "name": "Y2K",
  "path": "Y2K",
  "parent_id": null,
  "created_at": "2018-11-27 17:21:23",
  "updated_at": "2018-11-27 17:21:23"
}

This endpoint shows folder info based on its ID.

HTTP Request

GET https://api.publit.io/v1/folders/show/<folder_id>

Query Parameters

Parameter Required Type Description
id yes string Target folder ID.

Update Folder

$publitio_api = new \Publitio\API('<API Key>' '<API Secret>');

// Update folder with id 4vZsZBGa
$response = $publitio_api->call('/folders/update/4vZsZBGa', 'PUT');
# Please replace {{api_signature}} with your API signature
curl -X PUT "https://api.publit.io/v1/folders/update/4vZsZBGa?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Update folder with id 4vZsZBGa
publitio.call('/folders/update/4vZsZBGa', 'PUT')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Update folder with id 4vZsZBGa
publitio_api.update_folder('4vZsZBGa')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The folder with id '4vZsZBGa' has been updated"
}

This endpoint updates folder info based on its ID.

HTTP Request

PUT https://api.publit.io/v1/folders/update/<folder_id>

Query Parameters

Parameter Required Type Description
id yes string Target folder ID.
name no string Folder name. This name will become part of contained file paths (case-sensitive).

Delete Folder

$publitio_api = new \Publitio\API('<API Key>' '<API Secret>');

// Delete folder with id 4vZsZBGa
$response = $publitio_api->call('/folders/delete/4vZsZBGa', 'DELETE');
# Please replace {{api_signature}} with your API signature
curl -X DELETE "https://api.publit.io/v1/folders/delete/4vZsZBGa?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Delete folder with id 4vZsZBGa
publitio.call('/folders/delete/4vZsZBGa', 'DELETE')
  .then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Delete folder with id 4vZsZBGa
publitio_api.delete_folder('4vZsZBGa')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The folder with id '4vZsZBGa' has been deleted!"
}

This endpoint deletes a folder based on its ID.

HTTP Request

DELETE https://api.publit.io/v1/folders/delete/<folder_id>

Query Parameters

Parameter Required Type Description
id yes string Target folder ID.

Tree Folder

$publitio_api = new \Publitio\API('<API Key>' '<API Secret>');
$response = $publitio_api->call("/folders/tree", "GET");
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/folders/tree?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/folders/tree', 'GET')
  .then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.folders_tree()

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "folders_count": 2,
  "folders": [
    {
      "id": "4vZsZBGa",
      "name": "Y2K",
      "path": "Y2K"
    },
    {
      "id": "Xdx2p8ix",
      "name": "yo",
      "path": "Y2K/yo"
    }
  ]
}

This endpoint lists the entire folder tree.

HTTP Request

GET https://api.publit.io/v1/folders/tree

Query Parameters

This call does not support any parameters at this moment.

Update Folder Share Settings

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Update share settings for folder with id 4vZsZBGa
$response = $publitio_api->call(
    '/folder/settings/4vZsZBGa',
    'PUT',
    array(
        'enabled' => 'true',
        'theme' => 'dark',
        'infinity_scroll' => 'false'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X PUT "https://api.publit.io/v1/folder/settings/4vZsZBGa?{{api_signature}}" \
-H "Accept: application/json" \
--data enabled="true" \
--data theme="dark" \
--data infinity_scroll="false"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/folder/settings/4vZsZBGa', 'PUT', {
    enabled: 'true',
    theme: 'dark',
    infinity_scroll: 'false'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.call('/folder/settings/4vZsZBGa', 'PUT', {
    'enabled': 'true',
    'theme': 'dark',
    'infinity_scroll': 'false'
})

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "Folder settings saved."
}

This endpoint updates the public sharing settings for a folder. When enabled is set to true, the folder becomes publicly accessible via its share URL.

HTTP Request

PUT https://api.publit.io/v1/folder/settings/<folder_id>

Query Parameters

Parameter Required Type Description
id yes string Target folder ID.
enabled no bool Enable public sharing of the folder. Supported values are true and false. Default is false.
infinity_scroll no bool Enable infinite scroll on the shared folder page. Supported values are true and false. Default is false.
theme no string Visual theme for the shared folder page. Supported values are dark, light and user. Default is user.
password no string Password to protect the shared folder. Minimum 6 characters. Pass an empty string to remove the password. Requires Pro or Business plan.
upload_preset no string Upload preset code to enable anonymous uploads to this folder via its share page.

Get Folder Share URL

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Get share URL for folder with id 4vZsZBGa
$response = $publitio_api->call('/folder/share/4vZsZBGa', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/folder/share/4vZsZBGa?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/folder/share/4vZsZBGa', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.call('/folder/share/4vZsZBGa', 'GET')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "folder": "4vZsZBGa",
  "url": "https://media.publit.io/file/my-folder",
  "enabled": 1,
  "infinity_scroll": 0,
  "password": "",
  "theme": "dark",
  "upload_presets": [],
  "upload_preset": null
}

This endpoint returns the public share URL and current sharing settings for a folder.

HTTP Request

GET https://api.publit.io/v1/folder/share/<folder_id>

Query Parameters

Parameter Required Type Description
id yes string Target folder ID.

Players

Players Class allows easy creation and management of HTML5 Media Players that you can use to play/preview your files and versions.

Create Player

$publitio_api = new \Publitio\API('<API Key>' '<API Secret>');

// Create player with id myplayer
$response = $publitio_api->call(
    '/players/create', 'POST',
    array(
        'name' => 'myplayer',
        'auto_play' => '0',
        'skin' => 'blue'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X POST "https://api.publit.io/v1/players/create?{{api_signature}}" \
-H "Accept: application/json" \
--data name="myplayer" \
--data auto_play="0" \
--data skin="blue"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Create player with id myplayer
publitio.call('/players/create', 'POST', {
    name: 'myplayer',
    auto_play: '0',
    skin: 'blue'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Create player with id myplayer
publitio_api.create_player(name='myplayer')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 201,
  "message": "Player with name (id) 'myplayer' created",
  "id": "myplayer",
  "auto_play": 0,
  "skin": "blue",
  "controls": "on",
  "quality": "480p",
  "thumbnails": "on",
  "muted": "off",
  "adtag_id": "",
  "created_at": "2018-01-10 14:56:52",
  "updated_at": "2018-01-10 14:56:52"
}

This endpoint creates a new HTML5 Media Player.

Player setup will affect both embed_url, source_html, iframe_html and player_html once passed to the File Player call.

HTTP Request

POST https://api.publit.io/v1/players/create

Query Parameters

Parameter Required Type Description
name yes string Unique alphanumeric player name (ID).
auto_play no int Auto-play content. Supported values are 0 (off), 1 (on) and 2 (onmouseover).
skin no string Player skin color. Valid values are blue, pink, green, grey, orange and inverted. Default is grey.
controls no boolean Controlbar visibility. Valid values are 0, 1, true and false. Default is 1 (true).
quality no int Default video quality. Valid values are 0 (360p), 1 (480p), 2 (720p), 3 (1080p), 4 (1440p) and 5 (2160p). Default is 1 (480p).
thumbnails no boolean Thumbnails preview on seekbar. Valid values are: 0, 1, true and false. Default is 1 (true).
muted no boolean Player is initially muted. This can be useful with auto-play videos. Valid values are: 0, 1, true and false. Default is 0 (false).
adtag_id no string ID of adtag to use with this player.
color no string Custom player accent color in hex format (e.g. #ff0000).
sizeing no string Player sizing mode. Valid values: fluid, fill, fixed. Default is fluid.
width no int Player width in pixels (100–10000). Only applicable when sizeing is fixed.
height no int Player height in pixels (100–10000). Only applicable when sizeing is fixed.
loop_video no boolean Loop video playback. Valid values: 0, 1, true, false. Default is 0 (false).
playback_speed no boolean Show playback speed controls. Valid values: 0, 1, true, false. Default is 0 (false).
seek_buttons no boolean Show seek +/- buttons. Valid values: 0, 1, true, false. Default is 0 (false).
player_default no boolean Set as default player for the account. Valid values: 0, 1, true, false. Default is 0 (false).
download no boolean Show download button in player. Valid values: 0, 1, true, false. Default is 0 (false).
resume_playback no boolean Resume video from last position on re-play. Valid values: 0, 1, true, false. Default is 0 (false).
custom_css no string Custom CSS string to inject into the player.
up_next no int Up-next video behavior. Valid values: 0 (off), 1 (next video in folder), 2 (previous video in folder), 3 (random video in folder). Default is 0.

List Players

$publitio_api = new \Publitio\API('<API Key>' '<API Secret>');
$response = $publitio_api->call('/players/list', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/players/list?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/players/list', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.list_players()

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "players_count": 2,
  "players": [
    {
      "id": "myplayer",
      "auto_play": 0,
      "skin": "blue",
      "controls": "on",
      "quality": "480p",
      "thumbnails": "on",
      "muted": "off",
      "adtag_id": "",
      "created_at": "2017-11-29 17:50:36",
      "updated_at": "2017-11-29 17:50:36"
    },
    {
      "id": "publitio",
      "auto_play": 1,
      "skin": "grey",
      "controls": "on",
      "quality": "720p",
      "thumbnails": "on",
      "muted": "off",
      "adtag_id": "preroll",
      "created_at": "2017-12-19 10:26:15",
      "updated_at": "2017-12-19 10:26:15"
    }
  ]
}

This endpoint returns a list of all created players.

HTTP Request

GET https://api.publit.io/v1/players/list

Query Parameters

Parameter Required Type Description
limit no int Number of players to return. Default is 100, max 1000.
offset no int Number of players to skip. Default is 0.
order no string Sort order. Supported values: date, date:asc, date:desc, name, name:asc, name:desc. Default is date:desc.

Show Player

$publitio_api = \Publitio\API('<API Key>', '<API Secret>')
// Show player with id myplayer
$response = $publitio_api->call('/players/show/myplayer', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/players/show/myplayer?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Show player with id myplayer
publitio.call('/players/show/myplayer', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Show player with id myplayer
publitio_api.show_player('myplayer')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "id": "myplayer",
  "auto_play": 0,
  "skin": "blue",
  "controls": "on",
  "quality": "720p",
  "thumbnails": "on",
  "muted": "off",            
  "adtag_id": "",
  "created_at": "2018-01-10 14:56:52",
  "updated_at": "2018-01-10 14:56:52"
}

This endpoint shows player info based on its ID.

HTTP Request

GET https://api.publit.io/v1/players/show/<player_id>

Query Parameters

Parameter Required Type Description
id yes string Target player ID.

Update Player

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Update player with id mytestwm
$response = $publitio_api->call(
    '/players/update/myplayer',
    'PUT',
    array(
        'auto_play' => '2',
        'skin' => 'orange',
        'adtag_id' => 'myadtag'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X PUT "https://api.publit.io/v1/players/update/myplayer?{{api_signature}}" \
-H "Accept: application/json" \
--data auto_play="2" \
--data skin="orange" \
--data adtag_id="myadtag"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Update player with id myplayer
publitio.call('/players/update/myplayer', 'PUT', {
    adtag_id: 'mypreroll',
    auto_play: '1'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
# Update player with id myplayer
publitio_api.update_player('myplayer', skin='green')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The player with name (id) 'myplayer' has been updated"
}

This endpoint updates player info based on its ID.

Player setup will affect both embed_url, source_html, iframe_html and player_html once passed to the File Player call.

HTTP Request

PUT https://api.publit.io/v1/players/update/<player_id>

Query Parameters

Parameter Required Type Description
id yes string Target player ID.
auto_play no int Auto-play content. Supported values are 0 (off), 1 (on) and 2 (onmouseover).
skin no string Player skin color. Valid values are blue, pink, green, grey, orange and inverted. Default is grey.
controls no boolean Controlbar visibility. Valid values are 0, 1, true and false. Default is 1 (true).
quality no int Default video quality. Valid values are 0 (360p), 1 (480p), 2 (720p), 3 (1080p), 4 (1440p) and 5 (2160p). Default is 1 (480p).
thumbnails no boolean Thumbnails preview on seekbar. Valid values are 0, 1, true and false. Default is 1 (true).
muted no boolean Player is initially muted. This can be useful with auto-play videos. Valid values are: 0, 1, true and false. Default is 0 (false).
adtag_id no string ID of adtag to use with this player.
color no string Custom player accent color in hex format (e.g. #ff0000).
sizeing no string Player sizing mode. Valid values: fluid, fill, fixed. Default is fluid.
width no int Player width in pixels (100–10000). Only applicable when sizeing is fixed.
height no int Player height in pixels (100–10000). Only applicable when sizeing is fixed.
loop_video no boolean Loop video playback. Valid values: 0, 1, true, false. Default is 0 (false).
playback_speed no boolean Show playback speed controls. Valid values: 0, 1, true, false. Default is 0 (false).
seek_buttons no boolean Show seek +/- buttons. Valid values: 0, 1, true, false. Default is 0 (false).
player_default no boolean Set as default player for the account. Valid values: 0, 1, true, false. Default is 0 (false).
download no boolean Show download button in player. Valid values: 0, 1, true, false. Default is 0 (false).
resume_playback no boolean Resume video from last position on re-play. Valid values: 0, 1, true, false. Default is 0 (false).
custom_css no string Custom CSS string to inject into the player.
up_next no int Up-next video behavior. Valid values: 0 (off), 1 (next video in folder), 2 (previous video in folder), 3 (random video in folder). Default is 0.

Delete Player

$publitio_api = new \Publitio\API('<API Key>' '<API Secret>');

// Delete player with id myplayer
$response = $publitio_api->call('/players/delete/myplayer', 'DELETE');
# Please replace {{api_signature}} with your API signature
curl -X DELETE "https://api.publit.io/v1/players/delete/myplayer?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Delete player with id myplayer
publitio.call('/players/delete/myplayer', 'DELETE')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Delete player with id myplayer
publitio_api.delete_player('myplayer')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The player with name (id) 'myplayer' has been deleted!"
}

This endpoint deletes a player based on its ID.

HTTP Request

DELETE https://api.publit.io/v1/players/delete/<player_id>

Query Parameters

Parameter Required Type Description
id yes string Target player ID.

Adtags

Adtags Class (Sub-class of Players) allows easy creation and management of VAST/IMA ad tags that you can use with your players to monetize your files and versions with ads.

Create Adtag

$publitio_api = new \Publitio\API('<API Key>' '<API Secret>');

// Create adtag with name (id) myadtag
$response = $publitio_api->call(
    '/players/adtag/create',
    'POST',
    array(
        'name' => 'myadtag',
        'tag' => 'https://pubads.g.doubleclick.net/gampad/ads?sz=480x70&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dnonlinear&correlator='
    )
);
# Please replace {{api_signature}} with your API signature
curl -X POST "https://api.publit.io/v1/players/create?{{api_signature}}" \
-H "Accept: application/json" \
--data name="myadtag" \
--data tag="https://pubads.g.doubleclick.net/gampad/ads?sz=480x70&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dnonlinear&correlator="
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Create adtag with id myadtag
publitio.call(
    '/players/adtags/create',
    'POST', {
        name: 'myadtag',
        tag: 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator='
    }
).then((data) => { console.log(data) })
 .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Create adtag with id myadtag
publitio_api.create_adtag(name='myadtag', tag='https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator=')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 201,
  "message": "Adtag with name (id) 'myadtag' created",
  "id": "myadtag",
  "tag": "https://pubads.g.doubleclick.net/gampad/ads?sz=480x70&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dnonlinear&correlator=",
  "created_at": "2018-01-10 15:26:01",
  "updated_at": "2018-01-10 15:26:01"
}

This endpoint creates a new VAST/IMA ad tag that you can later use with your players to monetize your files and versions with ads. You can get sample tags for testing at Google IMA Sample Tags.

HTTP Request

POST https://api.publit.io/v1/players/adtags/create

Query Parameters

Parameter Required Type Description
name yes string Unique alphanumeric adtag name (ID).
tag yes string Tag URL you wish to use. The Publitio Player supports VAST & Google IMA ad tags at the moment.

List Adtags

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');
$response = $publitio_api->call('/players/adtags/list', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/players/adtags/list?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/players/adtags/list', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.list_adtags()

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "adtags_count": 2,
  "adtags": [
    {
      "id": "preroll",
      "tag": "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator=",
      "created_at": "2017-12-19 10:23:51",
      "updated_at": "2017-12-19 10:23:51"
    },
    {
      "id": "myadtag",
      "tag": "https://pubads.g.doubleclick.net/gampad/ads?sz=480x70&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dnonlinear&correlator=",
      "created_at": "2018-01-10 15:26:01",
      "updated_at": "2018-01-10 15:26:01"
    }
  ]
}

This endpoint returns a list of all created adtags.

HTTP Request

GET https://api.publit.io/v1/players/adtags/list

Query Parameters

This call does not support any parameters at this moment.

Show Adtag

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Show adtag with id myadtag
$response = $publitio_api->call('/players/adtags/show/myadtag', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/players/adtags/show/myadtag?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Show adtag with id myadtag
publitio.call('/players/adtags/show/myadtag', 'GET')
   .then((data) => { console.log(data) })
   .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Show adtag with id myadtag
publitio_api.show_adtag('myadtag')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "id": "myadtag",
  "tag": "https://pubads.g.doubleclick.net/gampad/ads?sz=480x70&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dnonlinear&correlator=",
  "created_at": "2018-01-10 15:26:01",
  "updated_at": "2018-01-10 15:26:01"
}

This endpoint shows adtag info based on its ID.

HTTP Request

GET https://api.publit.io/v1/players/adtags/show/<adtag_id>

Query Parameters

Parameter Required Type Description
id yes string Target adtag ID.

Update Adtag

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Update adtag with id myadtag
$response = $publitio_api->call(
    '/players/adtags/update/myadtag',
    'PUT',
    array(
        'tag' => 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator='
    )
);
# Please replace {{api_signature}} with your API signature
curl -X PUT "https://api.publit.io/v1/players/adtags/update/myadtag?{{api_signature}}" \
-H "Accept: application/json" \
--data tag="https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator="
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Update adtag with id myadtag
publitio.call('/players/adtags/update/myadtag', 'PUT', {
    tag: 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_parameters=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator='
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Update adtag with id myadtag
publitio_api.update_adtag(adtag_id, tag='myadtag')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The adtag with name (id) 'myadtag' has been updated"
}

This endpoint updates adtag info based on its ID.

HTTP Request

PUT https://api.publit.io/v1/players/adtags/update/<adtag_id>

Query Parameters

Parameter Required Type Description
id yes string Unique alphanumeric adtag name (ID).
tag no string Tag URL you wish to use. The Publitio Player supports VAST and Google IMA ad tags at the moment.

Delete Adtag

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Delete adtag with id myadtag
$response = $publitio_api->call('/players/adtags/delete/myadtag', 'DELETE');
# Please replace {{api_signature}} with your API signature
curl -X DELETE "https://api.publit.io/v1/players/adtags/delete/myadtag?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Delete adtag with id myadtag
publitio.call('/players/adtags/delete/myadtag', 'DELETE')
   .then((data) => { console.log(data) })
   .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Delete adtag with id myadtag
publitio_api.delete_adtag('myadtag')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The adtag with name (id) 'myadtag' has been deleted!"
}

This endpoint deletes an adtag based on its ID.

HTTP Request

DELETE https://api.publit.io/v1/players/adtags/delete/<adtag_id>

Query Parameters

Parameter Required Type Description
id yes string Target adtag id (name).

Watermarks

The Watermarks Class allows easy creation and management of watermarks that you can use to protect/copyright your uploaded files and versions.

Watermarks are used via URL-based transformations. To watermark a file or version, pass the wm option:

https://media.publit.io/file/wm_publitio/butterflies.jpg

You can learn more about applying watermarks here.

Create Watermark

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Create watermark from local file
$response = $publitio_api->upload_file(
    fopen('samples/smile.png'),
    'watermark',
    array(
        'name' => 'mytestwm',
        'position' => 'top-right',
        'padding' => '20'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X POST "https://api.publit.io/v1/watermarks/create?{{api_signature}}" \
-H "Accept: application/json" \
--form name=mytestwm \
--form position=top-right \
--form padding=20 \
--form file=@/localpathtoimage/watermark.png
import PublitioAPI from 'publitio_js_sdk'
import { readFileSync } from 'fs'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// This could also be a ReadableStream in Node, a File in the browser or a string
const file = readFileSync('watermark.png')

// Create watermark from local file
publitio.uploadFile(file, 'watermark', {
    name: 'mytestwm',
    position: 'top-right',
    padding: '20'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.create_watermark(self, file=open('path/to/file', rb), title='whatever')
# The file needs to be opened for binary reading. This function will not close the file.

The above command returns JSON structured like this:

{
  "success": true,
  "code": 201,
  "message": "Watermark created",
  "id": "mytestwm",
  "extension": "png",
  "width": 100,
  "height": 100,
  "size": 3198,
  "position": "top-right",
  "padding": 20,
  "url": "https://media.publit.io/watermark/c74i.png",
  "created_at": "2018-01-10 12:21:32",
  "updated_at": "2018-01-10 12:21:32"
}

This endpoint creates a new watermark that you can later use on files and versions in order to protect your images and videos. Right now you can upload png or jpg images as your watermarks and Publitio will securely store them for future use.

HTTP Request

POST https://api.publit.io/v1/watermarks/create

Query Parameters

Parameter Required Type Description
file yes file Image to upload as watermark (png and jpg images currently supported).
name yes string Unique alphanumeric name (ID) of watermark.
position no string Position of watermark, valid values are center, top-left, top, top-right, left, right, bottom-left, bottom, bottom-right. Default is bottom-right.
padding no int Padding in pixels (ignored when position is center). Default is 0.

List Watermarks

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');
$response = $publitio_api->call("/watermarks/list", "GET");
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/watermarks/list?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/watermarks/list', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.list_watermarks()

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "watermarks_count": 2,
  "watermarks": [
    {
      "id": "publitio",
      "extension": "png",
      "width": 150,
      "height": 49,
      "size": 3388,
      "position": "top-right",
      "padding": 10,
      "url": "https://media.publit.io/watermark/69ty.png",
      "created_at": "2017-11-29 16:49:26",
      "updated_at": "2017-11-29 16:49:26"
    },
    {
      "id": "mytestwm",
      "extension": "png",
      "width": 100,
      "height": 100,
      "size": 3198,
      "position": "top-right",
      "padding": 20,
      "url": "https://media.publit.io/watermark/c74i.png",
      "created_at": "2018-01-10 12:21:32",
      "updated_at": "2018-01-10 12:21:32"
    }
  ]
}

This endpoint returns a list of all created watermarks.

HTTP Request

GET https://api.publit.io/v1/watermarks/list

Query Parameters

Parameter Required Type Description
offset no int Number of results to skip. Default is 0.
limit no int Maximum number of results to return. Default is 10.
order no string Sort order in the format field:direction (e.g. date:desc). Default is date:desc.

Show Watermark

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Show watermark with id mytestwm
$response = $publitio_api->call('/watermarks/show/mytestwm', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/watermarks/show/mytestwm?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Show watermark with id mytestwm
publitio.call('/watermarks/show/mytestwm', 'GET')
   .then((data) => { console.log(data) })
   .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Show watermark with id mytestwm
publitio_api.show_watermark('mytestwm')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "id": "mytestwm",
  "extension": "png",
  "width": 100,
  "height": 100,
  "size": 3056,
  "position": "top-right",
  "padding": 20,
  "url": "https://media.publit.io/watermark/c74i.png",
  "created_at": "2018-01-10 13:04:45",
  "updated_at": "2018-01-10 13:04:45"
}

This endpoint shows watermark info based on its ID.

HTTP Request

GET https://api.publit.io/v1/watermarks/show/<watermark_id>

Query Parameters

Parameter Required Type Description
id yes string Target watermark ID (name).

Update Watermark

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Update watermark with id mytestwm
$response = $publitio_api->call(
    '/watermarks/update/mytestwm',
    'PUT',
    array(
        'position' => 'top-left',
        'padding' => '10'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X PUT "https://api.publit.io/v1/watermarks/update/mytestwm?{{api_signature}}" \
-H "Accept: application/json" \
--data padding="25" \
--data position="top-left"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Update watermark with id mytestwm
publitio.call('/watermarks/update/mytestwm', 'PUT', {
   position: 'bottom-right',
   padding: '10'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })

from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Update watermark with id mytestwm
publitio_api.update_watermark('mytestwm', position='left')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The watermark with name (id) 'mytestwm' has been updated"
}

This endpoint updates watermark info based on its ID.

HTTP Request

PUT https://api.publit.io/v1/watermarks/update/<watermark_id>

Query Parameters

Parameter Required Type Description
id yes string Target watermark ID.
position no string Watermark position, valid values are center, top-left, top, top-right, left, right, bottom-left, bottom, bottom-right. Default is bottom-right.
padding no int Padding in pixels (ignored if position is center). Default is 0.

Delete Watermark

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Delete watermark with id mytestwm
$response = $publitio_api->call('/watermarks/delete/mytestwm', 'DELETE');
# Please replace {{api_signature}} with your API signature
curl -X DELETE "https://api.publit.io/v1/watermarks/delete/mytestwm?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Delete watermark with id mytestwm
publitio.call('/watermarks/delete/mytestwm', 'DELETE')
   .then((data) => { console.log(data) })
   .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Delete watermark with id mytestwm
publitio_api.delete_watermark('mytestwm')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The watermark with name (id) 'mytestwm' has been deleted!"
}

This endpoint deletes a watermark based on its ID.

HTTP Request

DELETE https://api.publit.io/v1/watermarks/delete/<watermark_id>

Query Parameters

Parameter Required Type Description
id yes string Target watermark ID.

CNAMEs

The CNAMEs API allows you to manage custom domain names for media delivery. Instead of serving files from media.publit.io, you can use your own domain (e.g. media.yourdomain.com) by setting up a CNAME DNS record pointing to media.publit.io and registering it here.

Once a CNAME is verified and SSL is active, you can set it as the default delivery domain for your account. All file URLs returned by the API will then automatically use your custom domain.

Create CNAME

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Create a new CNAME
$response = $publitio_api->call(
    '/cnames/create',
    'POST',
    array(
        'name' => 'mycdn',
        'url'  => 'media.yourdomain.com'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X POST "https://api.publit.io/v1/cnames/create?{{api_signature}}" \
-H "Accept: application/json" \
--data name="mycdn" \
--data url="media.yourdomain.com"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/cnames/create', 'POST', {
    name: 'mycdn',
    url: 'media.yourdomain.com'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.call('/cnames/create', 'POST', {
    'name': 'mycdn',
    'url': 'media.yourdomain.com'
})

The above command returns JSON structured like this:

{
  "success": true,
  "code": 201,
  "message": "Cname created",
  "id": "mycdn",
  "url": "http://media.yourdomain.com",
  "dns_verified": false,
  "ssl_cert": "disabled",
  "default": 0,
  "expires_at": "2026-04-06 12:00:00",
  "created_at": "2025-04-06 12:00:00",
  "updated_at": "2025-04-06 12:00:00"
}

This endpoint registers a new custom domain. Before calling this endpoint, create a CNAME DNS record at your domain registrar pointing to media.publit.io. The API will immediately attempt to verify the DNS record. SSL is provisioned automatically once DNS is verified.

HTTP Request

POST https://api.publit.io/v1/cnames/create

Query Parameters

Parameter Required Type Description
name yes string Unique alphanumeric identifier for this CNAME (max 12 characters, letters and numbers only). This becomes the CNAME ID used in all subsequent API calls.
url yes string Your custom domain (e.g. media.yourdomain.com). Protocol prefix and www. are stripped automatically.

List CNAMEs

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');
$response = $publitio_api->call('/cnames/list', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/cnames/list?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/cnames/list', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.call('/cnames/list', 'GET')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "cnames_count": 1,
  "cnames": [
    {
      "id": "mycdn",
      "url": "https://media.yourdomain.com",
      "dns_verified": true,
      "ssl_cert": "working",
      "default": 1,
      "expires_at": "2026-04-06 12:00:00",
      "created_at": "2025-04-06 12:00:00",
      "updated_at": "2025-04-06 12:00:00"
    }
  ]
}

This endpoint returns a list of all registered CNAMEs for your account.

HTTP Request

GET https://api.publit.io/v1/cnames/list

Query Parameters

This call does not support any parameters at this moment.

Show CNAME

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Show CNAME with id mycdn
$response = $publitio_api->call('/cnames/show/mycdn', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/cnames/show/mycdn?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Show CNAME with id mycdn
publitio.call('/cnames/show/mycdn', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Show CNAME with id mycdn
publitio_api.call('/cnames/show/mycdn', 'GET')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "id": "mycdn",
  "url": "https://media.yourdomain.com",
  "dns_verified": true,
  "ssl_cert": "working",
  "default": 1,
  "expires_at": "2026-04-06 12:00:00",
  "created_at": "2025-04-06 12:00:00",
  "updated_at": "2025-04-06 12:00:00"
}

This endpoint returns details for a single CNAME. The ssl_cert field reflects the current SSL status: disabled (no SSL), waiting (DNS verified, SSL pending), working (SSL active), or bad (SSL error).

HTTP Request

GET https://api.publit.io/v1/cnames/show/<cname_id>

Query Parameters

Parameter Required Type Description
id yes string Target CNAME ID (the name used when creating it).

Update CNAME

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Set mycdn as the default delivery domain
$response = $publitio_api->call(
    '/cnames/update/mycdn',
    'PUT',
    array('default' => 1)
);
# Please replace {{api_signature}} with your API signature
curl -X PUT "https://api.publit.io/v1/cnames/update/mycdn?{{api_signature}}" \
-H "Accept: application/json" \
--data default=1
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Set mycdn as the default delivery domain
publitio.call('/cnames/update/mycdn', 'PUT', {
    default: 1
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Set mycdn as the default delivery domain
publitio_api.call('/cnames/update/mycdn', 'PUT', {
    'default': 1
})

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The cname with id 'mycdn' has been updated"
}

This endpoint updates a CNAME. Setting default to 1 makes this CNAME the active delivery domain — all other CNAMEs on the account are automatically unset as default.

HTTP Request

PUT https://api.publit.io/v1/cnames/update/<cname_id>

Query Parameters

Parameter Required Type Description
id yes string Target CNAME ID.
default no int Set this CNAME as the default delivery domain. Pass 1 to enable, 0 to disable. When set to 1, all other CNAMEs on the account are automatically unset.

Delete CNAME

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Delete CNAME with id mycdn
$response = $publitio_api->call('/cnames/delete/mycdn', 'DELETE');
# Please replace {{api_signature}} with your API signature
curl -X DELETE "https://api.publit.io/v1/cnames/delete/mycdn?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
// Delete CNAME with id mycdn
publitio.call('/cnames/delete/mycdn', 'DELETE')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
# Delete CNAME with id mycdn
publitio_api.call('/cnames/delete/mycdn', 'DELETE')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "message": "The cname with id 'mycdn' has been deleted!"
}

This endpoint permanently removes a CNAME from your account. The SSL certificate is revoked and the custom domain will no longer serve your files.

HTTP Request

DELETE https://api.publit.io/v1/cnames/delete/<cname_id>

Query Parameters

Parameter Required Type Description
id yes string Target CNAME ID.

Stats

The Stats endpoints allow you to retrieve analytics and engagement data for your media files, including play counts, bandwidth usage, and geographic breakdowns.

Show File Stats

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Get video play stats for file with id MvHX8Zx5
$response = $publitio_api->call('/stats/show/MvHX8Zx5', 'GET');
# Please replace {{api_signature}} with your API signature
curl -X GET "https://api.publit.io/v1/stats/show/MvHX8Zx5?{{api_signature}}" \
-H "Accept: application/json"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/stats/show/MvHX8Zx5', 'GET')
    .then((data) => { console.log(data) })
    .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.call('/stats/show/MvHX8Zx5', 'GET')

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "file_id": "MvHX8Zx5",
  "unique_plays": 142,
  "total_plays": 198,
  "average_percent": 74.3,
  "average_time": 87,
  "duration": 117,
  "timestamps": {
    "0": 198,
    "1": 195,
    "60": 156,
    "117": 41
  },
  "human_timestamps": {
    "0:00": { "views": 198, "percent": 100 },
    "1:00": { "views": 156, "percent": 78 },
    "1:57": { "views": 41, "percent": 20 }
  }
}

This endpoint returns video engagement analytics for a single video file: unique and total play counts, average watched percentage and time, video duration, and a per-second timestamp heatmap showing where viewers watched. Results are cached for 1 hour.

HTTP Request

GET https://api.publit.io/v1/stats/show/<file_id>

Query Parameters

Parameter Required Type Description
id yes string Target video file ID.

Show Multiple Files Stats

$publitio_api = new \Publitio\API('<API Key>', '<API Secret>');

// Get stats for multiple files over a date range
$response = $publitio_api->call(
    '/stats/show-multiple',
    'POST',
    array(
        'file_codes' => 'MvHX8Zx5,AbCdEfGh',
        'from' => '2024-01-01',
        'to' => '2024-01-31'
    )
);
# Please replace {{api_signature}} with your API signature
curl -X POST "https://api.publit.io/v1/stats/show-multiple?{{api_signature}}" \
-H "Accept: application/json" \
--data file_codes="MvHX8Zx5,AbCdEfGh" \
--data from="2024-01-01" \
--data to="2024-01-31"
import PublitioAPI from 'publitio_js_sdk'

const publitio = new PublitioAPI('<API Key>', '<API Secret>')
publitio.call('/stats/show-multiple', 'POST', {
    file_codes: 'MvHX8Zx5,AbCdEfGh',
    from: '2024-01-01',
    to: '2024-01-31'
}).then((data) => { console.log(data) })
  .catch((error) => { console.log(error) })
from publitio import PublitioAPI

publitio_api = PublitioAPI('<API Key>', '<API Secret>')
publitio_api.call('/stats/show-multiple', 'POST', {
    'file_codes': 'MvHX8Zx5,AbCdEfGh',
    'from': '2024-01-01',
    'to': '2024-01-31'
})

The above command returns JSON structured like this:

{
  "success": true,
  "code": 200,
  "range": {
    "from": "2024-01-01",
    "to": "2024-01-31"
  },
  "output": [
    {
      "success": true,
      "code": 200,
      "file_code": "MvHX8Zx5",
      "hits": 1450,
      "requests": 312,
      "bandwidth": "2.4 GB",
      "top_referers": [],
      "top_countries": [],
      "top_browsers": [],
      "top_systems": [],
      "average_percent": 68.5,
      "average_time": 80,
      "duration": 117,
      "unique_plays": 98,
      "total_plays": 131
    }
  ]
}

This endpoint returns analytics for up to 20 files over a specified date range. For each file it returns total hits, request count, bandwidth consumed, and top referers, countries, browsers, and operating systems. Video files additionally include play engagement metrics. Results are cached for 30 minutes.

HTTP Request

POST https://api.publit.io/v1/stats/show-multiple

Query Parameters

Parameter Required Type Description
file_codes yes string Comma-separated list of file IDs. Maximum 20 codes.
from yes string Start date for the range in YYYY-MM-DD format. Required.
to yes string End date for the range in YYYY-MM-DD format. Required.
days no int Shorthand for a relative date range — overrides from and to with the last N days when all three are provided.

Errors

Most errors returned by the API have the following form:

[
  {
    "success": false,
    "code": 404,
    "error": {
        "message": "The file with id 'RVsbVdyzp' doesn't exist"
    }
  }
]

The Publitio API might respond with the following HTTP response codes:

Error Code Meaning
400 Bad Request — Your request is invalid.
401 Unauthorized — Your API Signature is invalid.
403 Forbidden — The requested resource is private.
404 Not Found — The requested resource could not be found.
405 Method Not Allowed — You tried to access an endpoint using an invalid method.
406 Not Acceptable — You requested a format that isn't JSON.
410 Gone — The requested resource has been removed from our servers.
422 Unprocessable Entity — Unable to process the contained instructions.
429 Too Many Requests — You're making too many requests! Slow down!
500 Internal Server Error — We had a problem with our servers. Please try again later.
503 Service Unavailable — Resource or service temporarily unavailable. Please try again later.
sh php JS python