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 (after login).

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, etc.).

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, type, target_video_duration, video_model_priority (array of 1–3 model IDs: grok-imagine-video, sora-2, veo-3-1, wan-2-5-i2v-fast, seedance-1-5-pro), caption_preset, use_narrator, elevenlabs_voice_id, auto_generate, post_on_weekdays, post_at_time, timezone, generate_days_ahead, youtube_social_account_id, tiktok_social_account_id, generate_cover_photo. Same validation as the dashboard.

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). Returns the updated project.

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.

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 (full idea, screenplay, video). Returns the updated video/idea when complete. Uses credits.

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, draft, queue, upcoming, published, error, archive), limit, offset. Returns an array of video objects with project and account info.

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"; upcoming/queue require a final video URL; post_time only applies when status is upcoming.

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"}'

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) consumes credits from the key owner’s account; listing or updating resources typically does not. There is no separate API credit pool. For a breakdown of what uses credits, see Credits & billing.

Related guides

Automatic video generation — Enable auto_generate and scheduling from the dashboard or via PATCH /projects. Getting started — First steps with VidMachine.

Docs home

Manage API keys (login required)