Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Stable features
https://app.colossyan.com/api/v1Experimental features
https://app.colossyan.com/apiColossyan's API offers a programmable video creation service. It allows you to generate videos at scale. To facilitate this, we provide a REST API using standard JSON as request and response payload format. This way you can integrate our service into any technology stack.
💬 Over 600 voices
🌐 Over 70 languages
👄 Use any actor of your choice
👤 Create your own avatars through the API, and use them at your will
⚖️ Generate template videos at a massive scale, easily
📹 Everything that you can generate in the Colossyan Studio you can also generate via our API
🖼️ Embedded images
🎬 Embedded videos
🎶 Embedded audios
📞 Get notified immediately via a callback mechanism
💅 Thanks to our web-based templating and payload exporting options it's incredibly easy to get up-n-running.
Colossyan's API is using . This means, that every request has to be authenticated by sending the token in the Authorization header pre-pended by the text Bearer . See the example below:
You can create or find your existing tokens at the bottom of the Workspace details tab .
🔤 Embedded texts
Each token belongs to a specific workspace. This is where are the generated videos that you create through the API will be listed. To keep things tidy, it is recommended to create a specific workspace for each use-case for the API.
const response = await fetch(`${api}/video-generation-jobs`, {
method: "POST",
headers: {
Authorization: `Bearer ${token}`, // Authentication
"Content-Type": "application/json",
},
body: JSON.stringify(job),
});Using the API, you can list the following assets:
To create a new "instant" avatar please see the following page:
Constructing request bodies for complex video generation jobs can become very complicated very quickly. To get ahead of this we provide a way to use our web-based video-generation tool (Colossyan Studio) to export the payload for the video you see.
To do this, open any draft you'd like to generate via the API.
Click on the "Generate" button on the top right corner of your editor, than in the dialog appeared you should see a button called "Export to API", click that button.
Note that you can only see this button if you have API access.
In the appearing modal, you should see the request body that you can send to generate the exact video that you can see in the editor.
Feel free to customise this payload.
The endpoint will return the available avatars for your workspace.
The types of avatars the endpoint will return:
Studio: Avatars provided by Colossyan.
Scenario: Also provided by Colossyan, but shown with a specific scenario background.
Instant: Custom-made avatars. To learn how to create one using the API, check out the following page ⇒
There are multiple ways to generate a video.
You can generate a video based on a template (that you create). In this case you only send us a reference to the template and a list of dynamic variables that you'd like us to replace in the template. See more here:
You can generate a video, by sending a whole video-generation-job descriptor JSON to our API. See more here:
Once a video generation has been triggered, you have multiple options to get notified once it's ready. See more here: Receiving a generated video
ssa_lite/ssa_studio: These are also custom-made avatars. To learn more, visit this link.
Important: Scenario and Instant avatars are not included by default. To access them, please contact support.
There are two different inference models supported by the API (returned by the supportedInferenceModel parameter):
legacy
neo
There are three different avatar variants supported by the API (returned by the supportedActorTrackVariant parameter):
full_body
bubble
shoulder
Important: Not all inference models support all avatar variants.
full_body
✅
❌
bubble
✅
✅
shoulder
✅
✅
You can generate a video by sending us a video-generation-job descriptor JSON. This is essentially a recipe for a video. Constructing such a recipe manually for complex videos can become tedious very quickly. Due to this we strongly recommend to either:
Extract the video-generation-job payload from our web-based UI editor. More details here: Extracting request bodies from the web-editor
Or to generate based on a template. More details here: Generating using a template
To better understand the API, it's recommended to get an understanding of the following building blocks first:
Scenes
A scene is a logical consolidation of related content.
A video can consist of multiple scenes. These scenes are concatenated together. Think of them as slides on a presentation. Each scene is meant to aggregate and encapsulate related content.
Scenes offer a lot of convenience in timing their content, however it is completely up to the individual to decide how to divide the content into scenes.
Here you can see the details of the endpoint below.
To generate a video based on a template:
Head over to Colossyan and create your desired video draft using our web-based studio
Once you are done, click on the "Generate" button on the top right corner of your editor, than in the dialog appeared click "Export to API"
A video generation job holds data respective the video generation.
For example by retrieving the generation job you can tell which status the video generation is currenlty in. (e.g. generating, finished, failed)
Throught the API it is possible to retrieve or delete a video that was already generated.
In general, we always recommend to generate videos either by:
Extracting the video-generation-job payload from our web-based UI editor. More details here: Extracting request bodies from the web-editor.
If for some reason either of these options wouldn't be enough to achieve what you are after, in the following pages you can read about some advanced concepts, when working with our API.
Tracks
Tracks are the building blocks of scenes. You define the content of the video in tracks.
There are different types of tracks, for different purposes. To differentiate between them we use the type property.
On the top right corner of the appearing dialog click "Save job as a template" and make note of the appearing ID. This is the ID of your template job, you can send this id with your request to start generate the video.
Keep in mind: the template job ID refers to the state of the draft when you saved it. If later you edit this draft, you'll need to create another template id to represent the changes.
Now you have everything to send us a video generation request using the API endpoint below.
You can create an "instant" avatar by sending an image or video link to the API. The avatar will be generated based on the provided media.
The API will return the avatar's name, which can then be used for generating video with the avatar.
You can create dynamic template variables in the script on any scene, by simply typing a variable name between curly braces at any point of the script.
For example in the following script...
,,,
Dear {name}, I have seen that you haven't logged into your account for the past two months. Should we catch up quickly? Since then we released several cool stuff, such as {cool_stuff_1} and {cool_stuff_2}. Let me know if you have a free slot on your calendar next week!
,,,
...you have created three dynamic variables:
Experimental endpoints are not yet finalised. They can change at any point, without notice. To reflect this, these endpoints are not available on the /v1/ endpoint (See more here: )
You can use dynamic template variables in any text element, by simply typing a variable name between curly braces.
Take the following example:
,,,
Hey {name}, we’ve been improving!
Our newest feature, {feature_name}, is live!
,,,
In this text we created two template variables: name and feature_name .
const token = "<paste-your-token-here>";
const api = "https://app.colossyan.com/api/v1";
const job = {
videoCreative: {
settings: {
name: "My first video",
videoSize: {
width: 1920,
height: 1080
}
},
scenes: [
{
tracks: [
{
type: "actor",
position: { x: 420, y: 0 },
size: { width: 1080, height: 1080 },
actor: "karen",
text: "This is my first video generated with Colossyan! Amazing!",
speakerId: "aquXcfLbkxpW4BBI5qKm"
}
]
}
]
}
};
const response = await fetch(`${api}/video-generation-jobs`, {
method: "POST",
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json",
},
body: JSON.stringify(job),
});
const result = await response.json();
console.log(result); // { id, videoId }Dynamic template variables are placeholders within your video script or scene text element that can be replaced with different values each time a video is generated.
They allow you to customize content dynamically without modifying the base template.
Learn more on the following pages on how to use them:
namecool_stuff_1
cool_stuff_2
You can replace these template variables with their values, by sending their values in the request body when generating a video. The API will replace the placeholders in the script with the corresponding values you provide.
For example:
On how to generate a video you can find more information here: Video Generation
You can replace these template variables with their values, by sending their values in the request body when generating a video. The API will replace the placeholders in the text with the corresponding values you provide.
For example:
On how to generate a video you can find more information here: Video Generation
{
"dynamicVariables": {
"name": "John",
"feature_name": "AI-powered task automation",
},
// other request parameters...
}{
"dynamicVariables": {
"name": "John",
"cool_stuff_1": "AI-powered task automation",
"cool_stuff_1": "Slack & Google Calendar integration",
},
// other request parameters...
}We configured the actor to say This is my first video generated with Colossyan! Amazing! using the voice of aquXcfLbkxpW4BBI5qKm.
The actor is set to be 1080px * 1080px in size and it's top-left will be in the (420;0) coordinates, counting from the top-left, resulting in the actor being in the middle of the video.
You can download the video from your Colossyan Account after navigating to the workspace where the API key was created.
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:
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.
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:
Open Colossyan
Navigate to workspace in which the API key was used to generate the video
Open the generated videos page.
The video should be listed there
You should also see it if it's currently being generated. In this case, it'll show the status of the job.
Deleting a video generation job will stop the video generation processing.
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();Fetches a list of voices that the user has access to.
A list of voices
Unauthorized. Authentication required.
Internal server error.
GET /api/v1/assets/voices HTTP/1.1
Host: app.colossyan.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"sample": "text",
"genders": [
"text"
],
"characters": [
"text"
],
"name": "text",
"ages": [
"text"
],
"features": {
"pitch": true,
"emphasize": true,
"pause": true,
"speed": true
},
"style": "text",
"scenarios": [
"text"
],
"displayName": "text",
"languages": [
"text"
],
"isClonedVoice": true
}
]Dynamic variables to be loaded into the template.
URL for the callback.
Payload for the callback.
Job created successfully
Bad Request. Invalid input data.
Unauthorized. Authentication required.
Internal server error.
POST /api/v1/video-generation-jobs HTTP/1.1
Host: app.colossyan.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 505
{
"dynamicVariables": {},
"callback": "text",
"callbackPayload": {},
"videoCreative": {
"settings": {
"videoSize": {
"width": 1,
"height": 1
},
"name": "text",
"alphaChannel": true
},
"scenes": [
{
"name": "text",
"duration": 1,
"intrinsicDurationTrackReference": "text",
"transition": {
"type": "fade",
"duration": 1
},
"tracks": [
{
"type": "actor",
"variant": "full_body",
"view": "front",
"actor": "text",
"audioUrl": "text",
"text": "text",
"speakerId": "text",
"position": {
"x": 1,
"y": 1
},
"size": {
"width": 1,
"height": 1
},
"rotation": 1,
"referenceId": "text"
}
]
}
]
}
}{
"id": "text",
"videoId": "text"
}The ID of the generated video.
Generated video details retrieved successfully
Bad Request. Invalid videoId parameter.
Unauthorized. Authentication required.
Not Found. Generated video not found.
Internal server error.
The ID of the template job.
Dynamic variables to be loaded into the template.
URL for the callback after job completion.
Callback payload to return with the generated video once it's ready.
Job created successfully
Bad Request. Invalid input data.
Unauthorized. Authentication required.
Internal server error.
Generates and creates a draft using structured textual data.
The ID of the template to use. If not provided, the system will randomly select one.
Draft generated and created successfully
Bad Request. Invalid input data.
Unauthorized. Authentication required.
Internal server error.
Retrieves the status, progress, and details of a specific video generation job.
The ID of the video generation job.
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.
Bad Request. Invalid videoId parameter.
Unauthorized. Authentication required.
Not Found. Video generation job not found.
Internal server error.
Retrieves detailed information about a specific generated video.
The ID of the generated video.
Generated video details retrieved successfully
Bad Request. Invalid videoId parameter.
Unauthorized. Authentication required.
Not Found. Generated video not found.
Internal server error.
GET /api/v1/generated-videos/{videoId} HTTP/1.1
Host: app.colossyan.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
POST /api/v1/video-generation-jobs/template-jobs HTTP/1.1
Host: app.colossyan.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 88
{
"templateJobId": "text",
"dynamicVariables": {},
"callbackUrl": "text",
"callbackPayload": {}
}The ID of the generated video.
Video deleted successfully
Bad Request. Invalid videoId parameter.
Unauthorized. Authentication required.
Not Found. Generated video not found.
Internal server error.
No content
You can set the duration of each scene in three different ways. In either case no matter how long the duration of the tracks within the scene are, everything longer than the scene itself will be cut out.
You can explicitly define the scene's duration in milliseconds by setting the duration property on it.
If you would like your scene to be exactly as long as one of the tracks in it, you can do so by referring to the track on the scene. In this case Colossyan will try to figure out the length of the track in isolation first, and if it can do so, it'll assign the same duration to the scene itself.
Use the intrinsicDurationTrackReference property in the scene to refer to the referenceId of the track you would like the scene to have an equal duration with.
Combining this technique with timing the tracks by referring to the scene's start and end time is a very powerful combination, that allows you to achieve intricate videos with the flexibility of handing varying track lengths.
If you do not explicitly set the duration, nor refer to a track within the scene, Colossyan will try to infer the best guess for the duration of the scene by looking at the tracks, and trying to find a single one with either an intrinsic or explicitly set duration.
This is only possible if there is only one track in the scene with a default or explicitly set duration. Otherwise Colossyan will throw a schema validation error, when queueing the job.
Track duration can be set in three different ways. No matter which way you chose, if the scene is shorter, the track will be cut to fit it.
If however the track you provided does not last long enough to reach the duration defined by you (for example a video ends earlier, or the actor finishes speaking), the track will disappear earlier than you defined.
Similarly to setting a scene's explicit duration, you can set the duration of a track by setting the duration property on it. The duration should be set in milliseconds.
You can set the track to start after a certain amount of time has passed since the beginning of the scene, and to last until a certain amount of time before the end of the scene. By setting both of these variables, you are essentially defining the duration of the track as well.
You can define these gaps from the start and end of the scene by setting the startTimeGap and the endTimeGap properties on the track.
If you do not define the duration of the track in any way, Colossyan will try to fall back to the intrinsic duration of the track if there is any.
Only video and actor tracks have intrinsic durations.
In case of a video track the intrinsic duration equals the duration of the video itself.
In case of an actor track the intrinsic duration equals the duration of the lipsynched video of the actor speaking.
To time when the track should start or end within the scene, you can use the startTimeGap or the endTimeGap properties on the track.
Use startTimeGap and endTimeGap to make videos that work well for dynamic content.
Refer to the track's duration in scenes to deal with dynamic track lengths.
Do not over-constrain the timing of your scenes and tracks. This will yield in a schema validation error.
DELETE /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-12-14T01:33:31.825Z",
"videoSizeBytes": 1,
"videoDurationSeconds": 1
}{
"id": "text",
"videoId": "text"
}{
"url": "text"
}POST /api/knowledge-to-draft/generate-draft HTTP/1.1
Host: app.colossyan.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 136
{
"summary": {
"title": "text",
"description": "text",
"chapters": [
{
"title": "text",
"script": "text",
"searchTerms": "text"
}
]
},
"templateId": "text"
}{
"status": "in_queue",
"videoId": "text",
"progress": 1,
"maximumProgress": 1
}GET /api/v1/video-generation-jobs/{videoId} HTTP/1.1
Host: app.colossyan.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
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-12-14T01:33:31.825Z",
"videoSizeBytes": 1,
"videoDurationSeconds": 1
}const job = {
videoCreative: {
settings: {
name: "Simple video with a single scene",
videoSize: { height: 1080, width: 1920 },
},
scenes: [
{
name: "Scene with explicit duration",
duration: 2000, // ms
tracks: [
{
type: "actor",
position: { x: 200, y: 200 }, // From the top left in pixels
size: { height: 680, width: 1520 }, // In pixels
text: "This scene is exactly two seconds long. It does not matter how long any of the tracks are.",
speakerId: "en-GB-RyanNeural",
actor: "ryan",
},
],
},
],
},
};const job = {
videoCreative: {
settings: {
name: "Simple video with a single scene",
videoSize: { height: 1080, width: 1920 },
},
scenes: [
{
name: "This scene lasts until the actor stops speaking",
intrinsicDurationTrackReference: "speech",
tracks: [
{
type: "actor",
referenceId: "speech",
position: { x: 200, y: 200 }, // From the top left in pixels
size: { height: 680, width: 1520 }, // In pixels
text: "It does not matter how long I am talking. The scene will last as long as necessary.",
speakerId: "en-GB-RyanNeural",
actor: "ryan",
},
],
},
],
},
};const job = {
videoCreative: {
settings: {
name: "Simple video with a single scene",
videoSize: { height: 1080, width: 1920 },
},
scenes: [
{
name: "This scene defaults to last until the end of the video",
tracks: [
{
type: "video",
position: { x: 200, y: 200 }, // From the top left in pixels
size: { height: 680, width: 1520 }, // In pixels
videoUrl: "https://your.cdn.com/public/videos/some_video.mp4",
},
],
},
],
},
};const job = {
videoCreative: {
settings: {
name: "Simple video with a single scene",
videoSize: { height: 1080, width: 1920 },
},
scenes: [
{
name: "Scene with a single track with an explicitly set duration",
tracks: [
{
type: "image",
duration: 3000, // in ms
position: { x: 200, y: 200 }, // From the top left in pixels
size: { height: 680, width: 1520 }, // In pixels
imageUrl: "https://your.cdn.com/public/videos/image.jpg",
},
],
},
],
},
};const job = {
videoCreative: {
settings: {
name: "Simple video with a single scene",
videoSize: { height: 1080, width: 1920 },
},
scenes: [
{
name: "Scene with a single track with a duration set by startTimeGap and endTimeGap",
duration: 5000,
tracks: [
{
type: "image",
startTimeGap: 1000, // ms
endTimeGap: 2000, // ms
position: { x: 200, y: 200 }, // From the top left in pixels
size: { height: 680, width: 1520 }, // In pixels
imageUrl: "https://your.cdn.com/public/videos/image.jpg",
},
],
},
],
},
};const job = {
videoCreative: {
settings: {
name: "Simple video with a single scene",
videoSize: { height: 1080, width: 1920 },
},
scenes: [
{
name: "Scene with a single track with an intrinsic duration",
tracks: [
{
type: "video",
position: { x: 200, y: 200 }, // From the top left in pixels
size: { height: 680, width: 1520 }, // In pixels
imageUrl: "https://your.cdn.com/public/videos/some_video.mp4",
},
],
},
],
},
};Creates a new avatar from the sent properties.
Name to be displayed for the avatar
URL to the video or image file for the avatar to be created from
Avatar created successfully.
Bad Request. Invalid input data.
Unauthorized. Authentication required.
Internal server error.
GET /api/v1/assets/actors HTTP/1.1
Host: app.colossyan.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
The ID of the video generation job.
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.
No content
Bad Request. Invalid videoId parameter.
Unauthorized. Authentication required.
Not Found. Video generation job not found.
Internal server error.
No content
DELETE /api/v1/video-generation-jobs/{videoId} HTTP/1.1
Host: app.colossyan.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"name": "text",
"display_name": "text",
"preview_url": "text",
"version": "v1",
"type": "Studio",
"gender": "Male",
"age": 1,
"ethnicity": "Caucasian",
"clothing_style": "Casual",
"quality": "lite",
"emotions": [
"text"
],
"default_voice": "text",
"views": [
{
"viewVariantType": "front",
"aspectRatio": {
"height": 1,
"width": 1,
"ratio": 1
},
"supportedActorTrackVariants": [
"full_body"
],
"supportedInferenceModels": [
"legacy"
],
"pictarSourceUrl": "text",
"images": {
"thumbnail": "text",
"editor": "text",
"editor-happy": "text",
"editor-sad": "text"
},
"videos": {
"base": "text",
"baseTransparent": "text",
"dynamicPreviewUrl": "text"
},
"bubbleVariantDefaults": {
"crop": {
"left": 1,
"top": 1,
"right": 1,
"bottom": 1
}
},
"shoulderVariantDefaults": {
"crop": {
"left": 1,
"top": 1,
"right": 1,
"bottom": 1
}
}
}
],
"features": {
"side_view": true,
"emotions": true,
"hand_gesture": true
}
}
]{
"name": "text"
}POST /api/v1/assets/actors HTTP/1.1
Host: app.colossyan.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 61
{
"displayName": "text",
"sourceFileUrl": "text",
"gender": "Male"
}The ID of the video generation job.
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.
Bad Request. Invalid videoId parameter.
Unauthorized. Authentication required.
Not Found. Video generation job not found.
Internal server error.
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
}