The following paragraphs describe the various aspects involved in interfacing with Idomoo’s API.


API Endpoints

Idomoo’s API 2.0 has several endpoints all starting from one of several roots, depending on the territory in which you want your data sent to and processed:


USAhttps://usa-api.idomoo.com/api/v2
EUhttps://eur-api.idomoo.com/api/v2


The rest of the URI depends on the function you are using.


API Headers

No matter what function you are using, the headers of the API should always be the following:


KeyValue
AuthorizationBasic ZGVtbzpwQDU1dzByZA==
Acceptapplication/json



Security

In order to make sure you are who you say you are Idomoo offers the following security mechanisms.

Idomoo's APIs use Basic authorization. Basic authorization is a very simple authorization scheme that is built into the HTTP protocol. To create the value for the authorization header follow these steps:

  1. Create a string from the acount ID and API Secret Key with a colon (:) between them.
  2. Take the string and base64-encode it.
  3. Add the word Basic followed by a space before the encoded string.

Here is an example with some dummy data:


Account ID1111
API Secret KeykhjGLMDSJtdd7c7687ab727b47f624dc38645523b5wsJ1lPy9g2
String to encode1111:khjGLMDSJtdd7c7687ab727b47f624dc38645523b5wsJ1lPy9g2
Encodes asMTExMTpraGpHTE1EU0p0ZGQ3Yzc2ODdhYjcyN2I0N2Y2MjRkYzM4NjQ1NTIzYjV3c0oxbFB5OWcy
Used asBasic MTExMTpraGpHTE1EU0p0ZGQ3Yzc2ODdhYjcyN2I0N2Y2MjRkYzM4NjQ1NTIzYjV3c0oxbFB5OWcy



Finding the Account ID and API Secret Key

You can find the Account ID in the Storybuilding Suite by following these steps:

  1. Make sure you are logged in to the Storybuilding Suite.
  2. Click your name or account icon at the top right of the interface.
  3. Find the Account ID to the right of your name, in parentheses.


You can find the API Secret Key in the Storybuilding Suite by following these steps:

  1. From the top-right account menu (the one showing your registered name), click Settings.
  2. Click the API Keys tab.
  3. Your API Secret Key as available to copy in this page.

Using Authorization Method in Postman

To build the authorization header in Postman follow these steps:

  1. Click the Authorization tab.
  2. Choose Basic Auth from the Type pull-down menu.
  3. Add your account ID to the Username text field, and the API Secret Key to the Password text field.
  4. Click Preview Request to create the header.
  5. To change the header go back to the Authorization tab and change the Username or Password.
  6. To Remove Authorization change the type back to No Auth.

This example was made with Postman 6.0.8.


Concurrency

The concurrency allowed for API calls is 10 per minute. If more is needed, please contact support: support@idomoo.com.


Asynchronous API

Idomoo's API is asynchronous.
When you send an API call you get a near instantaneous response. The successful response includes the link to the video, image, or landing page. The video has not yet been generated. Instead, the request has been added to a queue and is processed when it reaches the top of the queue.
To check if your video is ready, you can use a URL that will update you with the progress. Find the URL under the "check_status_url" property in the response.
When you check the URL you are presented with a status update similar to this:


{"status": "VIDEO_AVAILABLE", "id": "1281/0000/583g401zlu1gk730q142732a31o22i672n3z24q"}


The status updates with the following options:

StatusDescription
IN_PROCESSThe API request arrived and is being processed.
IN_QUEUEThe video is waiting to be rendered.
RENDERINGThe video is being rendered at the moment
VIDEO_AVAILABLEThe process is finished and the video is ready.
ERRORSomething went wrong, with descriptions, as per a regular API call.
NOT_EXISTThe ID does not exist.


Developer Mode

Sending a generation call charges the client. When developing a generation call Idomoo doesn't want to charge, as you are only preparing the work, not sending it to clients. For this reason we created the developer mode. This adds a watermark to your videos, but does not charge your account.

To use Developer Mode simply send the following header in every call:


"x-idomoo-api-mode":"developer"


There are different allowances when using developer mode. These are:

Concurrency2 calls per minute
Daily Allowance200 generate calls a day (metadata calls are not counted)
Video File Expiration1 day


Unit Types

The API expects the following unit types:


DataDescriptionUnit TypeExample
TimeSecondsfloat1.2154
Color8bit color: 0-255. Syntax: “rgb(###, ###, ###)”string“rgb(127, 65, 13)”
ResolutionWidth and height in pixelsint720
Scale / SizePercent: 0-1float0.5
VolumeDecibeldB-6
PathPath to assetsstringhttps://dl.com/u/12/AmericanTypewriter.otf” “pal://1255/assets/image.png” “ual://my images/music.mp3”


More information about paths can be found here.



 Next API Reference 
 Back API Overview