---
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 — A portion of the complete transcript. Mutually exclusive with `audioUrl` — provide one or the other, not both. Current limit: 500 characters
    - `audioUrl` string — URL to an audio file for this moment, bypassing TTS generation. Mutually exclusive with `transcript` — provide one or the other, not both. Max duration: 40 seconds
    - `avatarId` string, required — The id of the avatar to be used for this moment
    - `voice` object — The voice for this moment, with optional per-generation model and settings overrides. Replaces the legacy `voiceId`/`voiceModel` fields — provide either `voice` or those legacy fields, not both.
      - `id` string, required — The id of the voice to use for this moment.
      - `model` string — Optional override for the voice's default TTS model. Must be compatible with the voice's provider; defaults to the voice's stored model when omitted. ElevenLabs: eleven_multilingual_v2, eleven_multilingual_v1, eleven_monolingual_v1, eleven_turbo_v2, eleven_turbo_v2_5, eleven_flash_v2_5, eleven_v3 Minimax: speech-02-hd, speech-02-turbo, speech-2.5-hd-preview, speech-2.5-turbo-preview, speech-2.6-hd, speech-2.6-turbo, speech-2.8-hd, speech-2.8-turbo
      - `settings` object — Per-generation voice settings, validated against the resolved model. Overrides the voice's stored defaults. ElevenLabs: voiceStability, voiceSimilarity, voiceStyle (0-1), voiceSpeed (0.7-1.2), speakerBoost (bool). eleven_v3 accepts voiceStability/voiceSimilarity/voiceStyle/voiceSpeed only. Minimax: voiceSpeed (0.7-1.2), languageBoost, emotion.
        - `voiceStability` number — 0-1. For ElevenLabs voices, controls consistency vs. expressiveness (lower = more variable).
        - `voiceSimilarity` number — 0-1. ElevenLabs only.
        - `voiceStyle` number — 0-1. ElevenLabs only.
        - `voiceSpeed` number — 0.7-1.2. Playback speed.
        - `speakerBoost` boolean — ElevenLabs standard models only.
        - `languageBoost` string — Minimax only.
        - `emotion` string — Minimax only.
    - `voiceId` string — [LEGACY] The id of the voice to be used for this moment. Optional, default is the avatar's voice. Prefer the `voice` object. Cannot be combined with `voice`.
    - `voiceModel` string — [LEGACY] Optional override for the voice's default TTS model. Prefer `voice.model`. Cannot be combined with `voice`. Must be compatible with the voice's provider. ElevenLabs voices: eleven_multilingual_v2, eleven_multilingual_v1, eleven_monolingual_v1, eleven_turbo_v2, eleven_turbo_v2_5, eleven_flash_v2_5, eleven_v3 Minimax voices: speech-02-hd, speech-02-turbo, speech-2.5-hd, speech-2.5-turbo, speech-2.6-hd, speech-2.6-turbo, speech-2.8-hd, speech-2.8-turbo
    - `gestureSlug` string — The slug identifier of the gesture to be used for this moment
    - `zoom` Zoom — Zoom animation defined by keyframes. A single keyframe applies a constant zoom. Multiple keyframes animate smoothly between values.
      - `keyframes` object[], required — List of zoom keyframes. Minimum 1, maximum 20.
        - `time` number, required — Position in the moment's timeline (0 = start, 1 = end). Relative to moment duration.
        - `scale` number, required — Zoom scale factor. 1.0 = no zoom (100%), 2.0 = 200%, 3.0 = 300%.
        - `easing` number[] — Cubic bezier easing curve [x1, y1, x2, y2] (CSS convention). Omit for linear interpolation. Ignored on the first keyframe.
    - `broll` union — Per-moment B-roll configuration. Specify the B-roll type and optional parameters for an individual moment. When `prompt` or `query` is omitted, it is auto-generated from the moment's transcript via LLM.
      - object — Generate a video B-roll featuring the avatar in action. Only available with AI Influencer (IMAGE-type) avatars. Costs 40 credits for image generation plus 4 credits/second for animation.
        - `type` 'AVATAR_ACTION', required
        - `prompt` string — Describes the scene/pose for the avatar image (first frame). Auto-generated from the moment's transcript when omitted.
        - `motionPrompt` string — Describes how the avatar moves/animates in the video. When omitted, falls back to `prompt` value, or is auto-generated from the transcript.
        - `productImageAssetId` string, uuid — ID of an uploaded product image (from `POST /assets`, must be READY status and IMAGE type). The product is passed as a reference image to the first-frame generation so the avatar appears with the actual product (e.g. holding your branded bottle with a readable label).
        - `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 controlling how the B-roll appears relative to the avatar.
        - `zoom` Zoom — Zoom animation defined by keyframes. A single keyframe applies a constant zoom. Multiple keyframes animate smoothly between values.
          - `keyframes` object[], required — List of zoom keyframes. Minimum 1, maximum 20.
            - `time` number, required — Position in the moment's timeline (0 = start, 1 = end). Relative to moment duration.
            - `scale` number, required — Zoom scale factor. 1.0 = no zoom (100%), 2.0 = 200%, 3.0 = 300%.
            - `easing` number[] — Cubic bezier easing curve [x1, y1, x2, y2] (CSS convention). Omit for linear interpolation. Ignored on the first keyframe.
      - object — Generate an AI image as a B-roll. Consumes 10 image generation credits per moment.
        - `type` 'GENERATION', required
        - `prompt` string — Describes the image to generate. Auto-generated from the moment's transcript when omitted.
        - `animate` boolean — Animate the generated image. Default: false.
        - `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 controlling how the B-roll appears relative to the avatar.
        - `zoom` Zoom — Zoom animation defined by keyframes. A single keyframe applies a constant zoom. Multiple keyframes animate smoothly between values.
          - `keyframes` object[], required — List of zoom keyframes. Minimum 1, maximum 20.
            - `time` number, required — Position in the moment's timeline (0 = start, 1 = end). Relative to moment duration.
            - `scale` number, required — Zoom scale factor. 1.0 = no zoom (100%), 2.0 = 200%, 3.0 = 300%.
            - `easing` number[] — Cubic bezier easing curve [x1, y1, x2, y2] (CSS convention). Omit for linear interpolation. Ignored on the first keyframe.
      - object — Use a Getty Images stock video as a B-roll.
        - `type` 'STOCKS_VIDEO', required
        - `query` string — Search query for Getty Images. Auto-generated from the moment's transcript when omitted.
        - `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 controlling how the B-roll appears relative to the avatar.
        - `zoom` Zoom — Zoom animation defined by keyframes. A single keyframe applies a constant zoom. Multiple keyframes animate smoothly between values.
          - `keyframes` object[], required — List of zoom keyframes. Minimum 1, maximum 20.
            - `time` number, required — Position in the moment's timeline (0 = start, 1 = end). Relative to moment duration.
            - `scale` number, required — Zoom scale factor. 1.0 = no zoom (100%), 2.0 = 200%, 3.0 = 300%.
            - `easing` number[] — Cubic bezier easing curve [x1, y1, x2, y2] (CSS convention). Omit for linear interpolation. Ignored on the first keyframe.
      - object — Use a Google Images result as a B-roll.
        - `type` 'GOOGLE_IMAGES', required
        - `query` string — Search query for Google Images. Auto-generated from the moment's transcript when omitted.
        - `animate` boolean — Animate the found image. Default: false.
        - `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 controlling how the B-roll appears relative to the avatar.
        - `zoom` Zoom — Zoom animation defined by keyframes. A single keyframe applies a constant zoom. Multiple keyframes animate smoothly between values.
          - `keyframes` object[], required — List of zoom keyframes. Minimum 1, maximum 20.
            - `time` number, required — Position in the moment's timeline (0 = start, 1 = end). Relative to moment duration.
            - `scale` number, required — Zoom scale factor. 1.0 = no zoom (100%), 2.0 = 200%, 3.0 = 300%.
            - `easing` number[] — Cubic bezier easing curve [x1, y1, x2, y2] (CSS convention). Omit for linear interpolation. Ignored on the first keyframe.
      - object — Use a previously uploaded asset as B-roll. The asset must have status READY and be of type IMAGE or VIDEO. Upload assets via `POST /assets`.
        - `type` 'UPLOAD', required
        - `assetId` string, uuid, required — ID of the uploaded asset (from `POST /assets`). Must be READY status and IMAGE or VIDEO type.
        - `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 controlling how the B-roll appears relative to the avatar.
        - `zoom` Zoom — Zoom animation defined by keyframes. A single keyframe applies a constant zoom. Multiple keyframes animate smoothly between values.
          - `keyframes` object[], required — List of zoom keyframes. Minimum 1, maximum 20.
            - `time` number, required — Position in the moment's timeline (0 = start, 1 = end). Relative to moment duration.
            - `scale` number, required — Zoom scale factor. 1.0 = no zoom (100%), 2.0 = 200%, 3.0 = 300%.
            - `easing` number[] — Cubic bezier easing curve [x1, y1, x2, y2] (CSS convention). Omit for linear interpolation. Ignored on the first keyframe.
  - `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`.
  - `duration` number, nullable — Total video duration in seconds. `null` when audio hasn't been generated yet.
  - `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: 500 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: 40 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.
    - `zoom` object — Current zoom effect applied to the avatar. Present only when a non-default zoom is set.
    - `broll` object — B-roll information for this moment.
      - `zoom` object — Current zoom effect applied to the B-roll. Present only when a non-default zoom is set.
  - `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.
  - `previewUrl` string — Url to the embedable preview of the video. Can be watched from web browsers or integrated in other websites before launching the generation. For embedable mode, add ?embed=true to the url.
  - `aspectRatio` '16:9' | '9:16' — The aspect ratio of the video output: 16:9 or 9:16.
  - `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

- **2026-06-15** `f3d0315da0f0` — 1 info
  - added the new optional request property `moments/items/voice`
- **2026-06-11** `dece0a05f750` — 1 warning
  - removed the request property `moments/items/broll/oneOf[subschema #1: AVATAR_ACTION]/useAvatarAsStartFrame`
- **2026-06-11** `516367d77f83` — 2 info
  - added the new optional request property `moments/items/broll/oneOf[subschema #1: AVATAR_ACTION]/productImageAssetId`
  - added the new optional request property `moments/items/broll/oneOf[subschema #1: AVATAR_ACTION]/useAvatarAsStartFrame`
- **2026-04-20** `166231bcfa85` — 1 info
  - added the optional property `duration` to the response with the `201` status
- **2026-04-16** `3e376c91df56` — 1 warning, 1 info
  - removed the optional property `duration` from the response with the `201` status
  - added `subschema #5: UPLOAD` to the `moments/items/broll` request property `oneOf` list

[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/f3d0315da0f0/schema)