---
title: "Generate media with AI (video, image, or audio)"
method: POST
path: "/v1/media/generate"
tags: ["media"]
---

# Generate media with AI (video, image, or audio)

`POST /v1/media/generate`

## Request

- Base URL: `https://api.cueframe.ai`
- URL: `https://api.cueframe.ai/v1/media/generate`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.cueframe.ai/api/auth/mcp/authorize`, token URL `https://api.cueframe.ai/api/auth/mcp/token`, scopes: `media:write`)
  - API key in header `PAYMENT-SIGNATURE`

Generate a new media item from a text prompt: text-to-video, text-to-image, image-to-video, speech, music, or sound effects (generator 'auto' selects the supported model). Async — returns a media id that flips to ready when generation finishes; poll GET /media/:id or register a media.completed webhook. Priced on what the model actually costs; refused with 402 if your balance cannot cover the quote (see GET /me).

## Request body

- MediaGenerateRequest: POST /media/generate body.
  - `generator` 'text-to-video' | 'text-to-image' | 'image-to-video' | 'text-to-music' | 'text-to-speech' | 'text-to-sfx' | 'auto', required
  - `prompt` string, required
  - `style` object: Free-form generation parameters, read per generator. All generators honor `aspect` (string) + `durationSec` (number) where applicable. text-to-speech honors `voice` (string; default voice when omitted), `speed` (number 0.7-1.2), `stability` (number 0-1), and `styleExaggeration` (number 0-1 → the endpoint's style exaggeration). Provider and model selection are server-owned and cannot be overridden.
  - `refs` object
    - `firstFrameMediaId` string
    - `lastFrameMediaId` string
    - `imageMediaIds` string[]

## Response `201`

Generation enqueued.

- MediaGenerateResponse: POST /media/generate response.
  - `id` string, required
  - `status` 'generating', required
  - `estimateUsd` number

## Other responses

- `400`: Bad request — validation_error / invalid_cursor / invalid_query.
- `401`: Missing or invalid Authorization header.
- `402`: Payment required — billing_required or x402 payment_*.
- `403`: Forbidden — permission insufficient.
- `422`: Unprocessable — invalid_composition / media_in_use / session_in_use / render_not_cancellable.
- `429`: Rate limited. Retry-After header present.
- `500`: Internal error.
- `503`: Service unavailable — billing_unavailable / honest-503 for runtime deps.

---

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