# API Documentation

The VidMachine REST API lets you create and manage projects, generate video ideas, and produce AI videos from your own applications. Use it to automate video creation for YouTube Shorts and TikTok, build custom content pipelines, or integrate VidMachine into existing tools. All requests require authentication via an API key. Create and manage keys in your account under [API Keys](https://vidmachine.ai/api-keys) (after login). Prefer an assistant? The same key works with the [MCP server](https://vidmachine.ai/docs/mcp.md) for Claude Code, Codex, Cursor, and other MCP clients.

## Authentication

Send your API key using either the `Authorization` header or `X-API-Key`:

```
Authorization: Bearer vidm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# or
X-API-Key: vidm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Do not commit keys to version control. Rotate keys by revoking and creating a new one in the dashboard.

## Base URL

`https://vidmachine.ai/api/v1` (replace with your actual app URL in production).

## Endpoints

### GET /projects

List all projects for the account. Returns an array of project objects (id, title, description, type, target_video_duration, video_model_priority, influencer_video_model_priority, image_model_priority, etc.).

```bash
curl -X GET "https://vidmachine.ai/api/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### POST /projects

Create a project. Body: `title` (required), plus optional description, `content_types` (array of one or more: `ai_video`, `ai_images`, `stock_video`, `ai_influencer`, `web_page`, `web_image`, `code_animation`, `uploaded_media` — the AI mixes segment types per video) or legacy `type` (single value), target_video_duration, `post_format` (`video` or `slideshow`; slideshow is only valid when `content_types` is exclusively `ai_images` and/or `web_image` — TikTok gets a native photo carousel with auto-added music, YouTube gets a rendered slideshow video), `target_slides` (2–10, default 5; slideshows only), `video_model_priority` (array of 1–3 model IDs for `ai_video` segments — excludes Kling Avatar V2 and P-Video Avatar), `influencer_video_model_priority` (array of 1–3 lip-sync model IDs for `ai_influencer` segments: `hailuo-3-480p`, `hailuo-3`, `seedance-2-0`, `seedance-2-0-720p`, `seedance-2-0-mini`, `seedance-2-0-mini-720p`, `seedance-2-5-480p`, `seedance-2-5`, `wan-2-7-i2v`, `p-video-avatar`, `kling-avatar-v2` — MiniMax H3 lip-sync uses an `audio` (URL) field with a `reference` image (480p at 3 credits/s, 768p at 8 credits/s); Kling Avatar V2 uses standard mode only, uses each scene's generated starting frame plus scene audio, and bills at 11 credits per second of scene video duration; P-Video Avatar uses each scene's starting frame plus scene audio at 720p and bills at 5 credits per second; legacy AI Influencer-only projects may still send `video_model_priority` instead), image_model_priority (ordered list of image model IDs for stills and start frames on `ai_video` and `ai_images`—omit or use `[]` for `stock_video` / `web_image`; cover images always use Muse Image regardless of project type; see [AI models](https://vidmachine.ai/models)), caption_preset, video_text_mode ('none', 'highlights', or 'captions'; default 'captions' — for slideshows, 'none' disables slide text), use_narrator (boolean, default true on create; always true for AI Influencer, always false for slideshows), elevenlabs_voice_id, `influencer_mode` (`scenes`, `overlay`, or `mixed` — how the AI Influencer presenter is used; overlay and mixed require at least one other content type and bill the circle overlay at 1 credit/s of overlay time), auto_generate, post_on_weekdays, post_at_time, timezone, generate_days_ahead, youtube_social_account_id, tiktok_social_account_id, instagram_social_account_id, `tiktok_publish_defaults` (object: TikTok Direct Post defaults for scheduled publishing—privacy, caption, interactions, commercial disclosure, consent; validated like the dashboard), `ai_disclosure_enabled` (boolean, default false — labels videos as AI-generated on YouTube, TikTok, and Instagram; set true to add the AI disclosure), generate_cover_photo. `ai_influencer` requires `use_narrator=true`, `elevenlabs_voice_id`, and a portrait `image_url` on the project (upload via dashboard after create). The presenter is generated from that reference image. Same validation as the dashboard.

```bash
curl -X POST "https://vidmachine.ai/api/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"My Channel","video_model_priority":["veo-3-1"]}'
```

### PATCH /projects/:projectId

Update a project. Body: any subset of project fields (all optional), including `tiktok_publish_defaults` or `null` to clear. Returns the updated project.

```bash
curl -X PATCH "https://vidmachine.ai/api/v1/projects/PROJECT_UUID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Updated title"}'
```

### POST /ideas/generate

Generate 10 video ideas for a project. Body: `project_id` (required). Returns the created ideas. Uses credits.

```bash
curl -X POST "https://vidmachine.ai/api/v1/ideas/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"PROJECT_UUID"}'
```

### POST /videos/generate

Generate a full one-shot video from a video idea. Body: `idea_id` (required). Runs the full pipeline (transcript and narrator speech when needed, screenplay, scene media, video). For `ai_influencer` projects, narrator speech is a single master track from the full script; talking-head scenes use a temporary audio slice (2–15s) during generation only (not stored on the screenplay). In overlay/mixed mode the circle avatar is generated from the narrator audio in ~10s lip-sync takes and burned into the export. Returns the updated video/idea when complete. Uses credits.

```bash
curl -X POST "https://vidmachine.ai/api/v1/videos/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idea_id":"IDEA_UUID"}'
```

### GET /videos

List videos. Query params: `project_id`, `status` (idea, one_shot, processing, draft, queue, upcoming, published, error, archive), `limit`, `offset`. Without `status`, archived videos are omitted; include `archive` in `status` to list them. Returns an array of video objects with project and account info. Status `one_shot` (queued in dashboard) and `processing` are system-assigned during generation and cannot be set manually via the API.

```bash
curl -X GET "https://vidmachine.ai/api/v1/videos?project_id=UUID&status=draft&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### PATCH /videos/:videoId

Edit a video. Body: `title`, `status` (archive, draft, upcoming, queue), `post_time` (ISO string, only when status is upcoming), `cover_photo_prompt`, `cover_photo_url`. Same rules as the dashboard: you cannot change status from "idea" or "published"; you cannot set or change status while the video is "one_shot" or "processing" (system-assigned during generation); upcoming/queue require a final video URL; post_time only applies when status is upcoming.

```bash
curl -X PATCH "https://vidmachine.ai/api/v1/videos/VIDEO_UUID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"New title","status":"upcoming","post_time":"2025-03-01T14:00:00.000Z"}'
```

### GET /models

Catalog of every image and video model you can call, including the exact `inputs` each model accepts, its capabilities (text-to-video, image-to-video, start/last frame, audio/lip-sync), and credit pricing. Use the returned model IDs with `POST /generations`.

```bash
curl -X GET "https://vidmachine.ai/api/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### POST /generations

Queue any catalog model. Body: `model` (required) and `inputs` (required object matching that model's `inputs` from `GET /models`). Text inputs are prompts; media inputs are public URLs: `image_url` (start frame or portrait), `last_frame_url`, `audio_url` (lip-sync), and `reference_images` (array of URLs). Returns `202` with the queued generation and a `status_url`; generation runs asynchronously. Credits are charged only when the model succeeds, and failed generations are free. Up to 10 queued or processing generations per account at a time (further calls return 429).

```bash
# Image
curl -X POST "https://vidmachine.ai/api/v1/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana-2","inputs":{"prompt":"A neon city at night","aspect_ratio":"9:16"}}'

# Video (image-to-video)
curl -X POST "https://vidmachine.ai/api/v1/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedance-2-5","inputs":{"prompt":"Slow camera push in","image_url":"https://example.com/frame.png","duration":7}}'
```

### GET /generations

List your API generations. Query params: `status` (queued, processing, succeeded, failed), `model`, `limit` (default 20, max 100), `offset`. Returns `{ generations, limit, offset }`.

```bash
curl -X GET "https://vidmachine.ai/api/v1/generations?status=succeeded&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /generations/:generationId

Poll one generation: `status` (queued, processing, succeeded, failed), `output_url` when succeeded, `credits` charged, `error` when failed, and timestamps (`created_at`, `started_at`, `completed_at`).

```bash
curl -X GET "https://vidmachine.ai/api/v1/generations/GENERATION_UUID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Errors

Responses use standard HTTP status codes. Body is JSON: `{ "error": "message" }`. Common codes: 400 validation, 401 invalid or missing API key, 402 insufficient credits, 403 forbidden, 404 resource not found, 500 server error.

### Credits

API usage uses the same credit balance as your dashboard. Every call that triggers generation (e.g. POST /ideas/generate, POST /videos/generate, POST /generations) consumes credits from the key owner's account; listing or updating resources typically does not. `POST /generations` charges only when the model succeeds and bills videos on the generated clip length; failed generations are not charged. There is no separate API credit pool. For a breakdown of what uses credits, see [Credits & billing](https://vidmachine.ai/docs/guides/credits-and-billing.md).

### Related guides

- [How to create videos](https://vidmachine.ai/docs/guides/create-videos.md) — Dashboard project settings aligned with API fields.
- [Automatic video generation](https://vidmachine.ai/docs/guides/automatic-video-generation.md) — Enable auto_generate and scheduling from the dashboard or via PATCH /projects.
- [MCP server](https://vidmachine.ai/docs/mcp.md) — Use these endpoints from Claude Code, Codex, and Cursor.
- [Quick start](https://vidmachine.ai/docs/getting-started.md) — First steps with VidMachine.
- [Docs home](https://vidmachine.ai/docs/)
- [Manage API keys](https://vidmachine.ai/api-keys) (login required)