> For the complete documentation index, see [llms.txt](https://docs.colossyan.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.colossyan.com/video-generation/video-generation/generating-a-video-manually.md).

# Generating a video manually

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](https://docs.colossyan.com/getting-started/publish-your-docs.md)
* Or to generate based on a template. More details here: [Generating using a template](https://docs.colossyan.com/video-generation/video-generation/generating-using-a-template.md)

***

### Important concepts

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

### Neo2 generations

To use Neo2 as the avatar generation technology instead of Neo, set the `videoCreative.settings.useNeo2Generation` to `true` in your request payload.

## Create a video generation job

> Submits a new video generation job for processing.

```json
{"openapi":"3.0.3","info":{"title":"Video Generation Job API","version":"1.0.0"},"servers":[{"url":"https://app.colossyan.com/api/v1","description":"V1 API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"VideoGenerationJob":{"type":"object","properties":{"dynamicVariables":{"type":"object","description":"Dynamic variables to be loaded into the template."},"callback":{"type":"string","description":"URL for the callback."},"callbackPayload":{"type":"object","description":"Payload for the callback."},"videoCreative":{"$ref":"#/components/schemas/VideoCreative","description":"The video creative details."}},"required":["videoCreative"]},"VideoCreative":{"type":"object","properties":{"settings":{"type":"object","properties":{"videoSize":{"type":"object","properties":{"width":{"type":"number","description":"Width of the video in pixels"},"height":{"type":"number","description":"Height of the video in pixels"}},"required":["width","height"]},"name":{"type":"string","description":"Name of the video"},"alphaChannel":{"type":"boolean","description":"Whether to attach the alpha-channel to the video or not. If true, only single-scene videos containing a single actor tracks are supported."},"useNeo2Generation":{"type":"boolean","description":"Whether to use Neo2 generation for avatars"}},"required":["videoSize","name"]},"scenes":{"type":"array","description":"List of scenes in the video","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the scene."},"duration":{"type":"number","description":"Duration of the scene."},"intrinsicDurationTrackReference":{"type":"string","description":"Reference to a track's referenceId in the scene. If the referenced track has a duration, the scene duration will be the same as the track duration."},"transition":{"$ref":"#/components/schemas/Transition"},"tracks":{"type":"array","description":"List of tracks in the scene.","items":{"oneOf":[{"$ref":"#/components/schemas/ActorTrack"},{"$ref":"#/components/schemas/ImageTrack"},{"$ref":"#/components/schemas/VideoTrack"},{"$ref":"#/components/schemas/TextTrack"},{"$ref":"#/components/schemas/AudioTrack"}]}}},"required":["tracks"]}}},"required":["settings","scenes"]},"Transition":{"type":"object","description":"The transition to use when transitioning to the next scene","properties":{"type":{"type":"string","description":"Type of transition.","enum":["fade","wipeleft","wiperight","wipeup","wipedown","smoothleft","smoothright","smoothup","smoothdown","circlecrop","rectcrop","circleopen","horzopen","vertopen","circleclose","horzclose","vertclose","slideleft","slideright","slideup","slidedown","hblur"]},"duration":{"type":"number","description":"Duration of the transition."}},"required":["type","duration"]},"ActorTrack":{"type":"object","description":"Represents an actor in the scene.","properties":{"type":{"type":"string","enum":["actor"],"description":"Type of track."},"variant":{"$ref":"#/components/schemas/ActorTrackVariant"},"view":{"$ref":"#/components/schemas/ActorView"},"actor":{"type":"string","description":"The name field of the actor"},"audioUrl":{"type":"string","description":"A publicly accessible URL to the audio file that the actor will speak."},"text":{"type":"string","description":"Text content for the actor to speak."},"speakerId":{"type":"string","description":"The name of the voice to use."},"position":{"$ref":"#/components/schemas/Position"},"size":{"$ref":"#/components/schemas/Size"},"rotation":{"$ref":"#/components/schemas/Rotation"},"referenceId":{"$ref":"#/components/schemas/ReferenceId"}}},"ActorTrackVariant":{"type":"string","enum":["full_body","bubble","shoulder"]},"ActorView":{"type":"string","enum":["front","side-front","side-back","sitting"]},"Position":{"type":"object","properties":{"x":{"type":"number","description":"X-coordinate of the track."},"y":{"type":"number","description":"Y-coordinate of the track."}}},"Size":{"type":"object","properties":{"width":{"type":"number","description":"Width of the track in pixels."},"height":{"type":"number","description":"Height of the pixels."}}},"Rotation":{"type":"number","description":"Rotation of the track. (-359 to 359)"},"ReferenceId":{"type":"string","description":"Reference ID of the track."},"ImageTrack":{"type":"object","description":"An embedded image in the scene.","properties":{"type":{"type":"string","enum":["IMAGE"],"description":"Type of track."},"imageUrl":{"type":"string","description":"A publicly accessible URL to the image file."},"position":{"$ref":"#/components/schemas/Position"},"size":{"$ref":"#/components/schemas/Size"},"rotation":{"$ref":"#/components/schemas/Rotation"},"referenceId":{"$ref":"#/components/schemas/ReferenceId"}}},"VideoTrack":{"type":"object","description":"An embedded video in the scene.","properties":{"type":{"type":"string","enum":["VIDEO"],"description":"Type of track."},"videoUrl":{"type":"string","description":"URL of the video."},"volume":{"type":"number","description":"Volume level."},"position":{"$ref":"#/components/schemas/Position"},"size":{"$ref":"#/components/schemas/Size"},"rotation":{"$ref":"#/components/schemas/Rotation"},"referenceId":{"$ref":"#/components/schemas/ReferenceId"}}},"TextTrack":{"type":"object","description":"An embedded text in the scene.","properties":{"type":{"type":"string","enum":["TEXT"],"description":"Type of track."},"text":{"type":"string","description":"Text content."},"fontSize":{"type":"number","description":"Font size."},"color":{"type":"string","description":"Color of the text."},"backgroundColor":{"type":"string","description":"Background color of the text."},"position":{"$ref":"#/components/schemas/Position"},"size":{"$ref":"#/components/schemas/Size"},"rotation":{"$ref":"#/components/schemas/Rotation"},"referenceId":{"$ref":"#/components/schemas/ReferenceId"}}},"AudioTrack":{"type":"object","description":"An embedded audio in the scene.","properties":{"type":{"type":"string","enum":["AUDIO"],"description":"Type of track."},"audioUrl":{"type":"string","description":"A publicly accessible URL to the audio file."},"volume":{"type":"number","description":"Volume level for the audio track."}}}}},"paths":{"/video-generation-jobs":{"post":{"summary":"Create a video generation job","description":"Submits a new video generation job for processing.","operationId":"createVideoGenerationJob","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoGenerationJob"}}}},"responses":{"200":{"description":"Job created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the created job."},"videoId":{"type":"string","description":"The provisioned ID of the generated video."}}}}}},"400":{"description":"Bad Request. Invalid input data."},"401":{"description":"Unauthorized. Authentication required."},"500":{"description":"Internal server error."}}}}}}
```

{% hint style="info" %}
For advanced use-cases and customisations (such as advanced timings or animations), please reach out to us, so we can help out with a solution engineer to make sure you achieve what you are after. Read more here: [Advanced use-cases](https://docs.colossyan.com/advanced/advanced-use-cases.md).
{% endhint %}
