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.

get

/video-generation-jobs/{videoId}

Authorizations

Path parameters

videoIdstringrequired

The ID of the video generation job.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://app.colossyan.com/api/v1/video-generation-jobs/{videoId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

400

401

404

500

200

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

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.

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.

get

/generated-videos/{videoId}

Authorizations

Path parameters

videoIdstringrequired

The ID of the generated video.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://app.colossyan.com/api/v1/generated-videos/{videoId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

400

401

404

500

200

{
  "id": "text",
  "jobId": "text",
  "publicUrl": "text",
  "thumbnailUrl": "text",
  "name": "text",
  "createdAt": "2025-02-21T18:02:56.341Z",
  "videoSizeBytes": 1,
  "videoDurationSeconds": 1
}

Generated video details retrieved successfully

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.