Documentation

Rocketium Code opens up our platform so third-party developers can create and manipulate images and videos programmatically.

post
Create video

https://code.rocketium.com/v1/videos
Rocketium's "Create API" lets you programmatically create videos using images, clips, text, and audio as input.
Request
Response
Request
Headers
access_token
required
string
Your API key
Content-Type
required
string
Allowed value is application/json
Body Parameters
scenes
required
array
Every video consists of multiple scenes, each with media (image, video, or GIF), voice-over, and captions. This field has details of the scenes. Details of the object are here.
themeId
required
string
ID of workspace where the exported video should be saved. If this is not specified, the video will be available in the last workspace you have opened. Please talk to your account manager to get ID of theme to be used to apply styles. You can get this by calling the Get Themes API.
teamId
optional
string
ID of workspace where the exported video should be saved. If this is not specified, the video will be available in the last workspace you have opened. Please talk to your account manager to get this ID.
title
optional
string
Title of the video. This will be visible in your workspace.
logoImage
optional
string
URL of image to be used as logo.
logoCustomPosition
optional
object
Custom position for logo.
metadata
optional
object
A custom object that can be sent to be associated with this video. This entire object will be sent in the response to a webhook callback, if any. This is useful for associating videos with users, products, or any other internal identifiers. If the object has an array of Share objects with the targets key, the video will be shared to the specified destinations after it has been rendered.
audio
optional
string
URL of an audio file. If this is not provided, audio from the specified theme will be used.
draftOnly
optional
boolean
Passing true will only create a draft in the Rocketium library but not render it as an mp4 video file. The default value is false i.e. without any input for this parameter a video will be generated and count against the 10 videos for a free user.
id
optional
string
The unique ID of a video returned from an earlier create API call. This can be used to make a copy of an existing video.
audio_mood
optional
string
Acceptable values are one of calm, bright, serious, inspirational and comical. If this is present, the 'audio' parameter needs to be removed as it takes precedence over the 'audio_mood' parameter.
orientation
optional
string
One of landscape, square, portrait, fbCover, instagramAd
videoBackground
optional
string
URL of an image or video to use as the background of the entire video. This will only show up in scenes where the image does not cover the entire scene.
brandColors
optional
array
Array of hexcodes of colors to be used as brandColors in the creative. A brand colour must be defined for various elements (overlays, text colors, background color, etc.) while creating the template. Users can directly pass colour hex codes in the JSON to get appropriate colour.
export-settings
optional
object
Additional export settings for the video such as bitrate.
templateVariables
optional
object
Instead of passing the entire scenes JSON, you can also pass data for individual variables in the template. If this is provided, scenes will be ignored. { name: 'Jean-Luc Picard', description: 'Captain of USS Enterprise', tagline: 'Make it so!' }
createProject
optional
boolean
If true, a new project will be created for this video. Note:- 1. The video will be available only in one size and style 2. If the same video is edited multiple times, a new project will be created every time 3. A zip file will not be created for this project
Response
200: OK
The response from the API will contain message indicating success or error and videoId which you can use to retrieve the video. In case of errors, the message will contain the relevant error as described in the error codes section below.
Success
Success
{
"message": "successful",
"videoId": "video1234567890",
"videoUrl": "https://rocketium.com/.../....mp4"
}

post

https://code.rocketium.com/v1/videos
Request
Response
Request
Body Parameters
templateVariables
optional
object
also
Response
200: OK
also

post

https://code.rocketium.com/v1/videos
Request
Response
Request
Body Parameters
createProject
optional
boolean
When this is enabled, a new project will be created in the project dashboard. Present constraints : 1. Multiple sizes and styles are not supported. 2. Not supported in case a video id is passed, a duplicate project will be created. 3. Zip file won't be created but on republish of the campaign will work as expected
Response
200: OK

post

https://code.rocketium.com/v1/videos
Request
Response
Request
Body Parameters
createProject
optional
boolean
When this is enabled, a new project will be created in the project dashboard. Present constraints : 1. Multiple sizes and styles are not supported. 2. Not supported in case a video id is passed, a duplicate project will be created. 3. Zip file won't be created but on republish of the campaign will work as expected
Response
200: OK

post

https://code.rocketium.com/v1/videos
Request
Response
Request
Body Parameters
createProject
optional
boolean
When this is enabled, a new project will be created in the project dashboard. Present constraints : 1. Multiple sizes and styles are not supported. 2. Not supported in case a video id is passed, a duplicate project will be created. 3. Zip file won't be created but on republish of the campaign will work as expected
Response
200: OK

post

https://code.rocketium.com/v1/videos
Request
Response
Request
Body Parameters
templateVariables
optional
object
Instead of passing the entire scenes JSON, you can also pass data for individual variables in the template. If this is provided, scenes will be ignored. { name: 'Jean-Luc Picard', description: 'Captain of USS Enterprise', tagline: 'Make it so!' }
Response
200: OK

Create video error codes

message value

Explanation

invalid token

The access token you specified in the header is not correct.

you reached the limit for using this api

Every API has a limit to prevent abuse. Please contact your account manager or message on our web chat to unblock this.

invalid user

The specified themeId does not exist.

Maximum 50 scenes can be added. Kindly delete 5 more

The number of scenes per video is limited to a max of 50. You can fix this by reducing the number of scenes to within 50. To increase this limit, please contact your account manager or message on our web chat.

Kindly enter a media for scene : 5

The image field is empty or absent. Every scene in a video needs a valid image or video in it.

invalid text for scene : 5 caption : 3

The text field has too many characters. You can fix this by reducing the number of characters to less than 300. To increase this limit, please contact your account manager or message on our web chat.

insufficient credits

Each account has a monthly limit for the number of videos that can be created. This error is shown when the limit has been reached. To increase this limit, please contact your account manager or message on our web chat.

feature unavailable

You are using features like background removal that have not been enabled for your account.

background removal failed

Background removal failed despite multiple retries.

post
Create image

https://code.rocketium.com/v1/videos
Rocketium's Create API lets you programmatically create images using images and text. As the same API is used for creating videos, an additional outputFormat parameter is required for image creation.
Request
Response
Request
Headers
access_token
optional
string
Your API key
Content-Type
optional
string
Allowed value is application/json
Body Parameters
scenes
required
array
For creating an image we need only one scene with media and captions. This field has details of the scene.
outputFormat
required
string
This value has to be image for this request to create an image.
themeId
required
string
ID of theme to be used to apply styles.
teamId
optional
string
ID of workspace where the exported image should be saved. If this is not specified, the image will be available in the last workspace you have opened.
logoImage
optional
string
Title of the image. This will be visible in the Images tab in your workspace.
metadata
optional
string
A custom object that can be sent to be associated with this image. This entire object will be sent in the response to a webhook callback, if any. This is useful for associating images with users, products, or any other internal identifiers.
draftOnly
optional
boolean
Passing true will only create a draft in the workspace but not render it as an image. The default value is false.
id
optional
string
The unique ID of an image returned from an earlier create API call. This can be used to make a copy of an existing image.
orientation
optional
string
One of landscape, square, portrait, fbCover, instagramAd.
templateVariables
optional
object
[DRAFT] Instead of passing the entire scenes JSON, you can also pass data for individual variables in the template. If this is provided, scenes will be ignored. { name: 'Jean-Luc Picard', description: 'Captain of USS Enterprise', tagline: 'Make it so!' }
Response
200: OK
The response from the API will contain message indicating success or error and videoId which you can use to retrieve the image. In case of errors, the message will contain the relevant error as described in the error codes section below.
Success
Success
{
"message": "successful",
"videoId": "image1234567890",
"imageUrl": "https://rocketium.com/.../....png"
}

Create image error codes

message value

Explanation

invalid token

The access token you specified in the header is not correct.

you reached the limit for using this api

Every API has a limit to prevent abuse. Please contact your account manager or message on our web chat to unblock this.

invalid user

The specified themeId does not exist.

Kindly enter a media for scene : 1

The image field is empty or absent.

invalid text for scene : 1 caption : 3

The text field has too many characters. You can fix this by reducing the number of characters to less than 300. To increase this limit, please contact your account manager or message on our web chat.

insufficient credits

Each account has a monthly limit for the number of images that can be created. This error is shown when the limit has been reached. To increase this limit, please contact your account manager or message on our web chat.

feature unavailable

You are using features like background removal that have not been enabled for your account.

background removal failed

Background removal failed despite multiple retries.

post
Convert text to speech

https://api.rocketium.com/speech
The text-to-speech API allows you to create natural-sounding voice-overs for use in your videos.
Request
Response
Request
Headers
access_token
optional
string
Your API key
Content-Type
optional
string
Allowed value is application/json.
Body Parameters
text
required
string
Text to convert to speech.
voice
required
string
Voice in which the voice should speak. Supported values are - in-female1, us-female1, us-male1, uk-female1, uk-male1.
Response
200: OK
The response will contain a message with a value of successful or error. If it is successful, the url will contain a link to the voice-over audio.
Success
Success
{
"message": "successful",
"url": "https://rocketium.com/.../....mp3"
}

post
Create workspace

https://api.rocketium.com/workspaces
This API enables you to create workspaces under your account.
Request
Response
Request
Headers
access_token
required
string
Your API key
Body Parameters
name
required
string
Every workspace needs a name to be identifiable.
Response
200: OK
The response will contain a message with a value of successful, invalid team name, invalid user, or limit reached. If it is successful, id will be the ID of the newly-created workspace.
Success
Success
{
"message": "successful",
"id": "some-id",
"shortId": "some-short-id"
}

post
Create motion graphic

https://api.rocketium.com/motion-graphics
Rocketium Create motion graphic API lets you programmatically create motion graphics like overlays, transitions, and caption backgrounds using images and clips.
Request
Response
Request
Headers
access_token
required
string
Your API key
Content-Type
required
string
application/json
Body Parameters
asset
required
string
Every motion graphic element is created from an existing asset. We support PNG and webm files. Pass a publicly-accessible link to the asset file.
type
required
string
Type of motion graphic to create. Allowed values are overlay and caption-background.
orientation
optional
string
Orientation of the motion graphic. Allowed values are landscape, square, portrait, fbCover, instagram.
loop
optional
boolean
Specify if the overlay should loop after it finishes playing or freeze after reaching the end.
size
optional
boolean
Specify if the caption-background should fit or fill inside the container. Allowed values are fit, fill, stretch.
Response
200: OK
This API might take up to 5 seconds as it involves rendering the asset into a motion graphic element. The message will be error if the API encountered an error. Details of the error will be in the details field. Possible values for this field are in the table below.
Success
Success
{
"message": "successful",
"url": "https://rocketium.com/.../....webm"
}

Create motion graphics error codes

details value

Explanation

missing-asset

No asset URL specified in the request

missing-type

No type specified in the request

asset-inaccessible

Asset is not accessible

asset-invalid

Asset is not a PNG or webm file

orientation-invalid

Asset is not one of landscape, square, portrait, fbCover, instagram

loop-invalid

loop is not one of true and false

post
Share

https://api.rocketium.com/share
Rocketium Share API lets you programmatically share videos, GIFs, or images to social, cloud storage, and advertising platforms.
Request
Response
Request
Headers
access_token
required
string
Your API key
Content-Type
required
string
application/json
Body Parameters
videoId
required
string
ID of the video you want to share. This is the same as the videoId field returned in the response of the Create Video API.
targets
optional
array
An array of objects representing individual shares.
Response
200: OK
The message will be error if the API encountered an error. Details of the error will be in the details field. Possible values for this field are in the table below.
Success
Success
{
"message": "successful",
"details": "Your video was shared successfully to Youtube"
}

Share Object

Key

Type

Value

platform

String

Platform where the media should be shared. Allowed values are facebook-page and youtube.

pageId

String

ID of the page to which image or video should be shared. Only applicable when platform is facebook-page.

description

String

Text description of the media. Can contain emoji. 🎉

publishAt (optional)

String

Time when the image or video should be published. Should be specified in the ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) format. Only applicable when platform is facebook-page.

title

String

Text description of the media. Can contain emoji. 🎉

thumbnail (optional)

String

Publicly accessible link to an image to be shown as thumbnail. Only applicable when platform is youtube.

tags

Array of String

Keywords for the video that help in discovery by users. Only applicable when platform is youtube.

visibility

String

Controls who can see the video. Allowed values are public, private, and unlisted. Only applicable when platform is youtube.

Share error codes

details value

Explanation

platform-invalid

platform is not one of facebook-page and youtube.

access-invalid

The account does not have access to the specified page or channel.

visibility-invalid

visibility is not one of private, public, unlisted.

post
Publish Video

https://code.rocketium.com/v1/publish
The publish API can be used to publish a previously created draft or republish an existing video in Rocketium using just the videoId.
Request
Response
Request
Headers
access_token
required
string
Your API access token
Body Parameters
videoId
required
string
VideoId of a previously generated/draft video
Response
200: OK
{
"message": "successful",
"videoUrl": "//rocketium.com/videos/video-url-goes-here"
}

get
Get video

https://api.rocketium.com/videos/:id
Once your video is created, you can easily retrieve it with a simple API call.
Request
Response
Request
Path Parameters
id
required
string
ID of the video you want to retrieve. This is the same as the videoId field returned in the response of the Create video API.
Headers
access_token
required
string
Your API key
Response
200: OK
The response from the API will contain a message with values successful, in_progress, or error. If the message is successful, the response will have the URL which you can use to access the video. If the message is in_progress, the response will have progress indicating the percentage progress in rendering the video.
Success
Success
{
"message": "successful",
"url": "https://rocketium.com/.../....mp4"
}

get
Get image

https://api.rocketium.com/videos/:id
Once your image is created, you can easily retrieve it with a simple API call.
Request
Response
Request
Path Parameters
id
optional
string
ID of the image you want to retrieve. This is the same as the videoId field returned in the response of the Create image API.
Headers
access_token
optional
string
Your API key
Response
200: OK
The response from the API will contain a message with values successful, in_progress, or error. If the message is successful, the response will have the URL which you can use to access the video. If the message is in_progress, the response will have progress indicating the percentage progress in rendering the image.
Success
Success
{
"message": "successful",
"url": "https://rocketium.com/.../....png"
}

Instead of polling for images and videos to be ready, you can also register a callback. We support REST APIs and send data in application/json format. Please talk to your account manager to get this set up.

get
Get themes

https://api.rocketium.com/api/v3/getThemes
This API returns themes associated with your account and public themes available to all users.
Request
Response
Request
Headers
access_token
required
string
Your API key
Query Parameters
teamId
optional
string
If this is not specified, themes available in every workspace will be returned. If a valid value is specified, themes from the given workspace will also be returned in addition to common themes.
filter
optional
If this is not specified, both public and private themes will be returned. If a valid value is specified, appropriate filter will be applied. Filter can be PUBLIC or PRIVATE, if no filter is provided both public and private are returned.
Response
200: OK

get
Get themes (Legacy V2)

https://api.rocketium.com/api/v2/themes
This API returns themes associated with your account and public themes available to all users.
Request
Response
Request
Path Parameters
optional
string
Response
200: OK

get
Get templates

https://api.rocketium.com/api/v3/getTemplates
This API returns templates associated with your account and public templates available to all users.
Request
Response
Request
Headers
access_token
required
string
Your API key
Query Parameters
tags
optional
string
A comma separated list of tags can be specified to return all the templates carrying those tags. Tags could specify use cases, marketing campaigns etc.
categories
optional
string
A comma separated list of categories can be specified to return all the templates (video and image) in that category. This can include public and private templates.
outputFormat
optional
string
Filtering image or video to show only image or video templates
teamId
optional
string
If this is not specified, public templates will be returned. If a valid value is specified, templates from the given workspace will also be returned in addition to public templates.
filter
optional
string
If this is not specified, both public and private templates will be returned. If a valid value is specified, appropriate filter will be applied. Filter can be PUBLIC or PRIVATE, if no filter is provided both public and private are returned.
Response
200: OK
{
"message": "successful",
"templates": [
{
"_id": "5a1517d21f88305bb8ff7fb4",
"name": "Listicles",
"orientation": "landscape",
"outputFormat": "video",
"thumbnail": "https://rocketium.com/images/export/5a1512a11f88305bb8ff7f44/1562650128765.png",
"preview_url": "https://rocketium.com/videos/57544fcdd8fa816f2043e705/720p/sports-and-positive-info-listicles_1562650120207.mp4"
},
{
"_id": "5a8bba8a8e79dc7da37f60a1",
"name": "Social media outro facebook",
"orientation": "landscape",
"outputFormat": "video",
"thumbnail": "https://rocketium.com/images/export/5a8bad125895f4471ee4286f/1562643165902.png",
"preview_url": "https://rocketium.com/videos/57544fcdd8fa816f2043e705/720p/social-media-outro-facebook_1562643160509.mp4"
},

get
Get template

https://api.rocketium.com/api/v1/template/:id
This API returns the JSON of a single template.
Request
Response
Request
Path Parameters
id
optional
string
The ID of the template whose code has to be retrieved.
Headers
access_token
required
string
Your API key
Query Parameters
templateVariables
optional
boolean
Return template variables and placeholder values instead of the scenes array
advancedCodeGen
optional
boolean
If this is true, advanced version of the template code will be returned.
Response
200: OK
// templateVariables: false
{
"message": "successful",
"template": {
"_id": "5a8bba8a8e79dc7da37f60a1",
"name": "Social media outro facebook",
"orientation": "landscape",
"thumbnail": "https://rocketium.com/images/export/5a8bad125895f4471ee4286f/1562643165902.png",
"preview_url": "https://rocketium.com/videos/57544fcdd8fa816f2043e705/720p/social-media-outro-facebook_1562643160509.mp4",
"description": "Template for Social media outro facebook",
"code": {
"themeId": "5a8bba81abc5e17e6bf3da62",
"audio": "/audio/resized/Rock-Me-to-Sleep_FULL_SFT013101.mp3",
"outputFormat": "video",
"title": "Social media outro facebook",
"teamId": "5a8b956854df7203fe9e9a9c",
"templateId": "5a8bba8a8e79dc7da37f60a1",
"scenes": [
{
"layoutId": "1519103246769",
"image": "//rocketium.com/images/57544fcdd8fa816f2043e705/resized/1519188661549.png",
"elements": [
{
"text": "Like and Follow us",
"type": "sticky"
},
{
"text": "@Rocketium_App",
"type": "caption"
}
]
}
]
}
}
}
// templateVariables: true
{
"message": "successful",
"template": {
"_id": "5a8bba8a8e79dc7da37f60a1",
"name": "Social media outro facebook",
"orientation": "landscape",
"thumbnail": "https://rocketium.com/images/export/5a8bad125895f4471ee4286f/1562643165902.png",
"preview_url": "https://rocketium.com/videos/57544fcdd8fa816f2043e705/720p/social-media-outro-facebook_1562643160509.mp4",
"description": "Template for Social media outro facebook",
"code": {
"themeId": "5a8bba81abc5e17e6bf3da62",
"audio": "/audio/resized/Rock-Me-to-Sleep_FULL_SFT013101.mp3",
"outputFormat": "video",
"title": "Social media outro facebook",
"teamId": "5a8b956854df7203fe9e9a9c",
"templateId": "5a8bba8a8e79dc7da37f60a1",
"templateVariables": {
"caption1": "Summer Sale",
"image": "//rocketium.com/images/57544fcdd8fa816f2043e705/resized/1519188661549.png"
}
}
}
}

get
Get template rules

https://code.rocketium.com/v1/template/:id/rules
This will fetch all the rules defined for the template.
Request
Response
Request
Path Parameters
id
optional
string
ID of the template whose rules are to be fetched
Response
200: OK
The response will contain variables with keys of each variables. These can be passed to the Create video or Create image APIs.
{
"template": {
"type": "image",
"name": "Profile template"
},
"variables": {
"name": {
"type": "text",
"helpText": "Please enter your name",
"placeholder": "Jean-Luc Picard",
"maxCharacters": 50,
"editable": true
},
"image": {
"type": "image",
"helpText": "Please upload your picture",
"placeholder": "https://jeanluc.com/image.jpg",
"editable": true
},
}
}

get
Get stock content

https://api.rocketium.com/stock-content-search
This API lets you search millions of stock images and clips.
Request
Response
Request
Headers
access_token
required
string
Your API key
Query Parameters
query
required
string
Search query
media-type
optional
Type of media that you want. Can be one of image and video. By default only images will be returned.
page-number
optional
number
Results will be paginated into 20 results at a time. To fetch subsequent results, pass the appropriate page number.
included-sources
optional
string
Comma-separated list of sources that should be queried to get the images or videos. Allowed values are pexels, pixabay, unsplash, flickr, and storyblocks.
Response
200: OK
Message can be either successful or error. If it is successful, images will contain the search results. The structure of each search result is described in the table below.
Success
Success
{
"message": "successful",
"images": [{
"thumbnail": "https://website.com/....jpg",
"url": "https://website.com/....mp4",
"title": "Title of the image or video will be here",
"source": "VideoBlocks",
"source_url": "https://website.com/...",
"user": "videoblocks",
"videoId": 12345,
"tags": [ "activity", "close up" ]
},
{...}],
"page-number": 1
}

Please note that Unsplash and Flickr require attribution of their images.

Stock content search result object

Key

Type

Value

thumbnail

String

Thumbnail image URL that can be used for preview

url

String

URL that can be used to download the image or video

title

String

Title of the image or video

source

String

Source of the image or video. Some sources require attribution of the creator.

source_url

String

Original URL of the image or video

user

String

Name of the creator of the image or video

userName

String

Username of the creator of the image or video

videoId (only for video)

String

Internal identifier for the video that should be used to download the video

tags (only for video)

Array of String

Tags related to the video

get
Get color breakdown of an image

https://code.rocketium.com/v1/colors
A utility API to get details of colors in an image.
Request
Response
Request
Query Parameters
url
required
string
Publicly-accessible URL of the image whose colors are needed.
brightness
optional
boolean
Default value is false. If true, we return the brightness of the dominant color. light indicates a color that is closer to white and dark indicates a color closer to black.
allowedColors
optional
string
Comma-separated hex codes of colors. If specified, the returned colors will be mapped to the closest colors in this array. For example, if the colors in the image are #473679, #e3dcd6, #9e9fbf, #532826, #998ec6 and allowedColors is "#473679,#ff7f00,#000", the returned colors will be ["#473679", "#ff7f00", "#473679", "#000", "#473679" ]
ignoreBackground
optional
boolean
Default value is true. If true, we identify the background color and do not return it in the response.
palette
optional
boolean
Default value is false. If true, we return up to 4 additional colors in the image.
Response
200: OK
Success
Error
Success
{
"message": "successful",
"colors": {
"dominant": "#473679",
"background": "#050505",
"palette": [ "#E3DCD6", "#9E9FBF", "#532826", "#998EC6" ]
}
}
Error
{
"message": "error",
"details": "Image inaccessible"
}

get

https://code.rocketium.com/v1/colors
Request
Response
Request
Query Parameters
allowedColors
optional
string
#473679,#ff7f00,#000
Response
200: OK

get
Search images and videos

https://api.rocketium.com/search
This API allows you to find images and videos in your workspaces.
Request
Response
Request
Headers
access_token
required
string
Your API key
Query Parameters
query
optional
string
Search query to find images and videos. The API will look through titles, tags, and metadata fields of images and videos to find the matches.
media-type
optional
string
Type of media that you want. Can be one of image and video. By default both images and videos will be returned.
workspaceID
optional
string
ID of the workspace where you want to search for images or videos.
page-number
optional
number
Results will be paginated into 20 results at a time. To fetch subsequent results, pass the appropriate page number.
is-published
optional
boolean
Show only published video. Default is false.
Response
200: OK
Message will be either successful or error. If it is successful, the results object will have the structure as described in the table below.
Success
Success
{
"message": "successful",
"results": [{
"id": "12345",
"workspaceID": "7890",
"thumbnail": "https://rocketium.com/.../....jpg",
"url": "https://rocketium.com/.../....mp4",
"title": "Your creative's title will be here",
"type": "video",
"tags": "summer,stories,portrait,instagram",
"metadata": {"userID": "12345", "pageID": "abcde", "productID": "qwerty"}
},
{...}],
"page-number": 1
}

Result object

Key

Type

Value

id

String

Unique ID of the image or video.

workspaceId

String

ID of the workspace where the image or video exists.

thumbnail

String

Thumbnail image URL that can be used for preview.

url

String

URL that can be used to download the image or video.

title

String

Title of the image or video.

type

String

Either image or video.

tags

String

Comma-separated tags that are specified when creating the image or video.

metadata

object

Key-value pairs that are specified when creating the image or video.

page-number

number

Results will be paginated into 20 results at a time. This field specifies the page number of the current results.

delete
Delete video

https://api.rocketium.com/videos/:id
Delete a video using the id
Request
Response
Request
Path Parameters
id
required
string
ID of the video you want to delete. This is same as the `videoId` field returned in the response of the Create Video API.
Headers
access_token
required
string
Your API Key
Response
200: OK
The response from the API will contain a `message` field indicating success or error.
{
message: "successful"
}

delete
Delete Image

https://api.rocketium.com/videos/:id
Delete an image using the id
Request
Response
Request
Path Parameters
id
required
string
ID of the image you want to retrieve. This is the same as the videoId field returned in the response of the Create video API.
Headers
access_token
required
string
Your API Key
Response
200: OK
The response from the API will contain a `message` field indicating success or error
{
message: "successful"
}

Objects

Scene object

Key

Type

Value

image

String, Media object, Search result object

The image, GIF, or video to be shown in the scene. If a string is passed, it should be a publicly accessible link to the file.

text (optional)

String, Array of String, Text object, Array of Text object

Captions in the scene. Text can include HTML formatting tags h1, strong, and em.

delay (optional)

Number

Number of seconds by which all the captions in this scene should be delayed

multiplier (optional)

Number

Speed at which the text should be shown. See note on speed and calculation of caption duration.

styles (optional)

Scene styles object

Additional styles that should be applied to this scene. These styles will override styles specified in the theme.

audio (optional)

String, Text-to-speech API request data

URL of an mp3 file containing the voice-over for this scene. Can also share text and voice to create voice-over automatically by passing parameters for the text-to-speech API.

Media object

Key

Type

Value

url

String

URL of the image, GIF, or video. This should be publicly accessible. If using Google Drive, Dropbox, or other cloud storage links, ensure that the link is to the direct file not a page with comments and download / share buttons.

fullDuration (optional)

Boolean

If true, the video in the scene will play for its full duration. If false, it will play as long as the captions.

loop (optional)

Boolean

If true, the video in the scene will loop when its duration is shorter than the duration of the scene. If false, it will stop at its last frame instead of looping.

mute (optional)

Boolean

If true, the audio in the video in this scene will be muted.

user (optional)

String

Text attribution for the content owner. For example, Aaron (Unsplash) or HBO (Youtube).

access-type (optional)

String

Specify how the object should be accessed. Allowed value is secure-s3. Ensure that you have set the appropriate S3 policy.

icon (optional)

String

An icon to indicate the source of this image or video. This should be passed as an HTML snippet - <i class="ICON"></i>. Allowed values for ICON are:-

• r-credits-icon-image - image

• r-credits-icon-video-camera - video

• r-credits-icon-globe - webpage

• r-credits-icon-facebook - Facebook

• r-credits-icon-instagram - Instagram

• r-credits-icon-youtube - Youtube

fit (optional)

Boolean

Specify if the provided image be fit in the container or not.

mediaType (optional)

String

Specify the media type. Accepted values are map, image, and video.

mapDetails (optional)

Map object

Details of the map. Applicable if mediaType is map.

Map object

Map object can be provided in accordance to the Google Maps Apis.

Key

Type

Value

center

String

Defines the center of the map, equidistant from all edges of the map. This parameter takes a location as a comma-separated {latitude,longitude} pair (e.g. "40.714728,-73.998672") identifying a unique location on the face of the earth.

zoom

Integer

Defines the zoom level of the map, which determines the magnification level of the map. This parameter takes a numerical value corresponding to the zoom level of the region desired. For more information, see zoom levels.

size

String

Defines the rectangular dimensions of the map image. This parameter takes a string of the form {horizontal_value}x{vertical_value}. For example, 500x400 defines a map 500 pixels wide by 400 pixels high.

markers (optional)

Array

Array of Map Marker Objects.

style (optional)

Array

Defines a custom style to alter the presentation of a specific feature (roads, parks, and other features) of the map. The object details are in accordance to Snazzy Maps.

Map marker objects

Key

Type

Value

location (optional)

String

Provide the location to put the marker. If nothing is provided, map center will be used as the marker.

size (optional)

String

Specifies the size of marker from the set {tiny, mid, small}. If no size parameter is set, the marker will appear in its default (normal) size.

color (optional)

String

Specifies a hex code (example: color=#007EFF) or a predefined color from the set {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

label (optional)

String

Specifies a single uppercase alphanumeric character from the set {A-Z, 0-9}. Note that default and mid sized markers are the only markers capable of displaying an alphanumeric-character parameter. tiny and small markers are not capable of displaying an alphanumeric-character.

Text object

Key

Type

Value

text (optional)

String or Array of String

Captions in the scene. Text can include HTML formatting tags h1, strong, and em.

type (optional)

String

Can be one of caption, sticky, and lower-third.

delay (optional)

Number

Number of seconds by which all the caption should be delayed.

multiplier (optional)

Number

Speed at which the text should be shown. See note Caption timing calculation below.

styles (optional)

Text styles object

Additional styles that should be applied to this caption. These styles will override styles specified in the theme and the scene.

Caption timing calculation

A value of 1 is 15 characters/second. To set custom timing for text, send the appropriate multiplier.

Speed Multiplier = No. of characters in text/(display duration * 15)

Text styles object

Key

Type

Value

captionPosition

(optional)

Position object

Custom position for the caption. This will override the position that was specified in the theme.

layoutId

(optional)

String

Position for the caption from one of 9 positions in a grid. This will override the position that was specified in the theme. Allowed values are:-

image-heading-top-left

image-heading-top

image-heading-top-right

image-heading-center-left

image-heading-center

image-heading-center-right

image-heading-bottom-left

image-heading-bottom

image-heading-bottom-right

caption-background

(optional)

String

Link to a background that should be applied to this caption. This can be an image file (JPG, JPEG, or PNG), webm file, or a link to a motion graphic file returned by the Create motion graphic API.

textColor

(optional)

String

Custom color for the normal text of the captions. The values should be specified in hexcode, for example #FFFFFF.

highlightColor

(optional)

String

Custom color for the highlighted text in the captions. The values should be specified in hexcode, for example #007EFF.

backgroundColor

(optional)

String

Custom color for the background of the captions. The values should be specified in hexcode, for example #007EFF.

fontSize

(optional)

Number

Custom font size. Values will be in px, assuming the video height to be 1080px.

font

(optional)

String

URL of custom font file to be provided. The URL must be publicly accessible, failing which the font falls back to the default font.

Metadata Object

Lets you add additional information to the JSON that will be sent as metadata for your video in the webhook callback. Any additional string added to the metadata object will be sent as-is in the webhook callback

Key

Type

Value

targets

array

Array of objects representing individual shares to connected social platforms

timestamps

boolean

If true, then timestamps for individual scenes and the video duration will be returned in the callback JSON. Default value is false.

"timestamps": [ "0:00", "0:21", "0:36", "0:51"]

"duration": "1:03"

Position Object

Key

Type

Value

top

Integer

percentage value from 0 (topmost) to 100 (bottommost) for the right corner

bottom

Integer

percentage value from 0 (topmost) to 100 (bottommost) for the right corner

left

Integer

percentage value from 0 (leftmost) to 100 (rightmost) for the right corner

right

Integer

percentage value from 0 (leftmost) to 100 (rightmost) for the right corner

Scene styles object

Key

Type

Value

mediaPosition (optional)

Position object

Custom position for the media (image, video, or GIF) in the scene. This will override the position that was specified in the theme.

overlay (optional)

String

Link to the animated overlay that should be applied to this scene. This can be a PNG file, webm file, or a link to a motion graphic file returned by the Create motion graphic API.

transition (optional)

String

Link to the animated transition that should be applied to this scene.

This can be a PNG file, webm file, or a link to a motion graphic file returned by the Create motion graphic API.

focusPoint (optional)

String

Focus the media to a particular section, one of the following values : center, top, bottom, left or right.

sceneBackgroundColor (optional)

String

Custom background color for the scene. The values should be specified in hexcode, for example #FFFFFF.

Search result object

Key

Type

Value

thumbnail

String

Thumbnail image URL that can be used for preview

url

String

URL that can be used to download the image or video

title

String

Title of the image or video

source

String

Source of the image or video. Some sources like Unsplash and Flickr require attribution of the creator.

source_url

String

Original URL of the image or video

user

String

Name of the creator of the image or video

userName

String

Username of the creator of the image or video

videoId (only for video)

String

Internal identifier for the video that should be used to download the video

tags (only for video)

Array of String

Tags related to the video

Search result object

Key

Type

Value

id

String

Unique ID of the image or video

workspaceId

String

ID of the workspace where the image or video exists

thumbnail

String

Thumbnail image URL that can be used for preview

url

String

URL that can be used to download the image or video

title

String

Title of the image or video

type

String

One of image or video

tags

String

Comma-separated tags that are specified when creating the image or video

metadata

Object

Key-value pairs that are specified when creating the image or video

page-number

String

Results will be paginated into 20 results at a time. This field specifies the page number of the current results.

Webhook Callback

A webhook callback allows Rocketium to send the video/image details once it is successfully generated. You can execute next action in your workflow based on the successful response and the data received.

For setting up a webhook callback, please create a webhook API as per the specifications below and share it with your account manager. They will set this up for your Rocketium account.

API Implementation

REST

HTTP Method

POST

CallbackType

body

Headers

("Content-Type", "application/json")

Callback JSON

{"videoUrl" : "https://rocketium.com/video-download-url-goes-here", "videoId": "uniqueVideoId",

"thumbnailUrl": "https://rocketium.com/video-thumbnail-url-here", //if applicable "videoName" : "Name of your creative", "metadata" : { "key": "metadata passed to create API" }}

Expected Response

{ "videoId: "<uniqueVideoId>", "response": "Updated successfully" //Error details }