---
title: "Create a video from a brief or your own script"
method: POST
path: "/videos"
tags: ["Videos"]
---

# Create a video from a brief or your own script

`POST /videos`

## Request

- Base URL: `https://app.makeaivideo.ai/api/v1`
- URL: `https://app.makeaivideo.ai/api/v1/videos`
- Auth: HTTP bearer

## Request body

- CreateVideo: Send either tool + fields, or script. Not both.
  - `tool` string: Path A: a tool id from GET /tools; we write the script
  - `fields` object
  - `duration_seconds` integer
  - `script` object: Path B: your own script (from /videos/script, /videos/scriptify, or hand-written)
    - `title` string, required
    - `hook` string, required
    - `visual_thread` string
    - `total_duration_seconds` number, required
    - `hashtags` string[]
    - `scenes` object[], required
      - `scene_number` integer, required
      - `narration` string, required
      - `visual_description` string, required
      - `duration_seconds` number, required
      - `scene_type` 'character' | 'scene'
      - `image_prompt` string
      - `video_prompt` string
  - `title` string
  - `topic` string
  - `mode` 'talking-head' | 'cinematic' | 'hybrid' | 'stock-narrated' | 'smart-mix'
  - `style` 'talking-head' | 'cinematic'
  - `character_id` integer, nullable
  - `voice_id` string
  - `music_id` string
  - `caption_style` string
  - `aspect_ratio` '9:16' | '1:1' | '16:9'
  - `language` string
  - `start_generation` boolean
  - `idempotency_key` string: Same key = same video. Set it when retrying.
  - `video_model` string: Optional. Leave it unset and MakeAIVideo picks the best video model for each scene.

## Response `202`

Accepted. status is `generating`, or `draft` when start_generation is false

- object
  - `data` VideoCreated
    - `video_id` string
    - `status` 'generating' | 'draft'
    - `title` string, nullable
    - `scene_count` integer, nullable
    - `poll_after_seconds` integer, nullable
    - `next` string
  - `error` unknown
  - `meta` Meta
    - `request_id` string
    - `timestamp` string, date-time

## Other responses

- `400`: Invalid brief or script
- `402`: Not enough credits or no active subscription
- `403`: Key lacks the write scope
- `429`: Rate or spend limit reached; see Retry-After

---

[API](https://skmtc.dev/makeaivideo/apis/makeaivideo-api.md) · [All operations](https://skmtc.dev/makeaivideo/apis/makeaivideo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/makeaivideo/apis/makeaivideo-api/revisions/8c6351087d6d?raw)