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 the theme to be used to apply styles. This is linked to a specific templateId and should not be changed
teamId
optional
string
ID of workspace where the exported creative should be saved. If this is not specified, the creative will be saved to the last active workspace. Please talk to your account manager to get this ID.
title
optional
string
Title of the creative. This will be visible in your workspace. Failing to provide a name results in an "untitled" name assigned automatically to the creative.
logo
optional
object
Object containing- URL of image to be usedd as logo, position, and size.
logoCustomPosition
optional
object
Used to provide custom position values other than the preset positions for the 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 array in the JSON, you can pass data for individual variables in the template (if defined). If this is provided, scenes array 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
themeId
required
string
ked to a specific templateId and should not be changed
Response
200: OK
​
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
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
required
string
Your API key
Content-Type
required
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 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
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. If this contains SSML tags, then pass textType as ssml.
provider
optional
string
Text to speech provider that should be used. Can be one of amazon, google, lovo.
metadata
optional
string
Additional metadata that should be sent to the text-to-speech provider. Any content passed here will be sent as-is to the text-to-speech provider.
voice
required
string
Voice that should be used for the conversion.

Example values can be found at https://docs.aws.amazon.com/polly/latest/dg/voicelist.html and https://cloud.google.com/text-to-speech/docs/voices and https://api-doc.lovo.ai.
textType
optional
string
Allowed value is ssml.
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 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
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 videoBlocks.
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.
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
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-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)
​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. 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)
​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
}
​

Code - Banner, video creation API - Previous

Quick start

Next - Code - Banner, video creation API

FAQ

Last updated 2 months ago

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`.

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`.

`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.

`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 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.

`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`

`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`.

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

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.

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.

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.

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`.

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.

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

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.


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 }`

Documentation

postCreate video

post​

Create video error codes

postCreate image

Create image error codes

postConvert text to speech

postCreate workspace

postCreate motion graphic

Create motion graphics error codes

postShare

Share Object

Share error codes

postPublish Video

getGet video

getGet image

getGet templates

getGet template

getGet template rules

getGet stock content

Stock content search result object

getGet color breakdown of an image

get​

getSearch images and videos

Result object

deleteDelete video

deleteDelete Image

Objects

Scene object

Element object

Media object

Map object

Map marker objects

Text object

Text-to-speech object

Text styles object

Metadata Object

Position Object

Scene styles object

Search result object

Search result object

Webhook Callback

post
Create video

post

post
Create image

post
Convert text to speech

post
Create workspace

post
Create motion graphic

post
Share

post
Publish Video

get
Get video

get
Get image

get
Get templates

get
Get template

get
Get template rules

get
Get stock content

get
Get color breakdown of an image

get

get
Search images and videos

delete
Delete video

delete
Delete Image