Colossyan API Documentation

Getting video

Getting video

You can either use the callback mechanism to get notified when your video is ready, or you can poll the video generation job to get its status.

We recommend using the callback mechanism for the following reasons:

  • it allows a nicer separation of concerns
  • it inherently protects from stucking in an infite loop in case an error happens during video generation
  • the video generation can take excessive amount of time in case our servers are under heavy load. This can end up causing your service to hang for a long time, even potentially timeout.


Upon posting a new video generation job, you have the opportunity to add a callback and some callbackPayload to the job. When the job is successful our service will issue a POST request to the url you provided in the callback field.

In the body of this post message, we add the following fields:

urlContains the public url of the generated video file
shareUrlContains a unique url pointing at Colossyan-s video sharing platform. You can use this link to share the video with anyone.

Apart from these fields, we also attach all the values you provided in the callbackPayload field, when posting the job. This helps your server side callback handler mechanism to get some context about the generated video.

Do not provide any sensitive information in the callbackPayload!


Polling is there to speed up development efforts and it allows you to get access to your generated videos without having to spin up your own server.

We do not recommend implementing polling in a production system!

Once you have the job id, you can poll the status by issuing a GET request to the following endpoint. (Replace {jobId} with your actual job id).{jobId}

The returned object will have the following properties:

statusThe status of the job. It can be any of the following: in_queue, preprocessing, preprocessing_finished, generating, finished, failed, deleted
videoIdThe id of the video the job will produce or has produced.
progressThe amount of progress the job has completed during its runtime.
maximumProgressThe amount of progress it takes to generate the video. Hint: use progress / maximumProgress to calculate the progress percentage.

Getting the video URL

When a job is finished, you can call the following endpoint to retrieve the resulting video's URL and other properties. (Replace {videoId} with the video id in the job object).{videoId}

The returned object will have the following properties:

publicUrlThe public URL of the video. This can be accessed without the need of authentication.
shareIdUse this to share the video on Colossyan's video sharing platform:{shareId}
videoSizeBytesThe video's file size in bytes.
videoDurationSecondsThe video's duration in seconds.


import fetch from "node-fetch";
const token = "your-token-here";
const jobId = "your-job-id-here";
const jobUrl = `${jobId}`;
async function pollStatus() {
const response = await fetch(jobUrl, {
headers: { authorizationtoken: token },
const result = await response.json();
const status = result.status;
if (status !== "finished" && status !== "failed") {
`Video status: ${status}, progress: ${result.progress}/${result.maximumProgress}`
setTimeout(pollStatus, 5000);
} else {
const videoUrl = `${result.videoId}`;
const response = await fetch(videoUrl, {
headers: { authorizationtoken: token },
const video = await response.json();
Edit this page on GitHub