Documentation

Rocketium Code opens up our platform so third-party developers can create and manipulate images and videos programmatically.
post
https://code.rocketium.com/v1
/videos
Create video

Create video error codes

message
Explanation
invalid token
The access token you specified in the header is not correct. The API key does not have access to the specified templateId
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 webchat to unblock this.
invalid user
The specified themeId does not exist or
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 webchat.
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 webchat.
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
https://code.rocketium.com/v1
/videos
Create image

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 specifiedthemeIddoes not exist.
Kindly enter a media for scene: 1
The imagefield is empty or absent.
invalid text for scene : 1 caption : 3
The textfield 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 webchat.
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
https://api.rocketium.com
/speech
Convert text to speech
post
https://api.rocketium.com
/workspaces
Create workspace
post
https://api.rocketium.com
/motion-graphics
Create motion graphic

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
https://api.rocketium.com
/share
Share

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
https://code.rocketium.com/v1/publish
Publish Video
get
https://api.rocketium.com
/videos/:id
Get video
get
https://api.rocketium.com
/videos/:id
Get image
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
https://api.rocketium.com/api
/v3/getTemplates
Get templates
get
https://api.rocketium.com/api
/v1/template/:id
Get template
get
https://code.rocketium.com
/v1/template/:id/rules
Get template rules
get
https://api.rocketium.com
/stock-content-search
Get stock content
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
https://code.rocketium.com
/v1/colors
Get color breakdown of an image
get
https://api.rocketium.com
/search
Search images and videos

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
https://api.rocketium.com
/videos/:id
Delete video
delete
https://api.rocketium.com
/videos/:id
Delete Image

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.
thumbnail (optional)
String
The thumbnail of the scene media. 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.

Element object

Key
Type
value
type
String
String value denoting the caption type. Example - sticky, caption.
url
String
URL of the element media. Must be publicly accessible.
elementType
String
Type of media element. One of image or video
thumbnail (optional)
String
The thumbnail of the media. It should be a publicly accessible link.

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)
String
Specify if the provided image be fit or fill 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
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-to-speech object

Key
Type
Value
text
String
Text to convert to speech. If this contains SSML tags, the pass textType as ssml.
voice
String
Voice in which the voice should speak. Some supported values are - in-female1, us-female1, us-male1, uk-female1, uk-male1. The complete list of voices is available at https://docs.aws.amazon.com/polly/latest/dg/voicelist.html for Amazon Polly voices and https://cloud.google.com/text-to-speech/docs/voices for Google voices
textType (optional)
String
Allowed value is ssml.

Text styles object

Key
Type
Value
captionPosition
(optional)
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. This can be used to add identifier tags or identifiers to the video.
The metadata object can also be used to trigger auxiliary functions such as sharing to a connected YouTube or Facebook page.
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
Float
percentage value from 0 (topmost) to 100 (bottommost) for the right corner (can take negative values if an element is partially outside the frame)
bottom
Float
percentage value from 0 (topmost) to 100 (bottommost) for the right corner
left
Float
percentage value from 0 (leftmost) to 100 (rightmost) for the right corner (can take negative values if an element is partially outside the frame)
right
Float
percentage value from 0 (leftmost) to 100 (rightmost) for the right corner

Scene styles object

Key
Type
Value
mediaPosition (optional)
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", // for videos
"imageUrl" : "https://rocketium.com/video-download-url-goes-here", // for images "videoId": "uniqueVideoId",
"thumbnail": "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 }