Colossyan API Documentation
Getting video
Getting video
You can either use the callback mechanism to get notified when your video is ready, or you can poll the video generation job to get its status.
We recommend using the callback mechanism for the following reasons:
- it allows a nicer separation of concerns
- it inherently protects from stucking in an infite loop in case an error happens during video generation
- the video generation can take excessive amount of time in case our servers are under heavy load. This can end up causing your service to hang for a long time, even potentially timeout.
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 |
| shareUrl | Contains a unique url pointing at Colossyan-s video sharing platform. You can use this link to share the video with anyone. |
Apart from these fields, we also attach all the values you provided in the callbackPayload field,
when posting the job. This helps your server side callback handler mechanism to get some context about
the generated video.
Do not provide any sensitive information in the callbackPayload!
Polling
Polling is there to speed up development efforts and it allows you to get access to your generated videos without having to spin up your own server.
- To poll the status of the job you will need the job id. You can get this job id in the response object when posting a new video generation job.
We do not recommend implementing polling in a production system!
Once you have the job id, you can poll the status by issuing a GET request to the
following endpoint. (Replace {jobId} with your actual job id).
https://app.colossyan.com/api/video-generation-jobs/{jobId}The returned object will have the following properties:
| Key | Description |
|---|---|
| status | The status of the job. It can be any of the following: in_queue, preprocessing, preprocessing_finished, generating, finished, failed, deleted |
| videoId | The id of the video the job will produce or has produced. |
| progress | The amount of progress the job has completed during its runtime. |
| maximumProgress | The amount of progress it takes to generate the video. Hint: use progress / maximumProgress to calculate the progress percentage. |
Getting the video URL
When a job is finished, you can call the following endpoint to retrieve the resulting video's URL and other properties. (Replace {videoId} with the video id in the job object).
https://app.colossyan.com/api/generated-videos/{videoId}The returned object will have the following properties:
| Key | Description |
|---|---|
| publicUrl | The public URL of the video. This can be accessed without the need of authentication. |
| shareId | Use this to share the video on Colossyan's video sharing platform: https://app.colossyan.com/share/{shareId} |
| videoSizeBytes | The video's file size in bytes. |
| videoDurationSeconds | The video's duration in seconds. |
Example
import fetch from "node-fetch";
const token = "your-token-here";const jobId = "your-job-id-here";const jobUrl = `https://app.colossyan.com/api/video-generation-jobs/${jobId}`;
async function pollStatus() { const response = await fetch(jobUrl, { headers: { authorizationtoken: token }, }); const result = await response.json(); const status = result.status;
if (status !== "finished" && status !== "failed") { console.log( `Video status: ${status}, progress: ${result.progress}/${result.maximumProgress}` ); setTimeout(pollStatus, 5000); } else { const videoUrl = `https://app.colossyan.com/api/generated-videos/${result.videoId}`; const response = await fetch(videoUrl, { headers: { authorizationtoken: token }, }); const video = await response.json(); console.log(video); }}
pollStatus();