Receiving a generated video

There are three ways to get a video, that was generated via our APIs.

1. You can get notified via our callback once a video is ready (recommended in production)

2. You can poll it using other API endpoints

3. You can download the video from your Colossyan Account after navigating to the workspace where the API key was created.

Callback

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:

Key	Description
url	Contains the public url of the generated video file.
videoUrl and shareUrl	Contains a unique url pointing at Colossyans video sharing platform.
status	The status of the video generation. Can either be finished or failed
...and everything that was provided at the job's generation as callbackPayload and dynamicVariables.

Polling

Due to the asynchronous nature of video-generations, first you need to query the video-generation-job itself, to see the status of it. To do this, use the API below.

Get video generation job status

Retrieves the status, progress, and details of a specific video generation job.

GEThttps://app.colossyan.com/api/v1/video-generation-jobs/{videoId}

Authorization

bearerAuth

Path parameters

videoId*string

The ID of the video generation job.

Response

200400401404500

Video generation job status and details retrieved successfully. The return value also contains all of the video-generation-job itself, which is not detailed here.

Body

application/json

statusenum

The current status of the video generation job.

in_queuepreprocessingpreprocessing_finishedgeneratingfinishedfaileddeleted

videoIdstring

The ID of the provisioned generated video

progressnumber

The current progress of the video generation job.

maximumProgressnumber

The maximum progress value of the video generation job.

Request

JavaScriptCurlPython

const response = await fetch('https://app.colossyan.com/api/v1/video-generation-jobs/{videoId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200

{
  "status": "in_queue",
  "videoId": "text",
  "progress": 0,
  "maximumProgress": 0
}

Continue to poll the status of the job, until it returns either finished or failed. In case it successfully finished generating use the API below to get the generated video.

• You can get the videoId both when queueing the job itself, or when fetching it's status.

Get details of a generated video

Retrieves detailed information about a specific generated video.

GEThttps://app.colossyan.com/api/v1/generated-videos/{videoId}

Authorization

bearerAuth

Path parameters

videoId*string

The ID of the generated video.

Response

200400401404500

Generated video details retrieved successfully

Body

application/json

idstring

The unique identifier of the generated video.

jobIdstring

The ID of the video generation job that created this video.

publicUrlstring

The public URL of the generated video.

thumbnailUrlstring

URL of the video's thumbnail.

namestring

The name of the video.

createdAtstring (date-time)

The date and time the video was created.

videoSizeBytesnullable number

The size of the video in bytes.

videoDurationSecondsnullable number

The duration of the video in seconds.

Request

JavaScriptCurlPython

const response = await fetch('https://app.colossyan.com/api/v1/generated-videos/{videoId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200

{
  "id": "text",
  "jobId": "text",
  "publicUrl": "text",
  "thumbnailUrl": "text",
  "name": "text",
  "createdAt": "2025-01-11T06:21:37.676Z",
  "videoSizeBytes": 0,
  "videoDurationSeconds": 0
}

An example of a script to poll a job can be found below:

const token = "<your-token-here>";
const jobId = "<your-job-id-here>";
const videoId = "<your-video-id-here>";
const jobUrl = `https://app.colossyan.com/api/v1/video-generation-jobs/${jobId}`;
const videoUrl = `https://app.colossyan.com/api/v1/generated-videos/${videoId}`;

async function pollStatus() {
  const jobResponse = await fetch(jobUrl, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
  });
  const result = await jobResponse.json();
  const status = result.status;

  if (status !== "finished" && status !== "failed") {
    console.log(
      `Video status: ${status}, progress: ${result.progress}/${result.maximumProgress}`
    );
    setTimeout(pollStatus, 5000); // Retry every 5 seconds
  } else {
    const videoResponse = await fetch(videoUrl, {
      method: "GET",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
    });

    const result = await videoResponse.json();
    console.log(result);
  }
}

pollStatus();

Getting the video from the Colossyan App

1. Open Colossyan
2. Navigate to workspace in which the API key was used to generate the video

3. Open the generated videos page.

   1. The video should be listed there

   2. You should also see it if it's currently being generated. In this case, it'll show the status of the job.