# VidMachine documentation (full) > Complete VidMachine documentation in a single markdown file for AI agents and LLMs. VidMachine is an AI video generation and automation platform for YouTube Shorts, TikTok, and Instagram Reels. Index of pages: https://vidmachine.ai/llms.txt Each page is also available as an individual markdown file at the same URL with `.md` appended. # Documentation > VidMachine documentation index. Learn how to create AI videos and run hands-free pipelines on YouTube Shorts, TikTok, and Instagram Reels. Learn how to use VidMachine to create AI videos and run hands-free pipelines. Start with the quick start, configure projects in how to create videos, then connect accounts and schedules in automatic video generation. Manage credits or use the REST API and MCP server for automation. ## Start here - [Quick start](https://vidmachine.ai/docs/getting-started.md): Five steps from sign-up to your first AI video — with screenshots. - [How to create videos](https://vidmachine.ai/docs/guides/create-videos.md): Set up project settings, generate ideas, produce videos, and publish manually. - [AI Influencer avatar overlays](https://vidmachine.ai/docs/guides/talking-avatar-overlays.md): Add a lip-synced circle avatar overlay to UGC-style Shorts and TikTok videos — project modes, requirements, and 1 credit/s pricing. - [Automatic video generation](https://vidmachine.ai/docs/guides/automatic-video-generation.md): Connect accounts and configure schedule settings for hands-free Auto Mode. - [Credits & billing](https://vidmachine.ai/docs/guides/credits-and-billing.md): How credits work, what uses them, and where to manage usage and billing. - [API reference](https://vidmachine.ai/docs/api.md): REST API authentication, endpoints, and examples for automation. - [MCP server](https://vidmachine.ai/docs/mcp.md): Connect Claude Code, Codex, Cursor, and other MCP clients to your account with an API key. ## Overview video - [VidMachine documentation overview](https://www.youtube.com/watch?v=tJaMSHLIkb0): Short walkthrough of the product and docs. ## Machine-readable versions - This file (`/llms.txt`) is the index for AI agents. - `/llms-full.txt` contains the complete documentation in a single markdown file. - Every page above is available as markdown at the same URL with `.md` appended. --- # Quick start Go from sign-up to your first AI video in about 10 minutes. These five steps match the **Quick start guide** inside the dashboard. Prefer watching? See the [documentation overview video](https://vidmachine.ai/docs). ## 1. Create your account Sign up with Google or email. Your account includes free credits, so you can create your first video without adding a payment method. ## 2. Connect a channel Open **Accounts** in the sidebar and connect YouTube and/or TikTok. You can skip this for now, but you need a connected account before VidMachine can publish for you. ![VidMachine Social Accounts page with the Connect YouTube and Connect TikTok buttons highlighted](https://vidmachine.ai/docs/getting-started/1-accounts.png) Connect YouTube or TikTok under Accounts. Instagram appears when it is enabled for your account. ## 3. Create a project Open **Projects** and click **Create Project**. Use one project per channel or niche — its settings apply to every video in it. ![VidMachine Projects page with the Create Project button highlighted](https://vidmachine.ai/docs/getting-started/2-projects.png) Projects hold the channel settings. Click Create Project in the top-right. Give the project a **Title** and a **Channel Description** (100–5,000 characters). The description is the main creative brief — the AI uses it for ideas, screenplays, and visuals. You can leave the other sections on their defaults and edit them later. ![Create Project modal with the Title and Channel Description fields filled in](https://vidmachine.ai/docs/getting-started/3-create-project.png) Title and Channel Description are the only fields you must fill to start. See [How to create videos](https://vidmachine.ai/docs/guides/create-videos.md) for every setting. ## 4. Generate video ideas Open **Videos** and click **Generate Video Ideas**, then pick your project. VidMachine writes a batch of titles (10 by default) from your channel description — 1 credit per batch. Keep the ideas you like. ![VidMachine Videos page with the Generate Video Ideas button highlighted](https://vidmachine.ai/docs/getting-started/4-videos-ideas.png) Generate Video Ideas fills your idea pool. Each batch uses 1 credit. ## 5. Generate your first video Open an idea from the list and click **Generate Video**. VidMachine runs the full pipeline: screenplay, scenes, media, optional narrator and captions, and the final export. You can leave the page — the video status stays visible on **Videos**. ![Video idea page with the Generate Video button highlighted](https://vidmachine.ai/docs/getting-started/5-idea-oneshot.png) Generate Video builds the complete video from the idea. Credits are used based on length, content types, and models. ## After your first video When the video is ready, set it to **Upcoming** with a post time or publish it right away. Connect accounts under **Accounts** if you skipped that step. To make videos automatically, open **Projects**, click **Schedule** on your project, and enable **Auto Generate Videos** — see [Automatic video generation](https://vidmachine.ai/docs/guides/automatic-video-generation.md). ## If something goes wrong - **Generate Video Ideas is disabled or asks for a project** — create a project first, then select it in the dialog. - **Channel Description is rejected** — it must be at least 100 characters. Describe your topic, audience, format, and tone. - **Nothing publishes** — connect YouTube or TikTok under Accounts, then schedule the video or publish it manually. - **Generation fails or looks stuck** — open the video to see its status and error. You can retry, or add fallback models in the project settings. - **Out of credits** — see [Credits & billing](https://vidmachine.ai/docs/guides/credits-and-billing.md) for what uses credits and how to top up. ## What to read next - [How to create videos](https://vidmachine.ai/docs/guides/create-videos.md) — every project setting and the manual workflow. - [Automatic video generation](https://vidmachine.ai/docs/guides/automatic-video-generation.md) — accounts, schedules, and Auto Mode. - [Credits & billing](https://vidmachine.ai/docs/guides/credits-and-billing.md) - [API reference](https://vidmachine.ai/docs/api.md) --- # How to create videos Use this guide to set up a project and produce videos manually from the dashboard: Projects → Videos → publish. Configure creative settings once per channel or niche; the same settings apply to every video in that project (including Auto Mode later). For hands-free scheduling and posting, finish project setup here first, then follow [Automatic video generation](https://vidmachine.ai/docs/guides/automatic-video-generation.md). ## Create a project In the dashboard, open **Projects** and click **Create Project**. Your first project uses a short wizard: enter **Title** and **Channel Description**, then continue to full settings. For later projects, the configure modal opens with all sections at once. Use **Configure** on any row to edit an existing project. ## Project settings Everything below lives in the project configure modal (Create Project / Configure). Match labels in the app when you look for a field. ### Basics - **Title** — Channel or niche name for your reference in Projects and Videos. - **Content Types** — Select one or more types. The AI mixes segment types within each video. - **Video orientation** — Vertical (9:16) for Shorts/TikTok (target up to 2 minutes). Landscape (16:9) for widescreen (target up to 15 minutes). - **Channel Description** — Required, 100–5,000 characters. This is the main creative brief for ideas, screenplays, and visuals. Content type options: - **AI Video** — AI-generated motion clips per scene. - **AI Images** — Slideshow-style scenes from AI images. - **Stock Videos** — Licensed stock footage segments. - **Uploaded Media** — Your own footage and images. Upload up to 10 files per project (videos max 3 minutes / 200 MB, images max 25 MB). Analysis starts automatically after each upload and costs 1 credit per started video minute (1 credit per image). The AI uses the analyzed video segments and image descriptions to cut any moment or still into your screenplay. - **AI Influencer** — A lip-synced presenter; Reference Image is required. Choose a mode: Talking-head scenes, Avatar overlay only, or Scenes + overlay. - **Web Pages** — Screen-style segments from web pages; enable Web search in project settings. - **Web Images** — Segments built from web-sourced images. - **Code Animations** — Generated motion-graphics animations for abstract, data, and process beats. The AI writes an HTML/canvas animation per scene and renders it to video; if a render fails, the scene falls back to stock footage. 2 credits per scene. ### Slideshows When your content types are exclusively **AI Images** and/or **Web Images**, an **Output format** choice appears: **Video** or **Slideshow**. - Slideshow projects replace Target Video Duration with **Number of slides** (2–10; default 5). - The AI writes a short text line for each slide, baked onto the image with your caption styling. You can review and edit each slide's text on the video page; use **Update slides** to re-bake the images (exporting also re-bakes, and TikTok posts the baked images as-is). Prefer no text? Choose **None** under the slide text styles in project settings and the slides render without text. - **TikTok** receives a native photo carousel and automatically adds a recommended music track from TikTok's library — you can change the track later in the TikTok app. - **YouTube** receives the same slides rendered as a short video with your project music. - The narrator is off for slideshows; they are music-driven. ### Reference Image Optional for most projects; **required** when **AI Influencer** is enabled. Upload a clear portrait of your presenter (crop matches project aspect ratio). It defines the presenter identity for talking-head scenes and for the circle avatar overlay. See [AI Influencer avatar overlays](https://vidmachine.ai/docs/guides/talking-avatar-overlays.md). ### Ideas and web search **Web search** uses real-time web data when generating titles, transcripts, and full ideas (3 credits per step instead of 1). Required for **Web Pages** content. **Ideas per batch** controls how many titles are generated at once (3–10; default 10). Lower values (e.g. 3–5) keep Auto Mode fresher for news or timely topics. ### Voice **Use narrator voice** adds spoken narration (xAI, Speechify, or ElevenLabs) and is on by default on new projects. It can be turned off for any content type; it is forced on for AI Influencer (scene speech drives lip-sync and the avatar overlay) and forced off for slideshows (music-only). Pick a voice and adjust **narrator speed** (1.0–1.2; xAI and Speechify only — ElevenLabs v4 ignores speed). ### Video - **Target Video Duration (seconds)** — 10–120 seconds for portrait; 10–900 seconds for landscape. Drives screenplay length and generation cost. Not used for slideshows; those use **Number of slides** instead. - **AI Influencer mode** — Talking-head scenes, Avatar overlay only, or Scenes + overlay. Overlay modes require at least one other visual content type, and let you pick the overlay corner plus an optional colored border. - **Image models (priority)** — Pick 1–4 models in order; the next model is tried if one fails. Used for AI Video frames, AI Images, and related segments. - **AI Video models (priority)** — When AI Video is enabled: 1–3 video models in priority order (e.g. Grok, Veo, Sora). - **AI Influencer models (priority)** — When AI Influencer produces talking-head scenes: 1–3 lip-sync models in priority order. - **Generate cover photo** — Optional thumbnail/cover per export (uses credits; can be used as YouTube thumbnail when posting). - **Background music & sound effects** — Optional music under narration; optional short SFX on certain scene transitions. - **On-screen text / caption preset** — Full captions, sparse highlight titles, or none — plus a visual preset when captions are on. - **Watermark** — Optional branded watermark on exports (position and opacity in the watermark editor). ### Channel description tips Describe your topic, audience, structure, visual style, and tone. Include example titles or hooks. A strong description improves both manual ideas and Auto Mode output. ## From idea to finished video 1. **Generate video ideas.** Go to Videos and click Generate Video Ideas. Pick your project and confirm. VidMachine creates a batch of titles from your channel description (1 credit per batch; batch size is set in project settings). 2. **Pick an idea and generate the video.** Open an idea from the list and use Generate Video to run the full pipeline: idea expansion, screenplay, segments (AI video, images, stock, web, influencer, etc.), optional narrator, captions, and export. Generation uses credits based on length and models. 3. **Schedule or publish.** When the video is ready, set status to Upcoming with a post time, or publish immediately. Connect YouTube and TikTok (and Instagram Reels when available) under Accounts in the sidebar. For fully automatic creation and posting, use Schedule settings on the project — see Automatic video generation. ## Credits and generation time Video generation, narrator, captions, and covers consume credits. Cost depends on duration, content types, and model choices. See [Credits & billing](https://vidmachine.ai/docs/guides/credits-and-billing.md). Generate Video queues work immediately — you can leave the page. The Videos list shows status (queued, processing, draft, error, etc.). ## Related guides - [Quick start](https://vidmachine.ai/docs/getting-started.md) - [Automatic video generation](https://vidmachine.ai/docs/guides/automatic-video-generation.md) - [Credits & billing](https://vidmachine.ai/docs/guides/credits-and-billing.md) - [API reference](https://vidmachine.ai/docs/api.md) --- # Automatic video generation > Prerequisite: project configured. This guide assumes you already created a project and set creative options (content types, channel description, models, duration, narrator, etc.). If not, complete [How to create videos](https://vidmachine.ai/docs/guides/create-videos.md) first. Auto Mode (**Auto Generate Videos** in schedule settings) creates ideas and full videos ahead of your post dates and publishes them to the accounts you assign. Use one project per channel or niche so description, models, and posting targets stay aligned. ## What Auto Mode does When **auto_generate** is enabled for a project, VidMachine keeps upcoming slots filled: it generates video ideas and completes videos before each scheduled post time, then uploads to YouTube Shorts, TikTok, and/or Instagram Reels (when connected and selected). You can still generate or edit videos manually on the Videos page while Auto Mode is on. ## Step 1: Connect accounts Open **Accounts** in the dashboard sidebar. Connect one or more YouTube channels and TikTok accounts via OAuth. Instagram Reels appears when your account has Instagram integration enabled — connect it the same way. You can link multiple accounts and choose which channel each project uses in schedule settings. Without connected accounts, videos can still be generated but will not auto-publish until you assign accounts or publish manually. ![VidMachine Accounts page with Connect YouTube, Connect TikTok, and Connect Instagram buttons](https://vidmachine.ai/docs/automode/1-accounts.png) Connect the platforms you want to publish to before enabling Auto Mode. ## Step 2: Open Schedule settings Go to **Projects** and click **Schedule** on the project you want to automate. This opens the Schedule Settings modal for that project. ![VidMachine Projects table with the Schedule button highlighted on a project row](https://vidmachine.ai/docs/automode/2-projects.png) Each project has its own schedule — use one project per channel or niche. ## Step 3: Enable Auto Generate Videos In Schedule Settings, turn on **Auto Generate Videos**. Until this switch is on, VidMachine will not create or post videos automatically for this project, even if weekdays and times are set. ![Schedule Settings modal with the Auto Generate Videos toggle highlighted](https://vidmachine.ai/docs/automode/3-auto-gen.png) Turn on Auto Generate Videos to start the hands-free pipeline for this project. ## Step 4: Configure your schedule Choose posting weekdays, time, timezone, and how many days ahead videos should be generated. Assign YouTube, TikTok, and/or Instagram accounts for auto-publishing, then click **Update Project**. ![Schedule Settings modal showing weekdays, post time, timezone, generate days ahead, and linked social accounts](https://vidmachine.ai/docs/automode/4-schedule.png) Set when videos go live and which connected accounts receive each post. ### Schedule fields reference - **Auto Generate Videos** — Master switch for automatic generation and posting for this project. - **Post On Weekdays** — Which days to publish (select at least one). More days means more videos per week and higher credit use. - **Post At Time** — Time of day (24-hour) when each scheduled video should go live, interpreted in the timezone below. - **Timezone** — IANA timezone (e.g. America/New_York). The dashboard may pre-fill your detected timezone. - **Generate Days Ahead** — 1–30 days (default 5). How far before the post date VidMachine should have the video ready. Use at least 3–7 days so slow runs or retries do not miss post day. - **YouTube / TikTok / Instagram account** — Optional per platform. Only the selected account receives auto-published videos for this project. Leave blank to skip auto-publish on that platform. - **TikTok publish defaults** — When TikTok is selected: default caption template, privacy, comment/duet/stitch, commercial and branded content flags, and music consent — applied to each auto-published TikTok post unless overridden per video. - **Disclose AI-generated content** — Off by default. Turn it on to label each video as AI-generated on YouTube (altered or synthetic content disclosure), TikTok (AI-generated label), and Instagram (AI info label). When off, videos publish without the disclosure. - **Distribution protection** — On by default when at least one platform account is linked. If the last three published videos on a platform (each at least 24 hours old) all have fewer than 20 views, that platform enters a 7-day cooldown. With one platform connected, the whole schedule pauses and upcoming times shift forward. With multiple platforms, only the affected platform is skipped. You can turn protection off or resume early from the schedule modal or alerts on Projects/Videos. - **Auto Mode credits estimate** — Shown in the schedule modal: approximate weekly credit use based on your post days and current project settings. See Credits & billing for what drives cost. ## How generation and posting run Background jobs run on a fixed interval: generation runs about every 10 minutes and posting about every 5 minutes. For each project with Auto Mode on, the system computes upcoming post dates from weekdays, post time, and timezone, then ensures a video exists at least **generate_days_ahead** before each date. When post time arrives, the video is published to the linked accounts. Monitor upcoming and published items on the **Videos** page and the **Auto Mode** column on Projects. ## When something goes wrong If generation or publishing fails, check the **Auto Mode** column for an error message. After **2 consecutive failures**, Auto Mode turns off for safety — fix the issue (credits, account permissions, model errors), then re-enable **Auto Generate Videos** in schedule settings. Insufficient credits block new generation until you add credits or your subscription renews. ## Tips for reliable automation Keep a credit buffer for your posting frequency. Use 2–3 image and video models in priority order for fallbacks. Set generate days ahead to 3–7. Use a clear channel description (see [How to create videos](https://vidmachine.ai/docs/guides/create-videos.md)). Assign the correct YouTube, TikTok, and Instagram accounts per project when you run multiple channels. ## Related guides - [How to create videos](https://vidmachine.ai/docs/guides/create-videos.md) - [Quick start](https://vidmachine.ai/docs/getting-started.md) - [Credits & billing](https://vidmachine.ai/docs/guides/credits-and-billing.md) - [API reference](https://vidmachine.ai/docs/api.md) (enable `auto_generate` via PATCH /projects) --- # AI Influencer Avatar Overlays Make UGC-style videos that feel more “creator-on-camera” by overlaying a lip-synced circle avatar on top of your other scenes. Designed for Shorts and TikTok formats. ## How it works The AI Influencer content type has three modes: - **Talking-head scenes** — full-screen lip-synced presenter scenes (the classic behavior). - **Avatar overlay only** — no full-screen presenter scenes. A small circle avatar is overlaid on your other scenes. - **Scenes + overlay** — full-screen presenter scenes, plus the circle overlay on the other scenes. For the circle overlay, VidMachine: 1. Generates a short **presenter clip** from your project **Reference Image** with LTX 2.5 Fast at 480p, then caches it on the project and reuses it for every video. 2. Lip-syncs the presenter clip to the narrator audio with MuseTalk — each continuous stretch between talking-head scenes, or the whole video in Avatar overlay only mode, split into chunks under MuseTalk’s 120-second audio limit. 3. Overlays the result as a circle in the final video, only where non-presenter scenes play (Scenes + overlay mode). Pick the corner and an optional colored ring border in project settings — bottom-right and no border by default. ## Requirements - **AI Influencer content type selected** — Avatar overlays belong to the AI Influencer type and its mode. - **Narrator must be enabled** — Overlays are lip-synced to the narrator audio. - **Reference image required** — The presenter clip is generated from your project Reference Image the first time an overlay is needed, then cached and reused. - **Another content type required** — Overlay and Scenes + overlay modes need at least one other visual type (AI Video, AI Images, Stock Videos, Web Pages, or Web Images) for the avatar to sit on. - **Overlay position** — Choose which corner the circle overlay sits in: top-left, top-right, bottom-left, or bottom-right (default). Applied at export time. - **Overlay border (optional)** — Add a colored ring around the circle overlay with the color picker, or leave it off for no border. Applied at export time. ## Where to configure it Open **Projects**, then **Configure** your project. Select **AI Influencer** in Basics and pick the **AI Influencer mode** in the Video generation section. When overlay mode is active, the **Avatar overlay corner** and **Avatar overlay border** settings appear right below the mode. The border is off by default — pick a color to add a ring. See [How to create videos](https://vidmachine.ai/docs/guides/create-videos.md) for the full project settings reference. ## Credits for avatar overlays Avatar overlay credits are calculated from the overlay-visible seconds of video. VidMachine bills at `1 credit` per second, rounded up. Talking-head scenes are billed separately by their selected video model. ## Quick start 1. **Select AI Influencer and a mode.** Choose **Avatar overlay only** or **Scenes + overlay**. 2. **Add a reference image.** Upload a clear portrait of your presenter in project settings. 3. **Enable narrator voice.** The avatar is lip-synced to the narrator audio. 4. **Generate your video.** VidMachine generates a presenter clip from the reference image (reused for later videos), lip-syncs it to the narration, and burns the circle overlay into the final export. 5. **Publish as UGC-style Shorts/TikTok.** Schedule or publish the result to your connected YouTube Shorts, TikTok, or Instagram accounts. You can also regenerate the overlay for a single video from the video page. ## Related guides - [How to create videos](https://vidmachine.ai/docs/guides/create-videos.md) - [Automatic video generation](https://vidmachine.ai/docs/guides/automatic-video-generation.md) - [Credits & billing](https://vidmachine.ai/docs/guides/credits-and-billing.md) --- # Credits and billing VidMachine uses a credit-based system for usage. You can subscribe to a monthly plan for a recurring credit allowance, or buy pay-as-you-go credits that never expire. Each action (generating ideas, screenplays, AI video, narrator audio, captions, cover images) consumes credits. There is no separate pool for the API — API usage draws from the same balance as the dashboard. ## How the credit system works After you create an account, add credits by subscribing or purchasing pay-as-you-go credits (from $10). Subscription plans include a monthly credit allowance that resets each billing cycle. Pay-as-you-go credits stay in your wallet until you use them. Credits are consumed whenever you or the system runs AI operations: generating video ideas, writing screenplays, generating video clips or images, generating narrator voice (xAI, Speechify, or ElevenLabs), adding captions, or creating cover photos. Heavier operations — such as full AI video generation (e.g. Veo, Sora) — cost more per second of output than lighter ones (e.g. idea generation, transcript). Your balance is shown in the dashboard; if you run out, generation and API calls that require credits will fail until you buy more credits or your subscription renews. Subscription credits typically do not roll over; pay-as-you-go credits never expire. ## Pay-as-you-go vs subscription **Pay-as-you-go** — Buy credits in dollar amounts from $10 to $1,000 ($0.02 per credit). Credits never expire. Optional auto top-up can refill your balance when it runs low. Best for trying the workflow or occasional projects. **Monthly subscription** — Plans from $39/mo include a larger monthly credit allowance. New subscribers get first-month bonus credits: +1,000 on Starter and above. Best for consistent posting and automated channels. Cancel anytime via the billing portal. ## What uses credits Credits are used for the following. Exact amounts can vary by model and options; the dashboard and pricing page give guidance for your plan. **Generate video ideas** — Each batch of ideas uses `1` credit (batch size is configurable per project, default 10 titles). Used when you click “Generate Video Ideas” and when automatic video generation refills the idea pool. **Generate transcript or full idea** — Narrator projects: `1` credit per transcript. Non-narrator AI Video projects: `1` credit per full idea expansion. With **web search** enabled on a project, ideas, transcripts, and full ideas each cost `3` credits instead of `1`. **Generate screenplay** — Turning an idea into a full screenplay uses a fixed number of credits per video. The screenplay drives the scene structure and narration; it’s required before AI video or image generation runs. **AI video generation** — Generating video clips (AI Video project type) uses credits per second of video, and the rate depends on the model (e.g. Veo, Sora, Grok). Longer videos and premium models cost more. The system uses your project’s video model priority; if the first model fails, fallbacks are tried and also consume credits on use. **AI image generation** — When generating images (for AI Video start frames or for AI Images projects), each image uses a set number of credits per model (for example, OpenAI GPT Image 2 `gpt-image-2` uses `10` credits per image; other models vary — see [AI models](https://vidmachine.ai/models) and [Pricing](https://vidmachine.ai/pricing)). Image-heavy workflows (e.g. AI Images with many scenes) use more image credits. **Narrator voice** — If you enable the narrator for a project, generating the voice-over is billed by transcript length, rounded up. Speechify voices cost `1` credit per `500` characters, xAI voices cost `1` credit per `300` characters, and ElevenLabs voices cost `1` credit per `50` characters. Narrator is on by default on new projects and optional for every content type except AI Influencer, where it is required. **Captions and cover photo** — Enabling captions uses a small number of credits per video for transcription and styling. Enabling “Generate cover photo” uses credits per cover image. Both are optional and can be turned off to save credits. **Final video export** — Stitching scenes into the finished MP4 (ffmpeg export) costs `3` credits per successful export. Failed exports are not charged. **AI Influencer avatar overlays** — For AI Influencer projects in **Avatar overlay only** or **Scenes + overlay** mode, VidMachine generates a lip-synced circle avatar and overlays it in a corner of the final video (configurable per project, bottom-right by default). This is billed at `1 credit` per second of overlay-visible video, rounded up. Full-screen talking-head scenes are billed separately by their selected lip-sync model. ## Where to see usage and billing In your account you can view your current credit balance and usage. Your plan and billing are managed from the dashboard (e.g. Billing or account settings). For pricing tiers, feature comparison, and how many credits each plan includes, see the [Pricing](https://vidmachine.ai/pricing) page. If you use the API, the same balance is used; create and manage API keys under API Keys in the sidebar after login. ## Tips for managing credits Choose video duration and models to match your goals: shorter videos and efficient models use fewer credits per video. Use 2–3 models in priority order so the system can fall back without you manually retrying. For automatic video generation, set “Generate days ahead” so videos are ready in time without last-minute runs; the schedule modal shows an Auto Mode credits estimate based on your post days and project settings. Turn off narrator or captions if you don’t need them. Check your balance before large batches or before enabling auto-generate on multiple projects. ## Related guides - [Quick start](https://vidmachine.ai/docs/getting-started.md) - [How to create videos](https://vidmachine.ai/docs/guides/create-videos.md) - [Automatic video generation](https://vidmachine.ai/docs/guides/automatic-video-generation.md) - [Documentation home](https://vidmachine.ai/docs/) --- # 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) --- # MCP server The VidMachine MCP server connects your account to AI assistants and coding agents that speak the [Model Context Protocol](https://modelcontextprotocol.io) — Claude Code, OpenAI Codex, Cursor, and other MCP clients. It uses the same API keys, credit balance, and business rules as the [REST API](https://vidmachine.ai/docs/api.md), so anything you generate through an assistant is visible in your dashboard. ## Endpoint The server speaks JSON-RPC 2.0 over a single stateless HTTPS `POST` and returns JSON responses: ``` https://vidmachine.ai/api/mcp ``` ### Authentication Authenticate with the same API key you use for the REST API, sent as a Bearer token. Create one under [API Keys](https://vidmachine.ai/api-keys) (after login). ``` Authorization: Bearer vidm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` ## Set up a client In every case you provide the endpoint URL above and an `Authorization: Bearer ` header. ### Claude Code Put your key in the environment, then register VidMachine as an HTTP MCP server. The single quotes keep your shell from expanding the variable, so the key is not written to the config in plaintext. ```bash export VIDMACHINE_API_KEY=vidm_... claude mcp add --transport http vidmachine \ https://vidmachine.ai/api/mcp \ --header 'Authorization: Bearer ${VIDMACHINE_API_KEY}' ``` Run `claude mcp list` to confirm it connected. ### Project config (.mcp.json) The same placeholder works in a project `.mcp.json`, which is the safer form when the file is committed. ```json { "mcpServers": { "vidmachine": { "type": "http", "url": "https://vidmachine.ai/api/mcp", "headers": { "Authorization": "Bearer ${VIDMACHINE_API_KEY}" } } } } ``` ### Codex CLI Add an entry to `~/.codex/config.toml`. The `bearer_token_env_var` field names an environment variable that holds your key — it is not the key itself. ```toml [mcp_servers.vidmachine] url = "https://vidmachine.ai/api/mcp" bearer_token_env_var = "VIDMACHINE_MCP_KEY" ``` ```bash export VIDMACHINE_MCP_KEY="vidm_..." # raw key, no "Bearer " prefix ``` Open a new terminal and run `codex mcp list` to confirm. ### Cursor and other clients In Cursor, add an MCP server of type **http** with the URL above and an `Authorization` header, or reuse the `.mcp.json` entry. Any client that supports Streamable HTTP and a custom header works the same way. ## Tools Your assistant reads each tool's input schema automatically, so you rarely need to know the argument names. Read tools never change anything; write tools act on your account and use credits where noted. ### Read tools | Tool | What it does | |---|---| | `list_projects` | List every project with its content types, model priorities, and schedule. | | `list_videos` | List videos, filtered by project, status, limit, and offset. | | `list_models` | Catalog of callable image and video models with inputs and credit pricing. | | `list_generations` | List API generations, filtered by status and model. | | `get_generation` | Poll one generation for its status, output URL, and credits charged. | ### Write tools | Tool | What it does | |---|---| | `create_project` | Create a project; title is required, all other settings optional. | | `update_project` | Update any subset of a project's settings. | | `generate_ideas` | Generate 10 video ideas for a project. Uses credits. | | `generate_video` | Run the full one-shot pipeline for an idea. Uses credits. | | `update_video` | Edit a video's title, status, post time, or cover. Same rules as the dashboard. | | `create_generation` | Queue any catalog model for image or video generation. | ## Errors A missing or invalid API key returns HTTP `401` with a JSON-RPC error. Tool failures return a result with `isError: true` and the same codes as the REST API: `402` insufficient credits, `404` not found, `429` too many generations in flight. ## Credits MCP usage draws on the same credit balance as your dashboard. `create_generation` charges only when the model succeeds and failed generations are free. Up to 10 queued or processing generations per account at a time. See [Credits & billing](https://vidmachine.ai/docs/guides/credits-and-billing.md). ## Related - [API reference](https://vidmachine.ai/docs/api.md) — the REST API that the MCP tools call. - [AI models](https://vidmachine.ai/models) — the catalog returned by `list_models`. - [Programmatic overview](https://vidmachine.ai/api) - [Docs home](https://vidmachine.ai/docs/) - [Manage API keys](https://vidmachine.ai/api-keys) (login required)