---
title: "Create a new Video"
method: POST
path: "/videos"
---

# Create a new Video

`POST /videos`

Creates a new Video with the specified details

## Request body

- VideoCreateArgs
  - `name` string, required
  - `moments` object[], required — An array of Moment items, each representing a portion of the complete video.
    - `transcript` string, required — A portion of the complete transcript. Current limit: 250 characters
    - `avatarId` string, required — The id of the avatar to be used for this moment
    - `voiceId` string — The id of the voice to be used for this moment. Optional, default is the avatar's voice.
    - `gestureSlug` string — The slug identifier of the gesture to be used for this moment
    - `audioUrl` string — Optional url to the audio to be used for the video rendering, for bypassing our audio generation model. Current limit: 20 seconds
    - `zoom` object — Controls the zoom level of the viewport/display, allowing content to be scaled larger or smaller
      - `level` number, required — Specifies the zoom scaling factor where 1.0 represents 100% (original size), and 2.0 is 200% (zoomed in)
  - `subtitles` object — Subtitles settings for the video
    - `enable` boolean, required
    - `styleId` string — ID of the subtitle style to apply. Styles can be fetched from the /subtitles endpoint.
    - `position` 'Top' | 'Middle' | 'Bottom' — Position of subtitles on the video
    - `size` 'Small' | 'Medium' | 'Large' — Size of the subtitle text
  - `aspectRatio` '16:9' | '9:16' — Select desired output aspectRatio: 16:9 or 9:16. Optional, default depends on used avatar.
  - `enableAutoBrolls` boolean — [DEPRECATED] Enable automatic B-roll generation and placement. When enabled, the system will analyze your content and automatically add relevant B-rolls to appropriate moments.
  - `autoBrolls` object — Configuration for automatic B-roll generation and placement.
    - `enable` boolean, required — Enable or disable automatic B-roll generation.
    - `source` 'GENERATION' | 'GOOGLE_IMAGES' | 'STOCKS_VIDEO' | 'AVATAR_ACTION', required — Source for B-rolls: 'GENERATION' for generated images or 'GOOGLE_IMAGES' for images from Google, 'STOCKS_VIDEO' for GettyImages videos or 'AVATAR_ACTION' for generated videos including the avatar (only available with AI Influencer avatars).
    - `intensity` 'LOW' | 'MEDIUM' | 'HIGH', required — Intensity level of B-rolls: 'LOW', 'MEDIUM', or 'HIGH'. Not available for 'AVATAR_ACTION' source.
    - `layout` 'FULLSCREEN' | 'AVATAR_BOTTOM_LEFT' | 'AVATAR_BOTTOM_RIGHT' | 'AVATAR_TOP_LEFT' | 'AVATAR_TOP_RIGHT' | 'SPLIT_AVATAR_LEFT' | 'SPLIT_AVATAR_RIGHT' | 'SPLIT_AVATAR_TOP' | 'SPLIT_AVATAR_BOTTOM' | 'BACKGROUND' — Layout control for moments containing a B-roll. Controls how the B-rolls appears relative to the avatar.
  - `extras` object — Optional dictionary of custom key-value pairs to extend the video metadata. Maximum of 5 key-value pairs of 256 characters allowed
  - `backgroundMusic` object — Optional configuration for background music
    - `assetId` string, required — ID of an audio asset to use as background music
    - `volume` number — Volume level of the background music (0-1). Default is 0.14
  - `model` 'ARGIL_V1' | 'ARGIL_ATOM' — Model to use for the video generation.

## Response `201`

Successfully created Video

- Video
  - `id` string, uuid
  - `name` string
  - `createdAt` string, date-time
  - `updatedAt` string, date-time
  - `status` string — Can be either `IDLE`, `GENERATING_AUDIO`, `GENERATING_VIDEO`, `DONE` or `FAILED`.
  - `moments` object[] — An array of Moment items, each representing a portion of the complete video.
    - `transcript` string — A portion of the complete transcript. Current limit: 250 characters.
    - `avatarId` string — The id of the avatar to be used for this moment.
    - `voiceId` string — The id of the voice to be used for this moment.
    - `audioUrl` string — The audio that will be used for the video rendering. Automatically generated from the transcript when not provided. Current limit: 20 seconds.
    - `videoUrl` string — The url of the avatar rendering video for this moment.
    - `gestureSlug` string — The slug identifier of the gesture to be used for this moment.
  - `videoUrl` string — The url of the final avatar rendering video, containing all the moments merged.
  - `videoUrlSubtitled` string — The url of the final avatar rendering video with subtitles. Only available if subtitles are enabled.
  - `subtitles` object — Subtitles settings for the video
    - `enable` boolean
  - `extras` object — A dictionary of custom key-value pairs to extend the video metadata. Maximum of 5 key-value pairs of 256 characters allowed.

## Other responses

- `400` — Validation error

## Changes

- **2025-11-06** `4c7879813e4f` — 1 info
  - added the new optional request property `model`
- **2025-09-01** `6f180dc8aab4` — 1 info
  - added the new optional request property `autoBrolls/layout`
- **2025-07-09** `f965cd17ef70` — 3 info
  - added the new optional request property `subtitles/position`
  - added the new optional request property `subtitles/size`
  - added the new optional request property `subtitles/styleId`
- **2025-04-11** `d1e55b861d6e` — 2 info
  - added the new `AVATAR_ACTION` enum value to the request property `autoBrolls/source`
  - added the new `STOCKS_VIDEO` enum value to the request property `autoBrolls/source`
- **2025-02-03** `5efa1099f4d7` — 1 info
  - the request property `moments/items/voiceId` became optional

[Full history](https://skmtc.dev/argildotai/apis/argil-api/changes/videos/post.md)

---

[API](https://skmtc.dev/argildotai/apis/argil-api.md) · [All operations](https://skmtc.dev/argildotai/apis/argil-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/argildotai/argil-api/revisions/48a779d9f736/schema)