Colossyan API Documentation

Getting started

Getting started

Colossyan's API is authenticated with a token sent with each request. Contact us to request one.

Our API endpoint is available at:

https://app.colossyan.com/api/

The best way to start is by generating a few sample videos:

Example: Simple video

const token = "2fd3b795-15d4-456f-9a33-33391d1cfcf0";
const url = "https://app.colossyan.com/api/video-generation-jobs";
const job = {
videoCreative: {
settings: {
name: "My first video",
videoSize: {
height: 1080,
width: 1080,
},
},
scenes: [
{
name: "My first scene with an actor in it",
tracks: [
{
type: "actor",
actor: "ryan",
position: { x: 0, y: 0 }, // From the top left in pixels
size: { height: 1080, width: 1080 }, // In pixels
text: "This is my first video generated with Colossyan! Amazing!",
speakerId: "en-GB-RyanNeural",
removeBackground: true,
},
],
},
],
},
};
const response = await fetch(url, {
method: "POST",
headers: {
authorizationtoken: token,
"Content-Type": "application/json",
},
body: JSON.stringify(job),
});
const result = await response.json();
console.log(result); // { id, videoId }

The video

In the snippet above, we posted a new video generation job. Let's walk through what we should expect the generated video to look like.

  • It will have an aspect ratio of 1080 x 1080
  • It will consist of a single scene
  • We added an actor track to it, with our own video.
    • We configured the actor to say This is my first video generated with Colossyan! Amazing! in the voice of en-GB-RyanNeural.
    • The actor track is set to be 1080 x 1080 pixel in size and it should be as large as the video itself
    • We removed its background. (Since nothing is behind it, we should expect the background to be black)

The generated video

The return value

Upon posting a new video generation job we receive the newly queued job id and the video id. We can use the job id to poll the status of the video.

const token = "2fd3b795-15d4-456f-9a33-33391d1cfcf0";
const jobId = "650c585a-c55c-468e-ab71-e73a405af5a7";
const url = `https://app.colossyan.com/api/video-generation-jobs/${jobId}`;
async function pollStatus() {
const response = await fetch(url, {
headers: { authorizationtoken: token },
"Content-Type": "application/json",
});
const result = await response.json();
const status = result.status;
if (status !== "finished" && status !== "failed") {
console.log(`Video status: ${status}`);
setTimeout(pollStatus, 5000);
} else {
console.log(result); // { status, videoId }
}
}
pollStatus();

When the video is generated the status will turn to finished and we can retrieve the details of the video by its id.

const token = "2fd3b795-15d4-456f-9a33-33391d1cfcf0";
const videoId = "1fdc44da-bc42-4ae1-9bb1-5564b4bd0ed3";
const url = `https://app.colossyan.com/api/generated-videos/${videoId}`;
const response = await fetch(url, {
headers: {
authorizationtoken: token,
"Content-Type": "application/json",
},
body: JSON.stringify(job),
});
const result = await response.json();
console.log(result); // { publicUrl, name, shareId }

Example: Complex scenario

In the following example we queue a job just like in the previous case, but this time, we utlise a lot more of Colossyans power. We create a video that consists of 6 scenes, each scene consisting of multiple tracks. We use advanced concepts such as background removal, seamless concatenation between scenes and dynamic variables.

Each of these concepts are explained in details in the documentation.

const token = "2fd3b795-15d4-456f-9a33-33391d1cfcf0"
const url = "https://app.colossyan.com/api/video-generation-jobs"
const job = {
dynamicVariables: {
firstName: "Peter",
daytime: "afternoon",
dayOfWeek: "Monday"
}
videoCreative: {
settings: {
name: "Complex video example",
videoSize: {
height: 1080,
width: 1920,
}
},
scenes: [
{
name: "Scene 1",
intrinsicDurationTrackReference: "actor-track",
tracks: [
{
type: 'video',
position: { x: 0, y: 0 },
sequentialBlendId: "background",
size: { height: 1080, width: 1920 },
videoUrl: "https://colossyan-cdn.s3.eu-west-2.amazonaws.com/videos/backgrounds/news.mp4",
},
{
type: 'actor',
actor: "ryan",
position: {
x: 100,
y: 580,
},
size: {
height: 500,
width: 800,
},
removeBackground: true,
text: "Good {daytime} {firstName}! Here are the latest news from all around the world!",
speakerId: "en-GB-RyanNeural",
referenceId: "actor-track",
sequentialBlendId: "actor",
},
],
},
{
name: "Scene 2",
intrinsicDurationTrackReference: "actor-track",
tracks: [
{
type: 'video',
position: { x: 0, y: 0 },
sequentialBlendId: "background",
size: { height: 1080, width: 1920 },
videoUrl: "https://colossyan-cdn.s3.eu-west-2.amazonaws.com/videos/backgrounds/news.mp4",
},
{
type: 'actor',
actor: "ryan",
position: {
x: 100,
y: 580,
},
size: {
height: 500,
width: 800,
},
removeBackground: true,
text: "Two teens are facing homicide charges in connection with a fatal crash in madison. Police believe the vehicle that six teens were in friday night was stolen… And that the crash occurred after a fight over the steering wheel.",
speakerId: "en-GB-RyanNeural",
referenceId: "actor-track",
sequentialBlendId: "actor",
},
{
type: 'image',
position: { x: 970, y: 150 },
size: { height: 600, width: 800 },
imageUrl: "https://cdn.pixabay.com/photo/2016/03/07/09/34/kid-1241817_1280.jpg",
startTimeGap: 1,
endTimeGap: 1,
},
],
},
{
name: "Scene 3",
intrinsicDurationTrackReference: "actor-track",
tracks: [
{
type: 'video',
position: { x: 0, y: 0 },
sequentialBlendId: "background",
size: { height: 1080, width: 1920 },
videoUrl: "https://colossyan-cdn.s3.eu-west-2.amazonaws.com/videos/backgrounds/news.mp4",
},
{
type: 'actor',
actor: "ryan",
position: {
x: 100,
y: 580,
},
size: {
height: 500,
width: 800,
},
removeBackground: true,
text: "Surveillance cameras in East China’s Bozhou city have captured how a traffic cop, with the help of commuters, brought an out-of-control electronic rickshaw, or e-rickshaw, to a stop.",
speakerId: "en-GB-RyanNeural",
referenceId: "actor-track",
sequentialBlendId: "actor",
},
{
type: 'image',
position: { x: 970, y: 150 },
size: { height: 600, width: 800 },
imageUrl: "https://cdn.pixabay.com/photo/2019/12/14/12/08/night-4694750_1280.jpg",
startTimeGap: 1,
endTimeGap: 1,
},
],
},
{
name: "Scene 4",
intrinsicDurationTrackReference: "actor-track",
tracks: [
{
type: 'video',
position: { x: 0, y: 0 },
sequentialBlendId: "background",
size: { height: 1080, width: 1920 },
videoUrl: "https://colossyan-cdn.s3.eu-west-2.amazonaws.com/videos/backgrounds/news.mp4",
},
{
type: 'actor',
actor: "ryan",
position: {
x: 100,
y: 580,
},
size: {
height: 500,
width: 800,
},
removeBackground: true,
text: "Sridevi died at age 54 in Dubai reportedly after cardiac arrest. As the news of her death broke, Twitter was soon flooded with condolences and many of her fans refused to believe the shocking news.",
speakerId: "en-GB-RyanNeural",
referenceId: "actor-track",
sequentialBlendId: "actor",
},
{
type: 'image',
position: { x: 970, y: 150 },
size: { height: 600, width: 800 },
imageUrl: "https://cdn.pixabay.com/photo/2014/11/14/21/24/woman-531252_1280.jpg",
startTimeGap: 1,
endTimeGap: 1,
},
],
},
{
name: "Scene 5",
intrinsicDurationTrackReference: "actor-track",
tracks: [
{
type: 'video',
position: { x: 0, y: 0 },
sequentialBlendId: "background",
size: { height: 1080, width: 1920 },
videoUrl: "https://colossyan-cdn.s3.eu-west-2.amazonaws.com/videos/backgrounds/news.mp4",
},
{
type: 'actor',
actor: "ryan",
position: {
x: 100,
y: 580,
},
size: {
height: 500,
width: 800,
},
removeBackground: true,
text: "One of Australia’s top police officers has quit after being linked to crude racist, sexist, and pornographic online posts that his boss described Tuesday as “shocking”.",
speakerId: "en-GB-RyanNeural",
referenceId: "actor-track",
sequentialBlendId: "actor",
},
{
type: 'image',
position: { x: 970, y: 150 },
size: { height: 600, width: 800 },
imageUrl: "https://cdn.pixabay.com/photo/2015/07/31/15/01/security-869216_1280.jpg",
startTimeGap: 1,
endTimeGap: 1,
},
],
},
{
name: "Scene 6",
intrinsicDurationTrackReference: "actor-track",
tracks: [
{
type: 'video',
position: { x: 0, y: 0 },
sequentialBlendId: "background",
size: { height: 1080, width: 1920 },
videoUrl: "https://colossyan-cdn.s3.eu-west-2.amazonaws.com/videos/backgrounds/news.mp4",
},
{
type: 'actor',
actor: "ryan",
position: {
x: 100,
y: 580,
},
size: {
height: 500,
width: 800,
},
removeBackground: true,
text: "Thank you for tooning in {firstName}, enjoy your {dayOfWeek} {daytime}.",
speakerId: "en-GB-RyanNeural",
referenceId: "actor-track",
sequentialBlendId: "actor",
},
],
}
]
}
}
const result = await fetch(url, {
method: "POST",
headers: {
authorizationtoken: token,
'Content-Type': 'application/json',
},
body: JSON.stringify(job),
});
const result = await response.json();
console.log(result) // { id, videoId }

The video

The following job yields the video below.

Watch the video while examining the video job definition, to reference what configuration yielded what in the video.

Edit this page on GitHub