docs/videos

Video Generation

Create short video clips from text prompts with one authenticated API call.

Overview

Video generation fits workflows such as campaign clips, motion concepts, and social assets. Explore it in the Video Studio, or choose media units in video packages.

Quick start

Use the same sk-ag-* API key accepted by the other API endpoints.

bash

curl https://api.aggregate.ai/v1/videos/generations   -H "Authorization: Bearer sk-ag-..."   -H "Content-Type: application/json"   -d '{
    "model": "video-standard",
    "prompt": "A paper boat sailing through a glowing forest stream",
    "n": 1,
    "aspect_ratio": "16:9",
    "duration": 4
  }'

Slow path: Video generation is slow (~30s per clip). For batches always use POST /v1/batches and poll.

Request body

Name	Type	Required	Default	Description
model	string	yes	—	Video model ID from the model catalog.
prompt	string	yes	—	Text description of the video.
n	integer	no	1	Number of videos. Values greater than 1 use POST /v1/batches; see the batch guide.
aspect_ratio	string	no	16:9	Requested aspect ratio: 16:9, 9:16, or 1:1.
duration	integer	no	4	Clip length in seconds. Must be 4, 6, or 8.
seed	integer	no	random	Seed for reproducible generation when supported by the model.
negative_prompt	string	no	none	Content or visual qualities to avoid.

Response body

json

{
  "data": [{ "url": "https://.../video.mp4" }],
  "created": 1760000000
}

The url points to the generated MP4 video file. For batch requests, poll GET /v1/batches/{id} for the result.

Errors

402	Insufficient units.
404	Video model not found.
400	Invalid generation request or unsupported duration or aspect ratio.
422	Validation error in the request body.

Pricing

Each video generation consumes fixed media units determined by the selected model and media package. See video package pricing.

Models

Use a video model whose public catalog modality is video. The available IDs and provider metadata are listed in the video models section of Models.

Endpoint schema and duration validation: services/api-proxy/app/routers/videos.py:65-79, 155-174.