Receiving a generated video

PreviousGenerating a video manually NextUsing template variables

Last updated 4 months ago

Was this helpful?

Receiving a generated video

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

You can get notified via our callback once a video is ready (recommended in production)
You can poll it using other API endpoints
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.

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.

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

Navigate to workspace in which the API key was used to generate the video
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.

PreviousGenerating a video manually NextUsing template variables

Last updated 4 months ago

Was this helpful?

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

You can get notified via our callback once a video is ready (recommended in production)
You can poll it using other API endpoints
You can download the video from your Colossyan Account after navigating to the workspace where the API key was created.

Callback

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.

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.

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

Open
Navigate to workspace in which the API key was used to generate the video
.
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.

Get details of a generated video

get

Retrieves detailed information about a specific generated video.

Authorizations

Path parameters

videoIdstringRequired

The ID of the generated video.

Responses

200

Generated video details retrieved successfully

application/json

400

Bad Request. Invalid videoId parameter.

401

Unauthorized. Authentication required.

404

Not Found. Generated video not found.

500

Internal server error.

get

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": "2025-05-18T13:17:55.617Z",
  "videoSizeBytes": 1,
  "videoDurationSeconds": 1
}

Get video generation job status

get

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