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, image_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 (ai_video, ai_images, stock_video, or ai_influencer), target_video_duration, video_model_priority (array of 1–3 model IDs; for ai_influencer only seedance-2-0, seedance-2-0-720p, wan-2-7-i2v, kling-avatar-v2 — 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), image_model_priority (ordered list of image model IDs for stills and start frames—e.g. nano-banana, gpt-image-2; see AI models), caption_preset, use_narrator, elevenlabs_voice_id, avatar_enabled, avatar_id, auto_generate, post_on_weekdays, post_at_time, timezone, generate_days_ahead, youtube_social_account_id, tiktok_social_account_id, tiktok_publish_defaults (object: TikTok Direct Post defaults for scheduled publishing—privacy, caption, interactions, commercial disclosure, consent; validated like the dashboard), 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). Talking avatar overlays require use_narrator=true; if you provide an avatar_id, the project will enable avatar overlays only when narration is enabled. 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), including tiktok_publish_defaults or null to clear. 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 (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; after the screenplay splits dialogue by word indices, each scene gets a short audio slice (2–15s) for lip-sync. 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, 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 processing is set automatically during one-shot generation and cannot be set manually via the API.

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 "processing" (system-assigned during generation); 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"}'

GET /avatars

List your available talking avatars. Returns an array of avatar objects.

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

POST /avatars

Create/upload a talking avatar. This is a multipart form upload. Body: name (required) and file (required image; JPG/PNG/WEBP, up to 10MB).

curl -X POST "https://vidmachine.ai/api/v1/avatars" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "name=John" \
  -F "file=@/path/to/avatar.png"

PATCH /avatars/:avatarId

Rename an avatar. Body: name.

curl -X PATCH "https://vidmachine.ai/api/v1/avatars/AVATAR_UUID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"New name"}'

DELETE /avatars/:avatarId

Delete an avatar. This also clears avatar references from projects.

curl -X DELETE "https://vidmachine.ai/api/v1/avatars/AVATAR_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) 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)