Receiving a generated video

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
curl -L \
  --url 'https://app.colossyan.com/api/v1/video-generation-jobs/{videoId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "videoId": "text",
  "progress": 1,
  "maximumProgress": 1,
  "status": "in_queue"
}

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
curl -L \
  --url 'https://app.colossyan.com/api/v1/generated-videos/{videoId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "id": "text",
  "jobId": "text",
  "publicUrl": "text",
  "thumbnailUrl": "text",
  "name": "text",
  "createdAt": "2025-02-13T19:57:46.562Z",
  "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. Navigate to workspace in which the API key was used to generate the video

  2. 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.

Last updated

Was this helpful?