Getting Started

The Empower API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors and all POST data must also be in JSON format.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

All responses are returned within the data property of an object which consists of the following properties:

  • status: The HTTP response code returned for the request.
  • data: The response payload for the request that can either be null, an object or an array, depending on the type of the endpoint and the request.
  • errors: The list of errors occured while processing the request, as an array. This property is always returned and may co-exist with a non-null data property, as there might be cases where it's useful to warn the requester where it is still possible to respond.

https://api.empower.net

Authentication

Authenticate your account when using the API by passing your API key with the Authorization header in the request. Your API key carries many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

You may also use the access_token query parameter, if that's more convenient for you. Same rules apply.

curl https://api.empower.net/v1/videos \
   -H "Authorization: Bearer ff2ae22a58046fb5f6319bbaa0b1603595273f79ddc5f9bfd8ede8379aa86ee3"
curl https://api.empower.net/v1/videos?access_token=ff2ae22a58046fb5f6319bbaa0b1603595273f79ddc5f9bfd8ede8379aa86ee3

Errors

We use conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided, and codes in the 5xx range indicate an error with our servers (these are rare).

As explained above in the Getting Started section, responses also contain the HTTP response code, together with a list of errors occured, if any.

Attributes
  • type

    The type of error returned. Can be: A1000, A1001, E1000, or I1000.

  • message optional

    A human-readable message providing more details about the error.

HTTP status code summary

200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
402 - Request Failed The parameters were valid but the request failed.
404 - Not Found The requested resource doesn't exist.
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors Something went wrong on our end. (These are rare.)

Errors

Types
A1000 Failure to properly authenticate yourself in the request.
A1001 You do not have the permission to perform this action.
E1000 An unidentified error occured.
I1000 Your request was invalid due to invalid parameters.

Video

This is an object representing your video. You can retrieve it to see the details of your video.

Video Object

Attributes
  • id integer

    Unique identifier of the video.

  • title string

    The title provided for the video.

  • description string

    The description provided for the video.

  • createdAt string

    Date of creation of the video object, in ISO-8601 format.

  • duration integer

    The length of the video in milliseconds.

  • embed object

    Available embedding methods for the video. Use the URL provided with the url property to embed on your site.

  • status string

    Current status of the video. Possible values are: deleted, error, notfound, processing, available.

  • thumbnails object

    Thumbnails of the video in various resolutions.

  • views integer

    Number of times the video has been watched.

                                {
  "id": 30172857,
  "title": "Sample Video",
  "description": "A sample video description.",
  "createdAt": "2017-12-21T14:29:00+03:00",
  "duration": 1337000,
  "embed": {
    "url": "https://www.izlesene.com/embed/npm/ornek/30172857"
  },
  "status": "available",
  "thumbnails": {
    "small": "https://i1.imgiz.com/rshots/30172/ornek-video_30172857-54010_320x180.jpg",
    "medium": "https://i1.imgiz.com/rshots/30172/ornek-video_30172857-54010_640x360.jpg",
    "large": "https://i1.imgiz.com/rshots/30172/ornek-video_30172857-54010_1280x720.jpg"
  },
  "views": 238801
}
                            

List All Your Videos

You may fetch all your videos using the GET /v1/videos endpoint, in a reverse-chronological order.

The query parameters you may use are explained below:

Query Parameters
  • after optional integer

    The last video id you fetched, to retrieve the items listed afterwards when using pagination.

  • limit optional default is 10 integer

    The number of videos to return. The maximum value allowed is 100.

  • thumbnails optional string

    Comma-separated list of thumbnail resolutions to return in addition to the default sizes. These are nested under the custom property of thumbnails within the video object. Ex: 320x180,480x270

GET https://api.empower.net/v1/videos?access_token=ff2ae22a58046fb5f6319bbaa0b1603595273f79ddc5f9bfd8ede8379aa86ee3
                                {
  "status": 200,
  "data": [
    {
      "id": 30172857,
      "title": "Sample Video",
      "description": "A sample video description.",
      "createdAt": "2017-12-21T14:29:00+03:00",
      "duration": 1337000,
      "embed": {
        "url": "https://www.izlesene.com/embed/npm/ornek/30172857"
      },
      "status": "available",
      "thumbnails": {
        "small": "https://i1.imgiz.com/rshots/30172/ornek-video_30172857-54010_320x180.jpg",
        "medium": "https://i1.imgiz.com/rshots/30172/ornek-video_30172857-54010_640x360.jpg",
        "large": "https://i1.imgiz.com/rshots/30172/ornek-video_30172857-54010_1280x720.jpg"
      },
      "views": 238801
    },
    ...
  ],
  "errors": [
  ]
}
                            

Fetch a Single Video

You may also fetch a single video using the GET /v1/videos/:videoid endpoint, where :videoid is the unique identifier of the video.

The query parameters you may use are explained below:

Query Parameters
  • thumbnails optional string

    Comma-separated list of thumbnail resolutions to return in addition to the default sizes. These are nested under the custom property of thumbnails within the video object. Ex: 320x180,480x270

GET https://api.empower.net/v1/videos/30172857?access_token=ff2ae22a58046fb5f6319bbaa0b1603595273f79ddc5f9bfd8ede8379aa86ee3
                                {
  "status": 200,
  "data": {
    "id": 30172857,
    "title": "Sample Video",
    "description": "A sample video description.",
    "createdAt": "2017-12-21T14:29:00+03:00",
    "duration": 1337000,
    "embed": {
      "url": "https://www.izlesene.com/embed/npm/ornek/30172857"
    },
    "status": "available",
    "thumbnails": {
      "small": "https://i1.imgiz.com/rshots/30172/ornek-video_30172857-54010_320x180.jpg",
      "medium": "https://i1.imgiz.com/rshots/30172/ornek-video_30172857-54010_640x360.jpg",
      "large": "https://i1.imgiz.com/rshots/30172/ornek-video_30172857-54010_1280x720.jpg"
    },
    "views": 238801
  },
  "errors": [
  ]
}
                            

Update Video Details

You may update the details of the video using the POST /v1/videos/:videoid endpoint, where :videoid is the unique identifier of the video.

Please note that your payload must be of application/json content type.

The payload parameters you may use are:

Payload Parameters
  • title optional string

    The new video title you want to set.

  • description optional string

    The new video description you want to set.

POST https://api.empower.net/v1/videos/30172857?access_token=ff2ae22a58046fb5f6319bbaa0b1603595273f79ddc5f9bfd8ede8379aa86ee3
{
    "title": "The New Video Title",
    "description": "The new video description."
}
                                {
  "status": 200,
  "data": {
    "id": 30172857,
    "title": "The New Video Title",
    "description": "The new video description.",
    "createdAt": "2017-12-21T14:29:00+03:00",
    "duration": 1337000,
    "embed": {
      "url": "https://www.izlesene.com/embed/npm/ornek/30172857"
    },
    "status": "available",
    "thumbnails": {
      "small": "https://i1.imgiz.com/rshots/30172/ornek-video_30172857-54010_320x180.jpg",
      "medium": "https://i1.imgiz.com/rshots/30172/ornek-video_30172857-54010_640x360.jpg",
      "large": "https://i1.imgiz.com/rshots/30172/ornek-video_30172857-54010_1280x720.jpg"
    },
    "views": 238801
  },
  "errors": [
  ]
}
                            

Delete a Video

You may delete a video using the DELETE /v1/videos/:videoid endpoint, where :videoid is the unique identifier of the video.

DELETE https://api.empower.net/v1/videos/30172857?access_token=ff2ae22a58046fb5f6319bbaa0b1603595273f79ddc5f9bfd8ede8379aa86ee3
                                {
  "status": 200,
  "data": {
    "id": 30172857,
    "title": "The New Video Title",
    "description": "The new video description.",
    "createdAt": "2017-12-21T14:29:00+03:00",
    "duration": 1337000,
    "embed": {
      "url": "https://www.izlesene.com/embed/npm/ornek/30172857"
    },
    "status": "deleted",
    "thumbnails": {
      "small": "https://i1.imgiz.com/rshots/30172/ornek-video_30172857-54010_320x180.jpg",
      "medium": "https://i1.imgiz.com/rshots/30172/ornek-video_30172857-54010_640x360.jpg",
      "large": "https://i1.imgiz.com/rshots/30172/ornek-video_30172857-54010_1280x720.jpg"
    },
    "views": 238801
  },
  "errors": [
  ]
}
                            

Upload a Video

In order to upload a video, you may either provide a URL to a publicly accessible video file or you may upload the video file using our resumable upload system.

Regardless of the method, the maximum file size is 5 GB and the supported file types are as follows: 3gp aac asf avi divx dv flv m4a m4v mkv mov mp3 mp4 mpeg mpg qt vob wmv.

Uploading with a URL

This is the simplest method for uploading your videos, as everything happens on our end automatically, after your initial request. The steps you need to follow are:

1. Send a POST request to /v1/videos endpoint, providing the publicly accessible URL of the video file with the source parameter in the payload.
2. After your request, our systems will immediately create a video object and soon start transferring the file to our CDN. The video object will be returned as a response, so you can take a note of the ID of the video and the embed URL.
3. Poll the GET /v1/videos/:videoid endpoint with the ID of the video in a few minutes to see whether its status is available. If so, you may go live with the embed URL, otherwise, allow a few more minutes before polling once more.

Uploading with Resumable Upload System

Resumable upload system uploads files in chunks and keeps track of your progress during the upload so you can resume uploading from where you left off, in case of a network connectivity issue. Since the integration is a bit tricky, we're providing a widget to make your life easier. The steps you need to follow are:

1. Embed the Empower Uploader Widget on your page using an iframe, replacing REPLACE_WITH_TICKET_ID with an actual unique ticket identifier you will obtain in the next step.
2. Send a POST request to /v1/videos endpoint, without any payload. This will return a ticket identifier that you can use to upload one video. Once the upload is complete, the ticket is invalidated and cannot be reused, so make sure that each of your users are provided with a unique ticket. Please also note that you must generate the ticket on the server-side to prevent security issues.
3. Display the user the embedded Empower Uploader Widget with a unique ticket as described in the previous step and start listening for post message events. Once the user starts uploading, a message containing the video's unique identifier is sent to the parent page so you can save it on your end. The data payload of the message is as follows: {"event": "UPLOADER_VIDEO_SET", "id": 30172857}.
4. After the user completes uploading the video, our systems will immediately and permanently invalidate the upload ticket. Soon, the video will transcoded and will be ready for streaming. You may poll in a few minutes to see whether its status is available. If so, you may go live with the embed URL, otherwise, allow a few more minutes before polling once more.

POST https://api.empower.net/v1/videos?access_token=ff2ae22a58046fb5f6319bbaa0b1603595273f79ddc5f9bfd8ede8379aa86ee3
{
    "source": "https://www.example.com/videos/sample.mp4"
}
POST https://api.empower.net/v1/videos?access_token=ff2ae22a58046fb5f6319bbaa0b1603595273f79ddc5f9bfd8ede8379aa86ee3

Embed Your Video

You may embed your videos on your website:

Using the JavaScript API

The JavaScript API enables you to control and listen to the events emitted by your player.

First, you need to place the script tag seen on the right-hand side, within the head of the pages you want to display your videos on.

Then, you need to either Create a Player with HTML or Create a Player with JavaScript to position the player on your page.

<script src="https://c1.imgiz.com/player_others/html5/NoktaNpmPlayerApi.js"></script>

Method 1: Create a Player with HTML

Place div elements with class noktaplayer wherever you wish to display a player and configure each of them using the attributes listed below.

<div> Attributes
  • data-noktaplayer-videoid optional integer

    ID of the video to embed.

  • data-noktaplayer-options optional JSON string

    A stringified JSON object of Optional Player Parameters.

  • data-noktaplayer-readyhandler optional string

    Name of the function to call once the player object is initialized. The initialized player object is passed as an argument to the provided function, so that you may use the event listeners and methods.

  • data-noktaplayer-videoinfo optional JSON string

    A stringified JSON object of Video Information Parameters.

  • data-noktaplayer-videoinfoloadurl optional string

    The URL where the player can obtain the Video Information Parameters as a JSON object. data-noktaplayer-videoid is appended to the provided URL by the player automatically. This is an alternative to using data-noktaplayer-videoinfo.

Note: You must provide either data-noktaplayer-videoinfo or data-noktaplayer-videoinfoloadurl.

Optional Player Parameters
  • playerName optional default is izlesene_embed string

    Name of the player.

  • autoplay optional default is false boolean

    Whether the player should start playing immediately.

  • showtitlebar optional default is true boolean

    Whether the title bar (and the share buttons) should be displayed.

  • showseekbar optional default is true boolean

    Whether the seek bar should be displayed.

  • showtimedisplay optional default is true boolean

    Whether the duration area should be displayed.

  • showfullscreen optional default is true boolean

    Whether the full screen toggle button should be displayed.

  • showrel optional default is true boolean

    Whether a grid of related videos should be displayed at the end of the video.

  • showreplay optional default is true boolean

    Whether a replay button should be displayed at the end of the video.

  • showloop optional default is false boolean

    Whether the loop button should be displayed.

  • loop optional default is false boolean

    Whether the video should automatically replay after the completion.

  • theme optional default is null object

    Sets the color theme of the player: {"background":"FFFFFF", "foreground":"065099", "highlight":"F94989"}

  • logo optional default is null object

    Sets the logo displayed on the left-hand side of the full screen button and the URL to open when it's clicked: {"image":"...", "clickURL": "..."}

  • language optional default is tr string

    Sets the UI language. Must be one of the following: de, en, es, fr, ru or tr.

  • volume optional default is 1.0 float

    Sets the initial volume level of the player within the [0, 1.0] range.

  • loadAdsFromServer optional default is false boolean

    Whether the ad data should be fetched from the Nokta servers.

  • adSiteID optional default is null string

    Nokta Ad Site ID

  • adCatID optional default is null string

    Nokta Ad Category ID

Video Information Parameters
  • relatedContentLoadURL optional string

    The URL where the player can obtain the list of related videos to show at the end of the video.

  • videoID optional string

    Unique identifier of the video.

  • catName optional string

    Name of the video category.

  • posterURL optional string

    The URL of the image to show as a poster image before the video.

  • duration optional integer

    Duration of the video in seconds.

  • shareAsset optional object

    URLs to use in share buttons. Keys of the object are as follows:
    - facebook: Facebook Share URL
    - twitter: Twitter Share URL
    - link: URL of the video page
    - embedCode: Embed code to distribute to users

  • titleClickURL optional string

    The URL to open when the title of the video at the top of the player is clicked.

  • media optional object

    Video source file information.

    To stream in HLS format, set the source key to the m3u8 manifest URL, type to "hls" and defaultQuality to the respective value.

    To stream in MP4 format, set the level key to an array of video source files, type to "mp4", defaultQualtiy to the respective value.

    Please refer to the example below.

// HLS Example:
info["media"] = new Object();
info["media"]["defaultQualiy"] = 360;
info["media"]["type"] = "hls";
info["media"]["source"] = "source.m3u8";

// MP4 Example:
info["media"] = new Object();
info["media"]["defaultQualiy"] = 360;
info["media"]["type"] = "mp4";
info["media"]["level"] = new Array();
info["media"]["level"].push({value:"240", source:"240p.mp4"});
info["media"]["level"].push({value:"360", source:"360p.mp4"});
info["media"]["level"].push({value:"480", source:"480p.mp4"});
<div class="noktaplayer" data-noktaplayer-videoid="..." data-noktaplayer-options="..." data-noktaplayer-readyhandler="..." data-noktaplayer-videoinfo="..." data-noktaplayer-videoinfoloadurl="..."></div>
A Complete Example
<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <script src="https://c1.imgiz.com/player_others/html5/NoktaNpmPlayerApi.js"></script>
</head>
<body>
  <script>
    function readyHandler(playerObject) {
      playerObject.addEventListener("videoStart", startHandler);
      playerObject.addEventListener("videoPause", pauseHandler);
      playerObject.addEventListener("videoResume", resumeHandler);
      playerObject.addEventListener("videoComplete", completeHandler);
      playerObject.addEventListener("volumeChange", volumeHandler);
      playerObject.addEventListener("videoReplay", replayHandler);
      playerObject.addEventListener("videoSeek", seekHandler);
    }
    function startHandler(data) {}
    function pauseHandler(data) {}
    function resumeHandler(data) {}
    function completeHandler(data) {}
    function volumeHandler(data) {}
    function replayHandler(data) {}
    function seekHandler(data) {}
  </script>
  <div class="noktaplayer" style="width:640px;height:360px;" data-noktaplayer-videoid="12345" data-noktaplayer-options="{'playerName':'npm_test','volume':0.5,'autoPlay':true, 'loadAdsFromServer':true,'adSiteID':'npm_test:site_geneli','adCatID':'site_geneli'}" data-noktaplayer-readyhandler="readyHandler" data-noktaplayer-videoinfoloadurl="//npmtest.com/videometadata/"></div>
</body>
</html>

Method 2: Create a Player with JavaScript

First, place the div to wherever you wish to display the player, with its width and height properly set.

Then, create the load event listener function, noktaPlayerApiLoadHandler and implement it with player and ad settings.

Finally, load the video by providing the video ID and ad settings.

Player Methods
  • loadVideo(id, adSettings)

    Loads the video that corresponds to the given ID, and applies the provided ad settings.

  • playVideo()

    Plays the video. Only works when the video information is fetched and the click-to-play button is visible.

  • activate(event)

    Uses the provided event object (MouseEvent or TouchEvent) to trigger the playing. Only works when the player is in IDLE state.

  • setSize(width, height)

    Sets the width and the height of the player.

  • resume()

    Resumes the paused video.

  • pause()

    Pauses the playing video.

  • replay()

    Replays the completed video.

  • seekTo(second)

    Seeks the video to the given second.

  • setVolume(level)

    Sets the volume level, which must be a floating point value within the [0, 1.0] range

  • mute()

    Mutes the player.

  • unmute()

    Unmutes the player.

  • close()

    Aborts the playing video or ad and resets the player.

  • addEventListener(type, handler)

    Binds an event listener for the given event type. Events emitted by the player are: error, adStart, adComplete, videoStart, videoComplete, videoResume, videoPause, videoReplay, volumeChange, statusChange.

Step 1
<div id="noktaplayercontainer" style="width:640px;height:360px"></div>
Step 2
var noktaPlayer, noktaAdSettings;
function noktaPlayerApiLoadHandler() {
    noktaPlayer = new NoktaPlayer("noktaplayercontainer", {playerName: "npm_test", autoPlay: true});
    noktaAdSettings = {loadAdsFromServer: true, adSiteID: "npm_test:site_geneli", adCatID: "site_geneli"};
}
Step 3
noktaPlayer.loadVideo("VIDEOID", noktaAdSettings);
A Complete Example
<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <script src="https://c1.imgiz.com/player_others/html5/NoktaNpmPlayerApi.js"></script>
</head>
<body>
  <script>
    var noktaPlayer, noktaAdSettings;
    function noktaPlayerApiLoadHandler() {
      noktaPlayer = new NoktaPlayer('noktaplayercontainer', {playerName: 'npm_test', autoPlay: true});
      noktaAdSettings = {loadAdsFromServer: true, adSiteID: 'npm_test:site_geneli', adCatID: 'site_geneli'};
    }
  </script>
  <div class="noktaplayercontainer" style="width:640px;height:360px;"></div>
  <script>
    noktaPlayer.mute();
    noktaPlayer.loadVideo('12345', noktaAdSettings);
  </script>
</body>
</html>

Using the AMP Component

On your AMP pages, you may use the amp-izlesene component to display a player.

First, you need to place the script tag seen on the right-hand side, within the head of the pages you want to display your videos on.

Then, you may use the amp-izlesene component wherever you wish to display a player and configure each of them using the attributes listed below.

<amp-izlesene> Attributes
  • data-videoid required integer

    ID of the video to embed.

  • width required integer

    Width of the player.

  • height required integer

    Height of the player.

Step 1
<script async custom-element="amp-izlesene" src="https://cdn.ampproject.org/v0/amp-izlesene-0.1.js"></script>
Step 2
<amp-izlesene data-videoid="..." layout="responsive" width="..." height="..."></amp-izlesene>

Using an Iframe

You may easily embed your videos on your website using an iframe. All you need to do is to form your embed URLs properly using the parameters listed below.

For more advanced capabilities such as listening to player events and programatically controlling the player, please see the Using the JavaScript API section below.

Path Parameters
  • USERNAME required string

    Your username defined on the system.

  • VIDEOID required integer

    The numeric unique identifier given by the system for the video you wish to embed.

Query Parameters
  • automute optional default is 0 integer

    Whether the player should be muted. Possible values are:
    0: Not muted (Default)
    1: Muted

  • autoplay optional default is 1 string

    Whether the player should start playing immediately. Possible values are:
    0: Not autoplay
    1: Autoplay (Default)

  • dfpCustom optional string

    Custom DFP key-value pairs you may wish to pass. Must be URL-encoded. key1%3Dvalue1%26key2%3Dvalue2 should be used for key1=value1&key2=value2.

<iframe src="https://www.izlesene.com/embed/npm/USERNAME/VIDEOID" width="640" height="360" allowfullscreen="true" frameborder="0"></iframe>
<iframe src="https://www.izlesene.com/embed/npm/USERNAME/VIDEOID?autoplay=0&automute=1" width="640" height="360" allowfullscreen="true" frameborder="0"></iframe>