Idomoo API

Base URL: /api/v2, Version: 2.0

Default request content-types: application/json
Default response content-types: application/json
Schemes: https

Summary

Tag: library

Operation Description
POST /libraries/

Create Scene Library

GET /libraries/

List Scene Libraries

GET /libraries/{libId}/scenes/

Return Scenes from Library

PUT /libraries/{libId}

Update Scene Library

DELETE /libraries/{libId}

Delete Scene Library

GET /libraries/{libId}

Return Specific Scene Library

Tag: generate

Operation Description
POST /storyboards/generate

Generate Video From Storyboard

POST /scenes/generate

Generate Video from Scenes

Tag: storyboard

Operation Description
GET /storyboards/{storyboradId}

Get Storyboard by ID

GET /storyboards/

List of Storyboards

Tag: account

Operation Description
GET /accounts/

Get Account Informaion

Tag: scene

Operation Description
DELETE /libraries/{libId}/scenes/{sceneId}

Delete Scene

PUT /scenes/{sceneId}

Replace Scene

PATCH /scenes/{sceneId}

Patch Scene

GET /scenes/{sceneId}

Get Scene by ID

POST /scenes/?library={libId}

Upload New Scene

GET /scenes/

List of Scenes

Security

Basic authentication

Type: basic
Description:

Basic authentication is a very simple authentication scheme that is built into the HTTP protocol. Basic authentication uses the Authorization header. 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's an example:

  • This is a string to encode: 1111:khjGLMDSJtdd7c7687ab727b47f624dc38645523b5wsJ1lPy9g2
  • The encoded string is: MTExMTpraGpHTE1EU0p0ZGQ3Yzc2ODdhYjcyN2I0N2Y2MjRkYzM4NjQ1NTIzYjV3c0oxbFB5OWcy
  • It is finally used like this: Basic MTExMTpraGpHTE1EU0p0ZGQ3Yzc2ODdhYjcyN2I0N2Y2MjRkYzM4NjQ1NTIzYjV3c0oxbFB5OWcy

Paths

Get Account Informaion

GET /accounts/

Tags: account

This returns the information about your account.

fields

Choose which fields should return. GET /account/?fields=company,email

query string Return all available fields

Uses default content-types: application/json

200 OK

Status 200

401 Unauthorized

Status 401

List Scene Libraries

GET /libraries/

Tags: library

This function lists all scene libraries available to the authenticated user.

fields

Choose which fields should return. GET /libraries?fields=id,name,description

query string Return all available fields
desc

Allow ascending and descending sorting. GET /libraries?desc=true

query boolean
limit

Set limit of results GET /libraries?limit=5

query integer 10
offset

To get a different set of items, you can use the offset and limit parameters in the GET request’s query string

GET /libraries?offset=5&limit=5 Returns scenes 6…10.

query integer

application/json

200 OK

Status 200

Create Scene Library

POST /libraries/

Tags: library

Use this function to create a new Scene Library.

Uses default content-types: application/json

name: string

A descriptive name for the Scene Library.

Uses default content-types: application/json

200 OK

Status 200

400 Bad Request

Status 400

401 Unauthorized

Status 401

Delete Scene Library

DELETE /libraries/{libId}

Tags: library

Delete the scene library. Only library owner can delete. The scenes are not deleted, however, they can't be accessed through the interface anymore.

libId path string

Uses default content-types: application/json

204 No Content

Status 204

Return Specific Scene Library

GET /libraries/{libId}

Tags: library

Return Specific Scene Library by specifying its library ID.

fields

Choose which fields should return. GET /libraries/?fields=fps,scene_id,scene_width,scene_height

query string Return all available fields
libId path string

Uses default content-types: application/json

200 OK

Status 200

403 Forbidden

Status 403

Update Scene Library

PUT /libraries/{libId}

Tags: library

Update the library’s data, such as library name and description.

Uses default content-types: application/json

libId path string

Uses default content-types: application/json

200 OK

Status 200

Return Scenes from Library

GET /libraries/{libId}/scenes/

Tags: library

Return an array of all the Scenes and their metadata held in a specific Scene Library.

fields

Choose which fields should return. GET /libraries/{libId}/scenes/?fields=id,name,description

query string Return all available fields
libId path string

Uses default content-types: application/json

200 OK

Status 200

403 Forbidden

Status 403

Delete Scene

DELETE /libraries/{libId}/scenes/{sceneId}

Tags: scene

Delete this scene. Only scene owner can delete.

libId path string
sceneId path string

Uses default content-types: application/json

204 No Content

Status 204

List of Scenes

GET /scenes/

Tags: scene

List of Scenes. You can filter which fields to show, and paginate with limit and offset.

fields

Choose which fields should return. GET /scenes?fields=fps,scene_id,scene_width,scene_height Nested fields are also supported with dot-notation.

query string
limit

Set limit on number of results. GET /scenes?limit=5

query integer 10
offset

Get a different set of items. You can use the offset and limit parameters in the GET request’s query string

For example, GET /scenes?offset=5&limit=5 returns scenes 6..10.

query integer
desc

Allow ascending and descending sorting. GET /scenes?desc=true

query boolean

Uses default content-types: application/json

200 OK

Status 200

Upload New Scene

POST /scenes/?library={libId}

Tags: scene

Upload a new scene to a scene library. You'll need an IDM file for this. Though the upload might be succesful, the scene export which happens after, might not be. Poll "check_status_url" to see when the scene has been exported succesfully.

multipart/form-data

library

Add the scene to this Scene Library. POST /scenes/?library=1111

query integer
libId path string

Uses default content-types: application/json

200 OK

Status 200

400 Bad Request

Status 400

403 Forbidden

Account Is not Owner Of scene library or it does not exists .

Generate Video from Scenes

POST /scenes/generate

Tags: generate

A scene is a video segment exported from Adobe After Effects using Idomoo’s Scene Tools. Adding several scenes together in a specific order and populating placeholders with data creates a video. The Scene API let's you do just that. You can also make a video out of a single scene.

Uses default content-types: application/json

Uses default content-types: application/json

200 OK

Status 200

400 Bad Request

Status 400

Get Scene by ID

GET /scenes/{sceneId}

Tags: scene

Get Scene by its scene ID.

fields

Choose which fields should return.

query string[]
sceneId path string

Uses default content-types: application/json

200 OK

Status 200

403 Forbidden

Account is not owner of scene or it does not exists.

Patch Scene

PATCH /scenes/{sceneId}

Tags: scene

Change properties of a scene. Currently only scene name is supported. Only scene owner can rename a scene.

Uses default content-types: application/json

scene_name: string

The new name you would like to apply to the scene.

sceneId path string

Uses default content-types: application/json

200 OK

Status 200

Replace Scene

PUT /scenes/{sceneId}

Tags: scene

Replace a scene with a new IDM file. The new and old scenes have to have several same features:

  1. At least the same placeholders, but can have more.
  2. Same frame rate (FPS).
  3. Same resolution aspect ratio (width/height).

Though the upload might be succesful, the scene export which happens after, might not be. Poll "check_status_url" to see when the scene has been exported succesfully.

multipart/form-data

sceneId path string

Uses default content-types: application/json

200 OK

Status 200

400 Bad Request

Status 400

401 Unauthorized

Status 401

List of Storyboards

GET /storyboards/

Tags: storyboard

Lists all the storyboards available to your account.

fields

Choose which fields should return. GET /storyboards/?fields=fps,storyboard_id,width,height

query string
desc

Allow ascending and descending sorting. GET / storyboards/?desc=true

query boolean
limit

Set limit of results GET /storyboards/?limit=5

query integer 10
offset

To get a different set of items, you can use the offset and limit parameters in the GET request’s query string

GET /storyboards/?offset=5&limit=5 Returns scenes 6..10.

query integer

application/json

200 OK

Status 200

Generate Video From Storyboard

POST /storyboards/generate

Tags: generate

A dynamic storyboard, created in Storybuilding Suite already holds all the scene logic and placeholder formatting. Only thing left to do to generate a video is define what output you want, and fill in the data itself.

Uses default content-types: application/json

Uses default content-types: application/json

200 OK

Status 200

400 Bad Request

Status 400

Get Storyboard by ID

GET /storyboards/{storyboradId}

Tags: storyboard

Returns information about a specific storyboard.

fields

choose which fields should return

query string[]
storyboradId path string

Uses default content-types: application/json

200 OK

Status 200

403 Forbidden

Status 403

Schema definitions

Accessibility Output: object

This feature is only available when working with Idomoo's professional services as server side setup is needed per storyboard. The list of country codes is available here.

{
"caption_languages": [
"EN",
"ES"
]
,
"transcript_languages": [
"EN",
"FR"
]
}
caption_languages: string[]

Specify which languages are needed for caption. Not passing this means no captions.

"[\"EN\", \"ES\"]"
                                                        
string
transcript_languages: string[]

Specify which languages are needed for transcript. Not passing this means no transcript.

"[\"EN\", \"FR\"]"
                                                        
string

Accessibility Response: object

{
"caption_links": [
{
"language": "en",
"url": "https://v.idomoo.com/2324/0000/2rd3822zuy3t1cvs1u3a3717u2vo63asg2jg2q38c_en.html"
}
]
,
"transcript_links": [
{
"language": "en",
"url": "https://v.idomoo.com/2324/0000/2rd3822zuy3t1cvs1u3a3717u2vo63asg2jg2q38c_en.html"
}
]
}
transcript_links: object[]

Array of transcript outputs.

object
url: string

Link to the transcript file.

language: string

The language for the transcript.

caption_links: object[]

Array of caption outputs.

object
url: string

Link to the caption file.

language: string

The language of the caption.

Account Metadata: object

All the information held about your account with Idomoo. To open an account go to: https://pv/idomoo.com/.

{
"account_id": 1066,
"company": "My Comapny Inc.",
"credits": 500,
"email": "someone@example.com",
"first_name": "John",
"last_name": "Doe",
"max_concurrency_allowed": 20
}
first_name: string
last_name: string
account_id: number
company: string
credits: number
max_concurrency_allowed: number
email: string

Audio: object

Audio placeholder. Can be created in After Effects and packaged in the scene file, but can also simply be added by adding another object to the call. Placeholders generated in After Effects can't be deleted, but can be muted.

{
"audio_duration_addition": -0.5,
"duration_addition": 2.43,
"duration_referrer": true,
"duration_upto_unique_scene_id": "product03",
"fade_end": 0,
"fade_start": 0,
"key": "audio1",
"mute": true,
"sidechain_compression_affect": true,
"start_referrer": "Audio_1",
"start_time": 0,
"val": "path/audio.wav",
"volume": 0
}
volume: number

How many dB to add to the level of the sound.

fade_end: number

Fade out the sound from the level specified in volume to no sound. How many seconds should the fade take. 0 means no fade.

duration_referrer: boolean

This placeholder defines the duration of the scene. Only a single placeholder in a scene can use this. When the media of this placeholder is over + the "duration_addition" is over, the scene ends.

sidechain_compression_affect: boolean

Sidechain compression means other audio placeholders can change the level of the soundtrack's volume. Only placeholder that have "sidechain_compression_affect":true will affect the soundtrack's volume. True means this placeholder is one.

val: string , must match ^(http|ual|pal)

The path to the audio file. Use a path to external files or files held on Idomoo servers. More about paths can be found here.

Use a wav or mp3 file.

"ual://my_media/blue_card.wav"
                                                        
mute: boolean

If you don't want to hear this audio, make this true.

fade_start: number

Fade in of sound from no sound to the level specified in volume. How many seconds should the fade take. 0 means no fade.

start_time: number

The start time of the audio in seconds. Scene start is 0. Default for placeholders generated in After Effects is the time in After Effects. For placeholders generated on the call, default is 0.

If "start_referrer" is used this parameter turns to an offset parameter. By how much to offset the start of this placeholder from the end of another placeholder.

start_referrer: string

Instead of using "start_time" the placeholder can start when another placeholder finishes. Write the "key" of this other placeholder here.

key: string

Name of placeholder from After Effects as it appears in the scene, or new name of your choosing.

duration_upto_unique_scene_id: string

Make this audio end at the end of the scene referred to with this parameter.

audio_duration_addition: number

Add this amount of seconds to the duration of the audio defined by duration_upto_unique_scene_id.

duration_addition: number

How many seconds to add or reduce to the duration of the scene on top of the end of the placeholder. Can only be used if "duration_referrer": true.

Error: object

{
"error_code": 20,
"error_description": "Bummer! We do try to get good error messages, but sometimes the unexpected happens. Please wait a few moments and try again. If the problem persists, contact Idomoo support.",
"error_message": "An internal error occurred"
}
error_description: string

A more detailed explanation regarding what went wrong.

error_message: string

A title message about the error.

error_code: integer

A code for the error.

Error Response: object

{
"errors": [
{
"error_code": 5200,
"error_description": "This Account Does Not Have Permission To Use Scene Library: 3981.",
"error_message": "Authorization error"
}
]
,
"request_id": "5636.1521807688.938.450.586167",
"status": "Error"
}
status: string , x ∈ { GENERATION_FAILED , Error }

The error status

errors: object[]

The content of the error.

request_id: string

ID of this specific request. Helps Idomoo support find the call if issues happen.

Generation Response: object

{
"check_status_url": "https://api.idomoo.com/v2/clipstatus?id=1000/0000/1tis3bx3h1gl32bp1g82y1uxpoqr1uasv",
"output": {
"gif": [
{
"cost": 0,
"height": 360,
"links": {
"url": "https://v.idomoo.com/1000/0000/1tis3bx3h1gl32bp1g82y1uxpoqr1uasv.gif"
}
,
"start": 0
}
]
,
"video": [
{
"cost": 20,
"duration": 600,
"height": 720,
"links": {
"url": "https://v.idomoo.com/1000/0000/1tis3bx3h1gl32bp1g82y1uxpoqr1uasv_small.mp4"
}
,
"quality": 26,
"suffix": "small",
"video_type": "mp4"
},
{
"cost": 20,
"duration": 600,
"height": 360,
"links": {
"url": "https://v.idomoo.com/1000/0000/1tis3bx3h1gl32bp1g82y1uxpoqr1uasv_big.mp4"
}
,
"quality": 34,
"suffix": "big",
"video_type": "mp4"
}
]
}
,
"request_id": "5637.1521725570.921.495.56049",
"status": "Success",
"total_cost": 40,
"unique_id": "1000/0000/1tis3bx3h1gl32bp1g82y1uxpoqr1uasv"
}
status: string , x ∈ { Success , GENERATION_FAILED , Error }

Status of the response. Success means all checks past, but render hasn't happened yet. Render should pass successfully as well, except for in extreme cases. More on that under "check_status_url".

total_cost: integer

How many credits were used up in this call for all the outputs generated. A credit is up to 30 seconds of rendered video.

request_id: string

ID of this specific request. Helps Idomoo support find the call if issues happen.

output: Output Response
check_status_url: string

As Idomoo's API is asynchronous, when you get a successful response it only means the API call was checked, passed, and added to the render queue. To check if the video is rendered, check this URL's status. More about this here.

unique_id: string

The specific base file name for all outputs generated with the statics ID and account ID.

GIF Output: object

{
"color_depth": 64,
"crop_to_ratio": [
4,
5
]
,
"duration": 5,
"gif_fps": 8,
"gif_loop": -1,
"height": 1080,
"label": "test",
"overlay": "path/overlay.png",
"overlay_alignment": [
"left",
"middle"
]
,
"overlay_scale": "fit",
"start": 5.2,
"suffix": "blue"
}
gif_fps: number , { x ∈ ℝ | x ≤ 30 }

The frame rate of the GIF. The frame rate has a big impact on file size. The smaller the FPS the smaller the file size.

overlay_alignment: string[]

Alignment for overlay image in case the image doesn't fit the video perfectly. The first item in the array is X. The second is Y.

"\"overlay_alignment\":[\"center\", \"middle\"]"
                                                        
string , x ∈ { left , center , right , top , middle , bottom }
color_depth: number , x ∈ { 4 , 8 , 16 , 32 , 64 , 128 , 256 (default) }

Amount of colors in palette

suffix: string

Unique ending of the file name so several outputs can be created then identified. Required if there is more then 1 video output.

overlay: string

Path to overlay image, such as: play button or watermark.

gif_loop: integer , { x ∈ ℤ | x ≥ -1 }

If to loop the GIF. -1 is no loop, 0 is infinite loops, and other numbers are number of loops.

label: string

This label is another way to identify this specific output. The label is returned in the response, but does not appear in the file name.

overlay_scale: string , x ∈ { fit (default) , fill , none }

Scale the overlay image if it's not the same size as the video.

  • Fit: scale the image up or down so it's completely visible in the video's resolution. If not the same aspect ratio, transparency is added around the image according to the alignment settings.
  • Fill: scale the image up or down so it completely fills the video. If not the same aspect ratio, the image is cropped according to the alignment settings.
  • None: don't resize the overlay image.
crop_to_ratio: number[]

Crop the final output to this ratio. The crop is done to a common center.

"[4.0, 5.0]"
                                                        
number , { x ∈ ℝ | x ≥ 1 }
start: number

What second of the storyboard timeline to start the GIF.

duration: number

Seconds for the duration of the GIF. Can't be longer than the video.

height: number

Height of the media to be rendered, in pixels. Should be the height of your scenes unless a smaller resolution is needed. Resolution higher than the scene resolution reduces quality. The width is automatically calculated to keep the aspect ratio.

Gif Output Response: object

{
"cost": 0,
"duration": 1,
"gif_fps": 12,
"height": 720,
"links": {
"url": "https://v.idomoo.com/1000/0000/1tis3bx3h1gl32bp1g82y1uxpoqr1uasv_email.gif"
}
,
"start": 0,
"suffix": "email"
}
gif_fps: number , { x ∈ ℝ | x ≤ 30 }

The frame rate of the GIF. Default is the Video frame rate.

suffix: string

The suffix to the file name, if requested.

links: object

All links associated with this output.

url: string

Link to the output. Made out of <base_url> + "unique_id" + "suffix" + "video_type".

height: integer

Height of the media rendered, in pixels. The width was automatically calculated to keep the aspect ratio.

start: number

What second of the storyboard timeline to start the GIF.

cost: number

Cost of the render in credits. A credit is 30 seconds or less.

GIFs don't cost if created from the video.

duration: number

Seconds for the duration of the GIF.

JPG Output: object

{
"crop_to_ratio": [
4,
5
]
,
"height": 720,
"label": "test",
"overlay": "path/overlay.png",
"overlay_alignment": [
"left",
"middle"
]
,
"overlay_scale": "fit",
"suffix": "john",
"time": 0.1
}
overlay_alignment: string[]

Alignment for overlay image in case the image doesn’t fit the video perfectly. The first item in the array is X. The second is Y.

"\"overlay_alignment\":[\"centre\", \"middle\"]"
                                                        
string , x ∈ { left , center , right , top , middle , bottom }
suffix: string

Unique ending of the file name so several outputs can be created then identified. Required if there is more then 1 video output.

overlay: string

Path to overlay image, such as: play button or watermark.

label: string

This label is another way to identify this specific output. The label is returned in the response, but does not appear in the file name.

overlay_scale: string , x ∈ { fit (default) , fill , none }

Scale the overlay image if it's not the same size as the video.

  • Fit: scale the image up or down so it's completely visible in the video's resolution. If not the same aspect ratio, transparency is added around the image according to the alignment settings.
  • Fill: scale the image up or down so it completely fills the video. If not the same aspect ratio, the image is cropped according to the alignment settings.
  • None: don't resize the overlay image.
crop_to_ratio: number[]

Crop the final output to this ratio. The crop is done to a common center.

"[4.0, 5.0]"
                                                        
number , { x ∈ ℝ | x ≥ 1 }
time: number

The frame of the video to render. Can also be negative number that will be calculated from the end of the video.

height: integer

Height of the media to be rendered, in pixels. Should be the height of your scenes unless a smaller resolution is needed. Resolution higher than the scene resolution reduces quality. The width is automatically calculated to keep the aspect ratio.

JPG Output Response: object

{
"cost": 0,
"height": 720,
"links": {
"url": "https://v.idomoo.com/1000/0000/1tis3bx3h1gl32bp1g82y1uxpoqr1uasv_thumb.jpg"
}
,
"suffix": "thumb",
"time": 0.5
}
time: number

The frame of the video that was rendered. Can also be negative number that will be calculated from the end of the video.

cost: number

Cost of the render in credits. A credit is 30 seconds or less.

JPGs don't cost if created from the video.

suffix: string

The suffix to the file name, if requested.

links: object

All links associated with this output.

url: string

Link to the output. Made out of <base_url> + "unique_id" + "suffix" + "video_type".

height: number

Height of the media rendered, in pixels. The width was automatically calculated to keep the aspect ratio.

Libraries List: object

A list of all the returned scene libraries.

libraries: object[]
item_count: integer

Library Metadata: object

All the information held about a specific scene library.

library_id: integer

The Scene Library ID

thumbnail: string

In the Storybuilding Suite user interface the Scene Library is represented by a thumbnail image. This is that image.

name: string

A descriptive name for the Scene Library.

scenes: integer[]

A list of the Scene IDs for the scenes in this Scene Library.

integer

Media: object

Media placeholders are unique as they are an interchangeable format. The media placeholder includes image, color, and video. No matter how the placeholder was created in After Effects, it can be used for any one of the three types.

{
"alignment_scale": 1,
"alignment_scale_type": "custom",
"alignment_x_align": 0,
"alignment_y_align": 0,
"duration_addition": 0.5,
"duration_referrer": true,
"fade_end": 1,
"fade_start": 0.5,
"if_longer": "hold",
"is_hidden": false,
"key": "underline_color",
"mute": false,
"sidechain_compression_affect": true,
"val": "http://path.to/file.mp4",
"volume": -6
}
volume: number

Only used with video media assets that contain audio.

How many dB to add to the level of the sound.

duration_referrer: boolean

Only used with video media assets.

This placeholder defines the duration of the scene. Only a single placeholder in a scene can use this. When the media of this placeholder is over + the "duration_addition" is over, the scene ends.

val: string , must match ^(http|ual|pal|rgb)

The path to the content to be placed in the media placeholder.

  • For images and video use a path to external files or files held on Idomoo servers. More about paths can be found here.
  • For color use this syntax: "rgb(###, ###, ###)". Use 8bit color ranging from 0-255.
"\"val\":\"ual://my_media/blue_card.png\""
                                                        
mute: boolean

Only used with video media assets that contain audio.

If the video contains audio you don't want to be used, make this True.

fade_start: number

Only used with video media assets that contain audio.

Fade in of sound from no sound to the level specified in volume. How many seconds should the fade take. 0 means no fade.

duration_addition: number

How many seconds to add or reduce to the duration of the scene on top of the end of the placeholder. Can only be used if "duration_referrer": true.

fade_end: number

Only used with video media assets that contain audio.

Fade out the sound from the level specified in volume to no sound. How many seconds should the fade take. 0 means no fade.

if_longer: string , x ∈ { cut (default) , loop , hold }

Only used with video media assets.

If the video is shorter than the placeholder, what to do with the video.

  • Cut: cut the placeholder. Nothing is scene after the media is finished.
  • Loop: loop the video so it repeats.
  • Hold: hold the last frame of the video frozen.
alignment_y_align: number , { x ∈ ℝ | 0 ≤ x ≤ 1 } 0.5

Alignment of media inside the placeholder in case the media doesn’t fit the placeholder perfectly. This is for the vertical Y axis. 0 is top, 0.5 is middle, and 1 is bottom.

alignment_x_align: number , { x ∈ ℝ | 0 ≤ x ≤ 1 } 0.5

Alignment of media inside the placeholder in case the media doesn’t fit the placeholder perfectly. This is for the horizontal X axis. 0 is left, 0.5 is center, and 1 is right.

key: string

Name of placeholder from After Effects as it appears in the scene.

sidechain_compression_affect: boolean

Only used with video media assets that contain audio.

Sidechain compression means other audio placeholders can change the level of the soundtrack's volume. Only placeholder that have "sidechain_compression_affect":true will affect the soundtrack's volume. True means this placeholder is one.

is_hidden: boolean

Hide a placeholder so it's not processed and shown by using this parameter.

alignment_scale: number , { x ∈ ℝ | x ≥ 0 }

By how much to scale the image. Must be used if "alignment_scale_type" is set to "custom".

alignment_scale_type: string , x ∈ { fit (default) , fill , custom }

How to scale the image or video media in case it's not the same dimensions as the placeholder.

  • Fit: scale the media up or down so it's completely visible in the video's resolution. If not the same aspect ratio, transparency is added around the image according to the alignment settings.
  • Fill: scale the media up or down so it completely fills the video. If not the same aspect ratio, the image is cropped according to the alignment settings.
  • Custom: scale the media by a specific multiplier. Used with "alignment_scale".

Colors fill the placeholder completely.

Media is always cropped inside the placeholder.

Output: object

No matter if you want to generate videos using scenes or storyboards, you need to define the output. After all, that's why we're here, to get some media back.

{
"accessibility": {
"caption_languages": [
"EN",
"ES"
]
,
"transcript_languages": [
"EN",
"FR"
]
}
,
"gif": [
{
"color_depth": 64,
"duration": 5,
"gif_fps": 8,
"gif_loop": -1,
"height": 1080,
"label": "test",
"overlay": "path/overlay.png",
"overlay_alignment": [
"left",
"middle"
]
,
"overlay_scale": "fit",
"start": 5.2,
"suffix": "blue"
}
]
,
"jpg": [
{
"height": 720,
"label": "test",
"overlay": "path/overlay.png",
"overlay_alignment": [
"left",
"middle"
]
,
"overlay_scale": "fit",
"suffix": "john",
"time": 0.1
}
]
,
"video": [
{
"height": 512,
"label": "test",
"landing_page_id": 65141,
"overlay": "path/overlay.png",
"overlay_alignment": [
"center",
"middle"
]
,
"overlay_scale": "fit",
"quality": 29,
"suffix": "134652",
"video_type": "mp4"
}
]
}
gif: object[]

Specify your animated gif outputs. Usually used for thumbnails.

video: object[]

Specify your video outputs.

accessibility: Accessibility Output
jpg: object[]

Specify your jpg outputs. Usually used for thumbnails.

Output Response: object

All output requested returned here.

{
"gif": [
{
"cost": 0,
"height": 360,
"links": {
"url": "https://v.idomoo.com/1000/0000/1tis3bx3h1gl32bp1g82y1uxpoqr1uasv.gif"
}
,
"start": 0
}
]
,
"video": [
{
"cost": 20,
"duration": 600,
"height": 720,
"links": {
"url": "https://v.idomoo.com/1000/0000/1tis3bx3h1gl32bp1g82y1uxpoqr1uasv_small.mp4"
}
,
"quality": 26,
"suffix": "small",
"video_type": "mp4"
},
{
"cost": 20,
"duration": 600,
"height": 360,
"links": {
"url": "https://v.idomoo.com/1000/0000/1tis3bx3h1gl32bp1g82y1uxpoqr1uasv_big.mp4"
}
,
"quality": 34,
"suffix": "big",
"video_type": "mp4"
}
]
}
gif: object[]

All GIFs requests returned here.

video: object[]

All video requests returned here.

accessibility: Accessibility Response
jpg: object[]

All JPGs requests returned here.

Scene: object

{
"audio": [
{
}
]
,
"duration_addition": -1,
"duration_in_seconds": 2.5,
"duration_upto_unique_scene_id": "title01a",
"media": [
{
}
]
,
"scene_id": 6121,
"scene_start_in_seconds": 0,
"start_time_offset_seconds": 2.5,
"start_time_offset_unique_scene_id": "my_scene",
"text": [
{
}
]
,
"unique_scene_id": "6151.1",
"z_index": 0
}
z_index: integer

When layering scene on top of scene a scene with a higher Z index will be on top of a scene with a lower Z index.

start_time_in_seconds: number

Absolute time for the scene to start. Can't be sent with "start_time_offset_unique_scene_id" and "start_time_offset_seconds".

unique_scene_id: string

As the same scene can be used several time, the unique scene ID is a way for the developer to identify this specific use of the scene. Must be used for "start_time_offset_unique_scene_id" to work.

media: object[]

Array of all the media placeholders, including image, video and color. All placeholders need to be called unless the defaults saved in the IDM are to be used.

duration_addition: number

Make the duration set by duration_upto_unique_scene_id shorter or longer by adding or subtracting seconds with this parameter.

start_time_offset_unique_scene_id: string

To start this scene when another scene ends, use the other scene's "unique_scene_id" here. Must not be used with "start_time_in_seconds".

duration_in_seconds: number , { x ∈ ℝ | x ≥ 0 }

Duration of the scene to use in seconds. By default, the full duration is used.

text: object[]

Array of all the text placeholders. All placeholders need to be called unless the defaults saved in the IDM are to be used.

start_time_offset_seconds: number

Offset in seconds from when the scene specified in "start_time_offset_unique_scene_id" ends. Can be used with negative values.

duration_upto_unique_scene_id: string

The duration of this scene ends at the end of the scene referred to by this parameter.

scene_id: integer

The numeric scene ID created after the scene upload.

scene_start_in_seconds: number

Stating the first frame to use from the scene in seconds. Trim the beginning of the scene.

audio: object[]

Array of all the audio placeholder. All placeholders need to be called unless the defaults saved in the IDM are to be used.

Scene API Request: object

{
"output": {
}
,
"statistic_id": 1001,
"storage": [
0
]
,
"timeline": {
}
,
"video_file_name": "id672"
}
output: Output
statistic_id: string

Use statistic ID to group several renders together for analytics.

video_file_name: string , must match ^[A-Za-z0-9]+$

The unique file name for all output types. After the file name, the suffix is added after an underscore, and finally the file extension. Only the following characters are allowed: a-z A-Z 0-9. Has to be at least 2 characters long.

storage: integer[]

By default all videos are saved on Idomoo servers. For clients working with professional services, storage can be defined so that videos are stored on another storage. Please contact support or your project manager to define storage.

integer
timeline: Timeline

Scene Metadata: object

All the information held about a specific scene, including all the placeholders found in it.

{
"audio": [
{
"duration_in_seconds": 2.04,
"key": "audio",
"start_time": 0,
"val": "pal://6964706206070378.mp3",
"volume": 0
}
]
,
"duration_in_seconds": 1,
"fps": 25,
"idm_format_version": "2.0",
"media": [
{
"duration_in_seconds": 4,
"height": 1024,
"is_hidden": false,
"key": "color",
"val": "rgb(253,1,54)",
"width": 1024
},
{
"duration_in_seconds": 4,
"height": 500,
"is_hidden": false,
"key": "image",
"val": "pal://4729309327804407781.png",
"width": 500
}
]
,
"scene_height": 1024,
"scene_id": 30611,
"scene_name": "Comp 1",
"scene_status": "Done",
"scene_width": 1024,
"text": [
{
"alignment": [
"center",
"top"
]
,
"asset_path": "courbd_16967884718120943769.ttf",
"duration_in_seconds": 4,
"font_size": 50,
"is_hidden": false,
"key": "txt",
"text_color": "rgb(255,255,255)",
"val": [
{
"text": "yossi"
}
]
}
]
,
"thumbnail": "https://materials.idomoo.com/1066/0000/2xew3e1yx4lt52p1o3f2g20is3f08qe1r362p3c21.jpg",
"video": "https://materials.idomoo.com/1066/0000/2xew3e1yx4lt52p1o3f2g20is3f08qe1r362p3c21.m3u8"
}
idm_format_version: string

The version of the IDM file format that created the scene.

errors: object[]

An array of errors for scene upload or replace.

scene_status: string , x ∈ { In Process , Exporting , Rendering Preview , Error , Done }

The status of the scene. Mainly used while uploading or to check if the scene is in error or not.

In Process - initial status

Exporting - unpacking the IDM file

Rendering Preview - rendering video and thumbnail with default data

Error - an error occured and the scene is not available

Done - the scene is ready for use

scene_height: integer

The resolution width of the scene in pixels.

720
                                                        
replace_status: string , x ∈ { In Process , Validating , Restoring , Error , Done }

When replacing a scene these are the available statuses:

In Process - initial status

Validating - making sure the scene uploaded can replace the existing scene

Restoring - if validation fails, the original scene is restored

Error - if validation fails, after restoration, an error status is set

Done - when successful and ready

scene_width: integer

The resolution height of the scene in pixels.

1280
                                                        
scene_name: string

A descriptive name of the scene. This is usually the name of the composition in After Effects, unless changed.

"Comp 1"
                                                        
duration_in_seconds: number

The duration of the scene in seconds.

2.13
                                                        
text: object[]

An array of all the text placeholders in the scene.

object
asset_path: string , must match ^(http|ual|pal)

Path/URL to font file.

wrapping_truncate: boolean

Text can be drawn outside the bounding box. With this parameter true, the text is truncated at the last whitespace inside the bounding box and replaced with "wrapping_truncate_string". The default string is an ellipsis (…).

font_size: number

Size of the text in pixels.

val: object[]

This is where you input the text. As different parts of the text can have different text attributes, this is an array. To input simple text use this:

"val":[{"text":"my simple text"}]

\n stipulates a new line character.

object
text: string

The actual text string.

wrapping_breakline: boolean

The text automatically breaks into more lines when the width of the bounding box is reached. Newline characters in the text are still used.

The default depends on the type of text layer used in After Effects:

  • For point text layers: "false".
  • For paragraph text layers: "true".
wrapping_minimum: integer

Used with "wrapping_shrink". The text will not drop below this number.

wrapping_shrink: boolean

If "wrapping_breakline" is false, this shrinks the font size when the width of the bounding box is reached.

If "wrapping_brealline" is true, this shrinks the font size when the height of the bounding box is reached.

The default depends on the type of text layer used in After Effects:

  • For point text layers: "true".
  • For paragraph text layers: "false".
text_color: string , must match ^rgb\((\d{1,3}), (\d{1,3}), (\d{1,3})\)

The color of the text.

Uses this syntax: "rgb(###, ###, ###)" in 8bit color ranging from 0-255.

"rgb(255, 127, 0)"
                                                                                                            
duration_in_seconds: number

The duration, in seconds, of the placeholder.

key: string

Name of placeholder from After Effects as it appears in the scene.

is_hidden: boolean

To hide a placeholder, so it's not rendered, change this to true. If a layer is not visible in After Effects this will be set to true by default.

wrapping_truncate_string: string

When truncating a string using "wrapping_truncate", replace the last visible whitespace with this string.

alignment: string[]

How to align the text in the bounding box. The first item in the array is X. The second is Y.

X defaults to what was packaged in the scene. Y defaults to top for placeholders generated with After Effects paragraph text layers, and bottom for placeholders generated with After Effects point text layers.

"[\"left\",\"bottom\"]"
                                                                                                            
string , x ∈ { left , center , right , top , middle , bottom }
fps: number

The frame per seconds rate of the scene.

23.976
                                                        
media: object[]

An array of all the media placeholders in the scene. Media placeholders include image, video and color placeholders.

object
val: string , must match ^(http|ual|pal|rgb)

The path to the content to be placed in the media placeholder.

  • For images and video use a path to external files or files held on Idomoo servers. More about paths can be found here.
  • For color use this syntax: "rgb(###, ###, ###)". Use 8bit color ranging from 0-255.
"\"val\":\"ual://my_media/blue_card.png\""
                                                                                                            
height: integer

The height, in pixels, of the placeholder.

width: integer

The width, in pixels, of the placeholder.

duration_in_seconds: number

The duration, in seconds, of the placeholder.

key: string

Name of placeholder from After Effects as it appears in the scene.

is_hidden: boolean

To hide a placeholder, so it's not rendered, change this to true. If a layer is not visible in After Effects this will be set to true by default.

scene_id: number

The ID of the scene.

video: string

Link to a preview of the scene.

audio: object[]

An array of all the audio placeholders in the scene.

object
volume: number

The volume to add to the sound in dB.

start_time: number

The start time of the audio in seconds. Scene start is 0.

duration_in_seconds: number

The duration, in seconds, of the placeholder.

val: string , must match ^(http|ual|pal)

The path to the content to be placed in the audio placeholder. Use a path to external files or files held on Idomoo servers. More about paths can be found here.

key: string

Name of placeholder from After Effects as it appears in the scene.

thumbnail: string

Link to a preview frame of the scene.

Scenes List: object

A list of all the returned scenes.

scenes: object[]
item_count: integer

Soundtrack: object

Add a soundtrack to run the duration of the video.

{
"audio_duration_addition": -0.5,
"duration_upto_unique_scene_id": "product03",
"fade_end": 1,
"fade_start": 0,
"sidechain_compression_amount": -12,
"val": "path/soundtrack.wav",
"volume": -1
}
volume: number

How many dB to add to the level of the sound.

sidechain_compression_amount: number

Sidechain compression means other audio placeholders can change the level of the soundtrack's volume. Only placeholder that have "sidechain_compression_affect":true will affect the soundtrack's volume. Specify by how many dB to add to the volume. This will usually be a negative number.

val: string , must match ^(http|ual|pal)

Path to the audio file of your soundtrack.

Use a path to external files or files held on Idomoo servers. More about paths can be found here.

Preferably a wav or mp3 file.

"ual://my_media/blue_card.wav"
                                                        
fade_start: number

Fade in of sound from no sound to the level specified in volume. How many seconds should the fade take. 0 means no fade.

fade_end: number

Fade out the sound from the level specified in volume to no sound. How many seconds should the fade take. 0 means no fade.

duration_upto_unique_scene_id: string

Make this audio end at the end of the scene referred to with this parameter.

audio_duration_addition: number

Add this amount of seconds to the duration of the audio defined by duration_upto_unique_scene_id.

Storyboard API Request: object

{
"data": [
{
}
]
,
"output": {
}
,
"storyboard_id": 1001
}
video_file_name: string , must match ^[A-Za-z0-9_]+$

The unique file name for all output types. After the file name, the suffix is added after an underscore. Only the following characters are allowed: a-z A-Z 0-9 _. Has to be at least 2 characters long.

storyboard_id: number

The ID of the storyboard to render.

storage: integer[]

By default all videos are saved on Idomoo servers. For clients working with professional services, storage can be defined so that videos are stored on another storage. Please contact support or your project manager to define storage.

integer
output: Output
statistic_id: string

Use statistic ID to group several renders together for analytics.

data: object[]

An array of all the keys and vals required by the storyboard to generate a video.

Storyboard Data: object

val: string

The value for the key. It depends on what the key represents and how it was setup.

"\"Christopher\""
                                                        
key: string

Name of parameters defined in the Storybuilding Suite.

Storyboard List: object

A list of all the returned storyboards.

storyboards: object[]
item_count: integer

Storyboard Metadata: object

All the information held about a specific storyboard, including all the keys associated with it.

data: object[]

List of all the parameters in this storyboard.

object
val: string

The value to enter for the parameter.

key: string

The parameter name.

name: string

The descriptive name of this storyboard.

storyboard_id: integer

The unique number of this storyboard.

thumbnail: string

Link to an image representing this storyboard.

Text: object

Text placeholder. Can use different text attributes (font, size, color and so on) for different parts of the text. Text can also be created outside the bounding box.

The bounding box is created in After Effects.

The whole text with its different fonts and sizes is considered when applying alignment and bounding box wrapping operations.

{
"alignment": [
"right",
"bottom"
]
,
"asset_path": "path/font_name.ttf",
"font_size": 32,
"is_hidden": false,
"key": "date",
"right_to_left": true,
"text_color": "rgb(0,0,0)",
"val": [
{
}
]
,
"vertical": false,
"wrapping_breakline": false,
"wrapping_minimum": -1,
"wrapping_shrink": true,
"wrapping_truncate": false,
"wrapping_truncate_string": "[more...]"
}
asset_path: string , must match ^(http|ual|pal)

Path to the default font to use. This can be overwritten in Text Properties. However this is the font to be used for calculating the location of the baseline.

The default font is the one packaged with the scene.

wrapping_truncate: boolean

Text can be drawn outside the bounding box. With this parameter true, the text is truncated at the last whitespace inside the bounding box and replaced with "wrapping_truncate_string". The default string is an ellipsis (…).

font_size: number

Size of text in pixels. Default is the size of the text packaged with the scene.

vertical: boolean

Denoted the text to run from top to bottom.

val: object[]

This is where you input the text. As different parts of the text can have different text attributes, this is an array. To input simple text use this:

"val":[{"text":"my simple text"}]

Use \n to stipulate a new line character.

wrapping_breakline: boolean

The text automatically breaks into more lines when the width of the bounding box is reached. Newline characters in the text are still used.

The default depends on the type of text layer used in After Effects:

  • For point text layers: "false".
  • For paragraph text layers: "true".
wrapping_minimum: integer

Used with "wrapping_shrink". The text will not drop below this number.

wrapping_shrink: boolean

If "wrapping_breakline" is false, this shrinks the font size when the width of the bounding box is reached.

If "wrapping_brealline" is true, this shrinks the font size when the height of the bounding box is reached.

The default depends on the type of text layer used in After Effects:

  • For point text layers: "true".
  • For paragraph text layers: "false".
text_color: string , must match ^rgb\((\d{1,3}), (\d{1,3}), (\d{1,3})\)

The color of the text. This can be overwritten by Text Properties. Default is the color of the text packaged with the scene.

Use this syntax: "rgb(###, ###, ###)". Use 8bit color ranging from 0-255.

"rgb(255, 127, 0)"
                                                        
key: string

Name of placeholder from After Effects as it appears in the scene.

right_to_left: boolean

When true, the paragraph is to run from right to left. This is to support right to left languages such as Arabic and Hebrew.

is_hidden: boolean

Hide a placeholder so it’s not processed and shown by using this parameter.

wrapping_truncate_string: string

When truncating a string using "wrapping_truncate", replace the last visible whitespace with this string.

"[more…]"
                                                        
alignment: string[]

How to align the text in the bounding box. The first item in the array is X. The second is Y.

X defaults to what was packaged in the scene. Y defaults to top for placeholders generated with After Effects paragraph text layers, and bottom for placeholders generated with After Effects point text layers.

"[\"left\",\"bottom\"]"
                                                        
string , x ∈ { left , center , right , top , middle , bottom }

Text Properties: object

Array of text strings with properties that override the default properties.

[
{
"baseline": 0,
"color": [
0.533,
0.533,
0.533
]
,
"font_path": "path/other_font_name.ttf",
"highlight": [
1,
1,
0
]
,
"scale": 1.2,
"strikethrough": false,
"text": "January\n5",
"underline": false
},
{
"baseline": 0.5,
"scale": 0.5,
"text": "th",
"underline": true
}
]
scale: number , { x ∈ ℝ | x ≥ 0 }

Multiplies the size found in "font_size" for this part of the text.

baseline: number

Shifts the vertical location of the text upward. A value of 1 is the size of the font.

0.5
                                                        
color: string , must match ^rgb\((\d{1,3}), (\d{1,3}), (\d{1,3})\)

Overwrite the color for this part of the text.

Use this syntax: "rgb(###, ###, ###)". Use 8bit color ranging from 0-255.

"rgb(255, 127, 0)"
                                                        
text: string

The actual text string. Use \n for newline character.

strikethrough: boolean

Draw a line through the middle of the text.

font_path: string , must match ^(http|ual|pal)

Overwrite the font for this part of the text. Use a path.

highlight: string , must match ^rgb\((\d{1,3}), (\d{1,3}), (\d{1,3})\)

Draw a colored box behind the text similar to a word processor highlight. Not passing this parameter means no highlight.

Enter the color you want. Use this syntax: "rgb(###, ###, ###)". Use 8bit color ranging from 0-255.

"rgb(255, 127, 0)"
                                                        
underline: boolean

Draw a line at the baseline of the text.

Timeline: object

{
"timeline": {
"scene_order": "linear",
"scenes": [
{
}
]
,
"soundtrack": {
"fade_end": 1,
"fade_start": 0,
"sidechain_compression_amount": -12,
"val": "path/soundtrack.wav",
"volume": -1
}
}
}
soundtrack: Soundtrack
scenes: object[]

Array of scenes to render. The order matters if Scene Order is set to linear. Otherwise, there is no significance to order.

scene_order: string , x ∈ { linear (default) , non-linear }

How to order the scene on the timeline:

  • Linear scene ordering simply places the scenes in the order you specify, one after the other.
  • Non-linear scene ordering leaves the start timing of each scene up to you.

Upload Scene: object

Information returned about your scene. Though the upload might be succesful, the scene export which happens after, might not be. Poll "ref" to see when the scene has been exported succesfully.

scene_id: number

The unique number given to this scene.

ref: string

Link to query the newly uploaded scene.

Video Output: object

{
"crop_to_ratio": [
4,
5
]
,
"height": 512,
"label": "test",
"landing_page_id": 65141,
"overlay": "path/overlay.png",
"overlay_alignment": [
"center",
"middle"
]
,
"overlay_scale": "fit",
"quality": 29,
"suffix": "134652",
"video_type": "mp4"
}
overlay_alignment: string[]

Alignment for overlay image in case the image doesn't fit the video perfectly. The first item in the array is X. The second is Y.

"\"overlay_alignment\":[\"centre\", \"middle\"]"
                                                        
string , x ∈ { left , center , right , top , middle , bottom }
suffix: string

Unique ending of the file name so several outputs can be created then identified. Required if there is more then 1 video output.

overlay: string

Path to overlay image, such as: play button or watermark.

landing_page_id: string

The ID of the landing page that is returned in the response to present the video in.

label: string

This label is another way to identify this specific output. The label is returned in the response, but does not appear in the file name.

video_type: string , x ∈ { mp4 , hls }

Type of x264 to output. Render HLS for real-time playback and MP4 if you just need a file.

crop_to_ratio: number[]

Crop the final output to this ratio. The crop is done to a common center.

"[4.0, 5.0]"
                                                        
number , { x ∈ ℝ | x ≥ 1 }
overlay_scale: string , x ∈ { fit (default) , fill , none }

Scale the overlay image if it's not the same size as the video.

  • Fit: scale the image up or down so it's completely visible in the video's resolution. If not the same aspect ratio, transparency is added around the image according to the alignment settings.
  • Fill: scale the image up or down so it completely fills the video. If not the same aspect ratio, the image is cropped according to the alignment settings.
  • None: don't resize the overlay image.
height: integer

Height of the media to be rendered, in pixels. Should be the height of your scenes unless a smaller resolution is needed. Resolution higher than the scene resolution reduces quality. The width is automatically calculated to keep the aspect ratio.

quality: integer , { x ∈ ℤ | 1 ≤ x ≤ 50 } 26

Quality of x264. The lower the number, the higher the quality and file size. Numbers between 21 - 29 should be more than enough for most uses.

Video Output Response: object

{
"cost": 20,
"duration": 600,
"height": 720,
"links": {
"url": "https://v.idomoo.com/1000/0000/1tis3bx3h1gl32bp1g82y1uxpoqr1uasv_small.mp4"
}
,
"quality": 26,
"suffix": "small",
"video_type": "mp4"
}
suffix: string

The suffix to the file name, if requested.

links: object

All links associated with this output.

url: string

Link to the output. Made out of <base_url> + "unique_id" + "suffix" + "video_type".

landing_page_url: string

Link to the landing page containing the video, if requested.

video_type: string , x ∈ { mp4 , hls }

Type of x264 to output returned. HLS or MP4.

height: integer

Height of the media rendered, in pixels. The width was automatically calculated to keep the aspect ratio.

cost: number

Cost of the render in credits. A credit is 30 seconds or less.

duration: number

The duration that was rendered in seconds.

Quality: integer , { x ∈ ℤ | 1 ≤ x ≤ 50 } 26

Quality of x264. The lower the number, the higher the quality and file size.