---
title: "Generate AI footage (tool generate_footage): {name, prompt, duration_seconds?, aspect?, resolution?, with_audio?, budgetUsd?}."
method: POST
path: "/api/videos/generate"
---

# Generate AI footage (tool generate_footage): {name, prompt, duration_seconds?, aspect?, resolution?, with_audio?, budgetUsd?}.

`POST /api/videos/generate`

## Request

- Base URL: `https://shapelessai.com`
- URL: `https://shapelessai.com/api/videos/generate`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://shapelessai.com/api/auth/mcp/authorize`, token URL `https://shapelessai.com/api/auth/mcp/token`, scopes: `write`)

## Request body

- object
  - `name` string, required: A 2-6 word filename for this clip, as you would describe it to a colleague - e.g. "rain on window neon". Becomes the file the user sees in their Assets.
  - `prompt` string, required: The shot as 1-3 sentences of flowing prose: subject, setting, light, and the ONE camera move. Say what the camera does, not what the story means.
  - `duration_seconds` number: 4, 6, 8 (6 by default); anything else rounds up, and you are billed for the rounded length. You pay per second, and you will cut most of it.
  - `aspect` '9:16' | '16:9': Shape of the generated frame. 9:16 by default.
  - `resolution` '720p' | '1080p': 720p by default and right for b-roll under a cut. 1080p costs $0.05/s against $0.03/s - worth it only when the clip fills the frame and holds.
  - `with_audio` boolean: Generate the clip's own sound too - $0.05/s at 720p against $0.03/s silent. Default false, because narration, music and sfx normally own the mix and a generated soundtrack fights them. Worth it when the clip sound IS the point: rain, a crowd, a machine, a diegetic moment that carries the shot. An unmuted clip is mixed into the master.
  - `budgetUsd` number: The most this call may spend, in USD (default 2, max 10). Held while the tool runs, released after.

## Response `200`

OK

- ToolResult
  - `tool` string, required
  - `output` unknown, required
  - `media` object[], required: Every media key the output names, with the URL that streams it (read scope). Put a key on a post's mediaKeys.
    - `key` string
    - `url` string, uri
  - `chargedUsd` number, required

## Other responses

- `400`: The input does not match the tool's schema; the message names the field.
- `401`: No credential, or not valid.
- `402`: Not enough credit to hold budgetUsd, or the call costs more than budgetUsd.
- `403`: The key is missing the "write" scope.
- `404`: No such tool on this deployment.
- `422`: The tool refused this input; nothing was charged.
- `429`: Over the key's rate limit (600 requests an hour).
- `502`: The tool failed; nothing was charged.

---

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