### Installation

Source: https://makeaivideo.ai/docs/sdk

Install the SDK via npm.

```APIDOC
## Install

```bash
npm install @makeaivideo/sdk
```
```

--------------------------------

### Install @makeaivideo/sdk via npm

Source: https://makeaivideo.ai/docs/sdk

Install the SDK package from npm. Requires an API key created under Developers.

```shell
npm install @makeaivideo/sdk
```

--------------------------------

### Start a device login with curl

Source: https://makeaivideo.ai/docs/api/auth

Use this curl command to start a device login. It sends a POST request to /auth/device with a client_name in the JSON body. The response includes a user code and a URL for the user to approve in a browser.

```bash
curl -X POST https://app.makeaivideo.ai/api/v1/auth/device \
  -H "Content-Type: application/json" \
  -d '{ "client_name": "my-laptop" }'
```

--------------------------------

### Install MakeAIVideo CLI globally with npm

Source: https://makeaivideo.ai/docs/cli

Install the @makeaivideo/cli package globally via npm. The CLI uses the device-code flow for authentication, so no secret is pasted into the terminal.

```bash
npm install -g @makeaivideo/cli
```

--------------------------------

### GET /tools

Source: https://makeaivideo.ai/docs

Lists the available tools that can be used to create videos.

```APIDOC
## GET /tools

### Description
See what we can make.

### Method
GET

### Endpoint
/tools
```

--------------------------------

### GET /tools

Source: https://makeaivideo.ai/docs/api/introspection/list-tools

List create tools and their brief fields. Requires a bearer API key with the read scope.

```APIDOC
## GET /tools

### Description
List create tools and their brief fields.

### Method
GET

### Endpoint
https://app.makeaivideo.ai/api/v1/tools

### Authentication
Bearer API key with `read` scope. A key without it gets `403 forbidden` naming the scope it lacks.

### Response
#### Success Response (200)
- **data** (object) - Tools list
- **error** (null) - No error
- **meta** (object) - Metadata

#### Response Example
{
  "data": {},
  "error": null,
  "meta": {}
}

#### Error Response (403)
- **error** (object) - Contains stable `code` and `meta.request_id`
- **meta.request_id** (string) - Identifies the call for support

#### Error Example
{
  "data": null,
  "error": {
    "code": "forbidden",
    "message": "Missing required scope: read"
  },
  "meta": {
    "request_id": "..."
  }
}
```

--------------------------------

### GET /videos

Source: https://makeaivideo.ai/docs/api/videos

Lists all videos in the workspace. Returns a VideoList object.

```APIDOC
## GET /videos

### Description
Lists all videos in the workspace.

### Method
GET

### Endpoint
https://app.makeaivideo.ai/api/v1/videos

### Response
#### Success Response (200)
- **VideoList** (object) - List of videos.

#### Response Example
```json
{
  "videos": []
}
```
```

--------------------------------

### GET /tools

Source: https://makeaivideo.ai/docs/api/introspection

Lists the create tools available to your account, each with the brief fields it expects. These field names are what you pass in the fields object on POST /videos.

```APIDOC
## GET /tools

### Description
Lists the create tools available to your account, each with the brief fields it expects. These field names are what you pass in the fields object on POST /videos.

### Method
GET

### Endpoint
https://app.makeaivideo.ai/api/v1/tools

### Responses
#### Success Response (200)
- **Tools** - Tools
```

--------------------------------

### GET /templates

Source: https://makeaivideo.ai/docs/api/videos

Lists available templates. (Details not provided in the source.)

```APIDOC
## GET /templates

### Description
Lists available templates.

### Method
GET

### Endpoint
https://app.makeaivideo.ai/api/v1/templates

### Response
#### Success Response (200)
- **TemplateList** (object) - List of templates.

#### Response Example
```json
{
  "templates": []
}
```
```

--------------------------------

### GET /characters

Source: https://makeaivideo.ai/docs/api/characters

Lists preset and workspace characters. This operation does not spend credits.

```APIDOC
## GET /characters

### Description
Lists preset and workspace characters. This operation does not spend credits.

### Method
GET

### Endpoint
https://app.makeaivideo.ai/api/v1/characters

### Response
#### Success Response (200)
Characters

```

--------------------------------

### POST /auth/device

Source: https://makeaivideo.ai/docs/api/auth

Starts a device login. Returns a short user code and a URL for the user to approve in a browser. This endpoint is unauthenticated.

```APIDOC
## POST /auth/device

### Description
Starts a device login. Returns a short user code and a URL for the user to approve in a browser. This endpoint is unauthenticated.

### Method
POST

### Endpoint
https://app.makeaivideo.ai/api/v1/auth/device

### Request Example
curl -X POST https://app.makeaivideo.ai/api/v1/auth/device \
  -H "Content-Type: application/json" \
  -d '{ "client_name": "my-laptop" }'

### Response
#### Success Response (200)
Returns a short user code and a URL for the user to approve in a browser.

#### Error Response (429)
Too many starts from this IP. Returns an ErrorEnvelope.
```

--------------------------------

### POST /auth/device

Source: https://makeaivideo.ai/docs/api/auth/device-start

Starts a device login. Send a POST request to the endpoint with a bearer API key. This route does not require a scoped key.

```APIDOC
## POST /auth/device

### Description
Start a device login. This endpoint initiates the device authorization flow. It requires a bearer API key but does not require a scoped key.

### Method
POST

### Endpoint
https://app.makeaivideo.ai/api/v1/auth/device

### Authentication
Bearer API key required. No scoped key required.

### Response
#### Success Response (200)
The request was successful.

#### Error Response (429)
Too many starts from this IP.

### Response Format
Every v1 response is `{ data, error, meta }`. On failure `error` carries a stable `code` and `meta.request_id` identifies the call.
```

--------------------------------

### Estimate video cost with POST /videos/estimate

Source: https://makeaivideo.ai/docs/quickstart

Estimates the credit cost before creating a video. Free to call. Requires a tool id from GET /tools and a duration in seconds.

```curl
curl -X POST https://app.makeaivideo.ai/api/v1/videos/estimate \
  -H "Authorization: Bearer $MAV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "<tool id from GET /tools>",
    "duration_seconds": 30
  }'
```

--------------------------------

### GET /me

Source: https://makeaivideo.ai/docs/api/introspection

Returns the account and organization behind the API key, along with credits. Use this to confirm which workspace the key is writing into.

```APIDOC
## GET /me

### Description
Returns the account and organization behind the API key, along with credits. Use this to confirm which workspace the key is writing into.

### Method
GET

### Endpoint
https://app.makeaivideo.ai/api/v1/me

### Responses
#### Success Response (200)
- **Me** - Key, user, organization and credits

#### Error Response (401)
- **ErrorEnvelope** - Missing or invalid key
```

--------------------------------

### GET /music

Source: https://makeaivideo.ai/docs/api/music

Lists the background tracks already generated in the workspace. This allows you to reuse a track across multiple videos without regenerating.

```APIDOC
## [GET] /music

### Description
Lists the background tracks already generated in the workspace. This allows you to reuse a track across multiple videos without regenerating.

### Method
GET

### Endpoint
https://app.makeaivideo.ai/api/v1/music

### Parameters
(No parameters documented in the source.)

### Response
#### Success Response (200)
- **Tracks** - A list of generated tracks.

#### Response Example
(No explicit response example provided in the source.)
```

--------------------------------

### POST /videos request body with idempotency_key

Source: https://makeaivideo.ai/docs/agents

Example request body for creating a video. The idempotency_key must be derived from the task, not the attempt, to prevent duplicate charges on retries.

```json
{
  "tool": "<tool id>",
  "fields": { "topic": "How compound interest works" },
  "idempotency_key": "run-2026-09-04-a7f3"
}
```

--------------------------------

### GET /api/v1/webhooks/{id}/deliveries

Source: https://makeaivideo.ai/docs/webhooks

Returns the last 50 delivery attempts for a webhook subscription, useful for diagnosing why an endpoint started failing.

```APIDOC
## GET /api/v1/webhooks/{id}/deliveries

### Description
Returns the last 50 delivery attempts for a webhook subscription, useful for diagnosing why an endpoint started failing.

### Method
GET

### Endpoint
https://app.makeaivideo.ai/api/v1/webhooks/{id}/deliveries

### Parameters
#### Path Parameters
- **id** (string) - Required - The webhook subscription ID (e.g., wh_...).

### Response
#### Success Response (200)
- **deliveries** (array) - List of delivery attempts, each containing attempt number, timestamp, and status.

#### Response Example
{
  "deliveries": [
    {
      "attempt": 1,
      "timestamp": 1700000000,
      "status": "success"
    }
  ]
}
```

--------------------------------

### Create a video with @makeaivideo/sdk

Source: https://makeaivideo.ai/docs/sdk

Shows the shortest useful path: list tools, estimate cost, create a video, and wait for it to be ready. The estimate step is free and confirms the cost before an irreversible spend. waitForReady polls respecting the API's poll_after_seconds hint.

```typescript
import { MakeAIVideo } from "@makeaivideo/sdk"

const mav = new MakeAIVideo({ apiKey: process.env.MAKEAIVIDEO_API_KEY! })

// 1. See the video tools and the fields each one asks for
const tools = await mav.tools.list()

// 2. Quote the cost, then create
const quote = await mav.videos.estimate({ tool: "explainer", duration_seconds: 30 })
const { video_id } = await mav.videos.create({
  tool: "explainer",
  fields: { topic: "Why octopuses have three hearts" },
  duration_seconds: 30,
  aspect_ratio: "9:16",
})

// 3. Wait for the render and download it
const video = await mav.videos.waitForReady(video_id, {
  onProgress: (v) => console.log(v.status),
})
console.log(video.download) // MP4 URL
```

--------------------------------

### GET /videos/{id}/captions

Source: https://makeaivideo.ai/docs/api/videos

Gets the captions for a video. (Details not provided in the source.)

```APIDOC
## GET /videos/{id}/captions

### Description
Gets the captions for a video.

### Method
GET

### Endpoint
https://app.makeaivideo.ai/api/v1/videos/{id}/captions

### Parameters
#### Path Parameters
- **id** (string) - Required - The video ID.

### Response
#### Success Response (200)
- **Captions** (object) - Caption data.

#### Response Example
```json
{
  "captions": []
}
```
```

--------------------------------

### GET /videos/{id}/voice

Source: https://makeaivideo.ai/docs/api/videos

Gets the voiceover progress. (Details not provided in the source.)

```APIDOC
## GET /videos/{id}/voice

### Description
Gets the voiceover progress.

### Method
GET

### Endpoint
https://app.makeaivideo.ai/api/v1/videos/{id}/voice

### Parameters
#### Path Parameters
- **id** (string) - Required - The video ID.

### Response
#### Success Response (200)
- **VoiceProgress** (object) - Voiceover progress.

#### Response Example
```json
{
  "progress": 50
}
```
```

--------------------------------

### List create tools with curl

Source: https://makeaivideo.ai/docs/api/introspection

Call GET /tools to retrieve the create tools and their brief fields. This is the first call in most integrations because it provides the field names needed for POST /videos.

```bash
curl https://app.makeaivideo.ai/api/v1/tools \
  -H "Authorization: Bearer $MAV_API_KEY"
```

--------------------------------

### GET /webhooks

Source: https://makeaivideo.ai/docs/api

List webhooks.

```APIDOC
## GET /webhooks

### Description
List webhooks.

### Method
GET

### Endpoint
/webhooks

```

--------------------------------

### mav.tools.list()

Source: https://makeaivideo.ai/docs/sdk

Lists the available video tools and the fields each one asks for.

```APIDOC
## mav.tools.list()

### Description
Lists the video tools and the fields each one asks for.

### Method
GET

### Endpoint
/tools

### Parameters
None

### Request Example
```typescript
const tools = await mav.tools.list()
```

### Response
#### Success Response (200)
- **tools** (array) - List of tool objects with fields.

#### Response Example
```json
{
  "tools": [
    {
      "id": "explainer",
      "fields": ["topic", "duration_seconds", "aspect_ratio"]
    }
  ]
}
```
```

--------------------------------

### GET /webhooks/{id}

Source: https://makeaivideo.ai/docs/api

Webhook detail.

```APIDOC
## GET /webhooks/{id}

### Description
Webhook detail.

### Method
GET

### Endpoint
/webhooks/{id}

```

--------------------------------

### GET /videos

Source: https://makeaivideo.ai/docs/api

Lists all videos associated with the authenticated user.

```APIDOC
## GET /videos

### Description
Lists all videos associated with the authenticated user.

### Method
GET

### Endpoint
/videos

```

--------------------------------

### GET /videos/{id}/renders

Source: https://makeaivideo.ai/docs/api/videos

List past exports of the video.

```APIDOC
## GET /videos/{id}/renders

### Description
List past exports of the video.

### Method
GET

### Endpoint
https://app.makeaivideo.ai/api/v1/videos/{id}/renders

### Parameters
#### Path Parameters
- **id** (string) - Required - Public video id, e.g. vid_abc123

### Response
#### Success Response (200)
- **Renders** - List of past exports.

```

--------------------------------

### mav.videos.waitForReady()

Source: https://makeaivideo.ai/docs/sdk

Polls until the video is ready and returns the video object with download URL.

```APIDOC
## mav.videos.waitForReady()

### Description
Polls until the video is ready and returns the video object with download URL.

### Method
GET

### Endpoint
/videos/{video_id}/wait

### Parameters
#### Path Parameters
- **video_id** (string) - Required - The ID of the video.

#### Query Parameters
- **onProgress** (function) - Optional - Callback for progress updates.

### Request Example
```typescript
const video = await mav.videos.waitForReady(video_id, {
  onProgress: (v) => console.log(v.status),
})
```

### Response
#### Success Response (200)
- **download** (string) - URL to download the MP4.
- **status** (string) - Current status of the video.

#### Response Example
```json
{
  "download": "https://example.com/video.mp4",
  "status": "ready"
}
```
```

--------------------------------

### mav.videos.create()

Source: https://makeaivideo.ai/docs/sdk

Creates a video render job.

```APIDOC
## mav.videos.create()

### Description
Creates a video render job.

### Method
POST

### Endpoint
/videos

### Parameters
#### Request Body
- **tool** (string) - Required - The video tool identifier.
- **fields** (object) - Required - Tool-specific fields.
- **duration_seconds** (number) - Required - Duration of the video in seconds.
- **aspect_ratio** (string) - Optional - Aspect ratio of the video (e.g., "9:16").

### Request Example
```typescript
const { video_id } = await mav.videos.create({
  tool: "explainer",
  fields: { topic: "Why octopuses have three hearts" },
  duration_seconds: 30,
  aspect_ratio: "9:16",
})
```

### Response
#### Success Response (200)
- **video_id** (string) - The ID of the created video.

#### Response Example
```json
{
  "video_id": "abc123"
}
```
```

--------------------------------

### POST /voices/preview: Hear a voice read your own line

Source: https://makeaivideo.ai/docs/api/voices

Sends a POST request to the preview endpoint with a voice ID and custom text. The response contains a temporary audio URL valid for about an hour; fetch and cache the audio promptly rather than storing the link.

```bash
curl -X POST https://app.makeaivideo.ai/api/v1/voices/preview \
  -H "Authorization: Bearer $MAV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_id": "<id from GET /voices>",
    "text": "Most people get compound interest backwards."
  }'
```

--------------------------------

### GET /videos/{id}/download

Source: https://makeaivideo.ai/docs

Fetches the finished MP4 video file.

```APIDOC
## GET /videos/{id}/download

### Description
Fetch the finished MP4.

### Method
GET

### Endpoint
/videos/{id}/download

### Parameters
#### Path Parameters
- **id** (string) - Required - The video ID.
```

--------------------------------

### Create video with POST /videos and 202 response

Source: https://makeaivideo.ai/docs/quickstart

Creates a video. Pass a `tool` plus `fields` to have the script written, or pass your own `script` object to render exactly that. Returns `202 Accepted`; the render has started but not finished. The `idempotency_key` prevents duplicate charges on retries.

```curl
curl -X POST https://app.makeaivideo.ai/api/v1/videos \
  -H "Authorization: Bearer $MAV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "<tool id from GET /tools>",
    "fields": { "topic": "How compound interest works" },
    "duration_seconds": 30,
    "idempotency_key": "quickstart-001"
  }'
```

```json
{
  "data": {
    "video_id": "vid_...",
    "status": "generating",
    "poll_after_seconds": <integer, read it from the response>,
    "next": "..."
  },
  "error": null,
  "meta": { ... }
}
```

--------------------------------

### Create a webhook subscription with curl

Source: https://makeaivideo.ai/docs/webhooks

POST to /api/v1/webhooks with a public HTTPS URL and the video.ready event. The signing secret is returned only once in the response, so store it immediately.

```bash
curl -X POST https://app.makeaivideo.ai/api/v1/webhooks \
  -H "Authorization: Bearer $MAV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/makeaivideo",
    "events": ["video.ready"]
  }'
```

--------------------------------

### GET /videos/{id}/renders

Source: https://makeaivideo.ai/docs/api/videos

Lists all renders for a video. (Details not provided in the source.)

```APIDOC
## GET /videos/{id}/renders

### Description
Lists all renders for a video.

### Method
GET

### Endpoint
https://app.makeaivideo.ai/api/v1/videos/{id}/renders

### Parameters
#### Path Parameters
- **id** (string) - Required - The video ID.

### Response
#### Success Response (200)
- **RenderList** (object) - List of renders.

#### Response Example
```json
{
  "renders": []
}
```
```

--------------------------------

### GET /videos/{id}

Source: https://makeaivideo.ai/docs/api/videos

Retrieves a single video by its ID. Used for polling render progress.

```APIDOC
## GET /videos/{id}

### Description
Retrieves a single video by its ID. Used for polling render progress.

### Method
GET

### Endpoint
https://app.makeaivideo.ai/api/v1/videos/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The video ID.

### Response
#### Success Response (200)
- **Video** (object) - The video object.

#### Response Example
```json
{
  "id": "video_123",
  "status": "generating"
}
```
```

--------------------------------

### Run MCP server locally over stdio

Source: https://makeaivideo.ai/docs/mcp

Runs the Makeaivideo MCP server locally using npx. Requires a MAKEAIVIDEO_API_KEY environment variable set to a valid API key.

```shell
MAKEAIVIDEO_API_KEY=mav_... npx -y @makeaivideo/mcp
```

--------------------------------

### GET /webhooks/{id}/deliveries

Source: https://makeaivideo.ai/docs/api/webhooks

Returns the last 50 delivery attempts for a webhook, useful for debugging delivery failures.

```APIDOC
## GET /webhooks/{id}/deliveries

### Description
Returns the last 50 delivery attempts for a webhook, useful for debugging delivery failures.

### Method
GET

### Endpoint
https://app.makeaivideo.ai/api/v1/webhooks/{id}/deliveries

### Parameters
#### Path Parameters
- **id** (string) - Required - Webhook id, e.g. wh_abc123

### Response
#### Success Response (200)
- **Deliveries** (array) - List of delivery attempt objects.

#### Response Example
{
  "deliveries": []
}
```

--------------------------------

### POST /videos

Source: https://makeaivideo.ai/docs/api/videos/create-video

Creates a video from a brief or your own script. Requires a bearer API key with write scope. The request body follows the CreateVideo schema and is required.

```APIDOC
## POST /videos

### Description
Create a video from a brief or your own script.

### Method
POST

### Endpoint
https://app.makeaivideo.ai/api/v1/videos

### Authentication
Bearer API key with `write` scope. A key without it gets `403 forbidden` naming the scope it lacks.

### Request Body
Required. Follows the `CreateVideo` schema. The full shape is in [openapi.json](https://makeaivideo.ai/openapi.json).

### Responses
Every v1 response is `{ data, error, meta }`. On failure `error` carries a stable `code` and `meta.request_id` identifies the call.

| Status | Meaning |
|--------|---------|
| 202 | Accepted. status is `generating`, or `draft` when start_generation is false |
| 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 |
```

--------------------------------

### GET /videos/{id}

Source: https://makeaivideo.ai/docs/agents

Polls the status of a video render. Use the poll_after_seconds value from the create response to determine when to poll.

```APIDOC
## GET /videos/{id}

### Description
Polls the status of a video render. Use the poll_after_seconds value from the create response to determine when to poll.

### Method
GET

### Endpoint
/videos/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The video ID returned from the create request.

### Response
#### Success Response (200)
- **data** (object) - Contains video status and other details.
  - **status** (string) - Status of the render, e.g., "ready" or "generating".
  - **poll_after_seconds** (number) - Suggested delay before next poll.

#### Response Example
{
  "data": {
    "status": "ready",
    "poll_after_seconds": 0
  }
}
```

--------------------------------

### POST /voices/preview

Source: https://makeaivideo.ai/docs/api/voices/preview-voice-text

Generates a preview audio of a voice speaking the provided text. Returns a URL to the audio, valid for one hour. Requires an API key with the 'ai' scope.

```APIDOC
## POST /voices/preview

### Description
Hear any voice say your text (1-hour audio URL).

### Method
POST

### Endpoint
https://app.makeaivideo.ai/api/v1/voices/preview

### Authentication
Bearer API key with `ai` scope. A key without this scope gets `403 forbidden` naming the scope it lacks.

### Response
#### Success Response (200)
- **data** (object) - Contains the audio URL.
- **error** (null) - No error.
- **meta** (object) - Metadata.

#### Response Example
{
  "data": {},
  "error": null,
  "meta": {}
}

### Error Handling
Every v1 response is `{ data, error, meta }`. On failure `error` carries a stable `code` and `meta.request_id` identifies the call, which is the thing to quote in a support mail.
```

--------------------------------

### POST /videos/estimate

Source: https://makeaivideo.ai/docs

Provides a free quote for video creation before spending credits.

```APIDOC
## POST /videos/estimate

### Description
Free quote, before you spend credits.

### Method
POST

### Endpoint
/videos/estimate
```

--------------------------------

### GET /brand-kit

Source: https://makeaivideo.ai/docs/api/brand-kit/get-brand-kit

Retrieves the brand kit settings, including watermark configuration. Requires a bearer API key with the read scope.

```APIDOC
## GET /brand-kit

### Description
Retrieves the brand kit settings, including watermark configuration. Requires a bearer API key with the read scope.

### Method
GET

### Endpoint
https://app.makeaivideo.ai/api/v1/brand-kit

### Authentication
Bearer API key with `read` scope. A key without this scope receives a `403 forbidden` response naming the missing scope.

### Response
#### Success Response (200)
Returns the brand kit data.

#### Response Example
{
  "data": {},
  "error": null,
  "meta": {}
}

#### Error Response (403)
Returned when the API key lacks the `read` scope. The error includes a stable `code` and `meta.request_id` for support.

#### Error Response Example
{
  "data": null,
  "error": {
    "code": "forbidden",
    "message": "Missing required scope: read"
  },
  "meta": {
    "request_id": "..."
  }
}
```

--------------------------------

### POST /videos

Source: https://makeaivideo.ai/docs/quickstart

Creates a new video render. You can either pass a `tool` plus `fields` and the API writes the script, or pass your own `script` object to render exactly that. Returns 202 Accepted with a video_id and polling information.

```APIDOC
## POST /videos

### Description
Creates a new video render. You can either pass a `tool` plus `fields` and the API writes the script, or pass your own `script` object to render exactly that. Returns 202 Accepted with a video_id and polling information.

### Method
POST

### Endpoint
https://app.makeaivideo.ai/api/v1/videos

### Authentication
Bearer token (API key with `write` and `ai` scopes)

### Request Body
- **tool** (string) - Required - The tool id from GET /tools.
- **fields** (object) - Optional - Fields for the tool to generate the script. Required if `script` is not provided.
- **script** (object) - Optional - Your own script object to render exactly. Required if `fields` is not provided.
- **duration_seconds** (integer) - Required - Desired video duration in seconds.
- **idempotency_key** (string) - Optional - A unique key to prevent duplicate charges on retries.

### Request Example
```
curl -X POST https://app.makeaivideo.ai/api/v1/videos \
  -H "Authorization: Bearer $MAV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "<tool id from GET /tools>",
    "fields": { "topic": "How compound interest works" },
    "duration_seconds": 30,
    "idempotency_key": "quickstart-001"
  }'
```

### Response
#### Success Response (202 Accepted)
- **data** (object) - Contains:
  - **video_id** (string) - The ID of the created video.
  - **status** (string) - The initial status, e.g., "generating".
  - **poll_after_seconds** (integer) - Recommended polling interval.
  - **next** (string) - URL for the next step.
- **error** (null) - Always null on success.
- **meta** (object) - Additional metadata.

#### Response Example
```
{
  "data": {
    "video_id": "vid_...",
    "status": "generating",
    "poll_after_seconds": <integer, read it from the response>,
    "next": "..."
  },
  "error": null,
  "meta": { ... }
}
```

```

--------------------------------

### mav.me()

Source: https://makeaivideo.ai/docs/sdk

Returns account information.

```APIDOC
## mav.me()

### Description
Returns account information.

### Method
GET

### Endpoint
/me

### Parameters
None

### Request Example
```typescript
const me = await mav.me()
```

### Response
#### Success Response (200)
- **account** (object) - Account details.

#### Response Example
```json
{
  "account": {
    "id": "user123",
    "email": "user@example.com"
  }
}
```
```

--------------------------------

### Download MP4 with GET /videos/{id}/download

Source: https://makeaivideo.ai/docs/quickstart

Downloads the finished MP4. Uses `-L` to follow redirects and `-o` to save as video.mp4.

```curl
curl -L https://app.makeaivideo.ai/api/v1/videos/vid_.../download \
  -H "Authorization: Bearer $MAV_API_KEY" \
  -o video.mp4
```

--------------------------------

### Import a reference image by URL with curl

Source: https://makeaivideo.ai/docs/api/uploads

Use POST /uploads/reference-from-url to import a reference image from a public URL. This is the easier path for an agent that already has an image address and no file on disk. Requires an API key with write scope.

```bash
curl -X POST https://app.makeaivideo.ai/api/v1/uploads/reference-from-url \
  -H "Authorization: Bearer $MAV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "image_url": "https://example.com/product.jpg" }'
```