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

get

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

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

videoIdstringRequired

The ID of the video generation job.

Responses

200

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.

application/json

statusstring · enumOptional

The current status of the video generation job.

Possible values:

videoIdstringOptional

The ID of the provisioned generated video

progressnumberOptional

The current progress of the video generation job.

maximumProgressnumberOptional

The maximum progress value of the video generation job.

400

Bad Request. Invalid videoId parameter.

401

Unauthorized. Authentication required.

404

Not Found. Video generation job not found.

500

Internal server error.

get

/video-generation-jobs/{videoId}

HTTPcURLJavaScriptPython

GET /api/v1/video-generation-jobs/{videoId} HTTP/1.1
Host: app.colossyan.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

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

get

Retrieves detailed information about a specific generated video.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

videoIdstringRequired

The ID of the generated video.

Responses

200

Generated video details retrieved successfully

application/json

idstringOptional

The unique identifier of the generated video.

jobIdstringOptional

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

publicUrlstringOptional

The public URL of the generated video.

thumbnailUrlstringOptional

URL of the video's thumbnail.

namestringOptional

The name of the video.

createdAtstring · date-timeOptional

The date and time the video was created.

videoSizeBytesnumber · nullableOptional

The size of the video in bytes.

videoDurationSecondsnumber · nullableOptional

The duration of the video in seconds.

400

Bad Request. Invalid videoId parameter.

401

Unauthorized. Authentication required.

404

Not Found. Generated video not found.

500

Internal server error.

get

/generated-videos/{videoId}

HTTPcURLJavaScriptPython

GET /api/v1/generated-videos/{videoId} HTTP/1.1
Host: app.colossyan.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "jobId": "text",
  "publicUrl": "text",
  "thumbnailUrl": "text",
  "name": "text",
  "createdAt": "2026-06-09T06:37:23.187Z",
  "videoSizeBytes": 1,
  "videoDurationSeconds": 1
}

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.