Streamable HTTP · Protocol 2025-06-18

Vid.AI MCP Reference

Connect an MCP-compatible AI client to Vid.AI. Your assistant can do what you do in the editor: pick narrators, custom voices and voice engines, image styles, visual direction, avatars and every upgrade, then create, edit, generate and render Faceless Shorts and Faceless Videos. It gets the exact credit cost first, and every charge is capped by the number you approved.

MCP endpoint

https://vid.ai/api/mcp

Getting started

Connection options

Connect with OAuth for a simple browser sign-in, or use an MCP key when your client supports custom headers. Both options provide the same Vid.AI tools.

Method	Best for	Setup	Credential
OAuth	Interactive MCP clients with browser sign-in.	Usually only the MCP endpoint is required.	Managed automatically by the client.
MCP key	Server tools, local clients, and explicit header configuration.	Endpoint plus a bearer header.	You choose an optional expiry and can revoke it anytime.

Getting started

Connect with OAuth

1. Add a remote or Streamable HTTP MCP server in your client.
2. Enter https://vid.ai/api/mcp as the server URL.
3. Start the connection. A compatible client discovers Vid.AI's OAuth metadata and opens browser sign-in.
4. Sign in to the Vid.AI account whose projects and credits the client should use, check the app name and where it sends you, and choose Allow.

Connection details

{
  "name": "vidai",
  "url": "https://vid.ai/api/mcp"
}

Secure sign-in

Compatible clients handle sign-in and token renewal automatically. The connection uses PKCE and the mcp:tools scope.

Discovery endpoints

Protected resourcehttps://vid.ai/.well-known/oauth-protected-resource/api/mcp

Authorization serverhttps://vid.ai/.well-known/oauth-authorization-server

Authorizehttps://vid.ai/oauth/authorize

Tokenhttps://vid.ai/oauth/token

Dynamic registrationhttps://vid.ai/oauth/register

Getting started

Connect with an MCP key

1. Open Developer settings and select MCP connectors.
2. Open Streamable HTTP, name the key, and optionally set an expiration date.
3. Copy the key when it is shown. The complete secret cannot be viewed again.
4. Send it on every MCP request as a bearer credential.

Authorization header

Authorization: Bearer vidai_mcp_your_key

Key security

Keys begin with vidai_mcp_. Keep them out of URLs, browser code, public repositories, screenshots, and logs. Each account can have up to 10 active MCP keys. Revoke an exposed key immediately.

Getting started

Client configuration

Clients use different configuration file names and labels, but a direct-key setup contains the same endpoint and header values. Use OAuth instead when a client does not allow custom headers.

Generic Streamable HTTP configuration

{
  "mcpServers": {
    "vidai": {
      "type": "http",
      "url": "https://vid.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer vidai_mcp_your_key"
      }
    }
  }
}

Client-specific syntax

Some clients call the transport http, streamable-http, or simply remote. Follow the client's schema while keeping the URL and authorization header exactly as shown.

Getting started

Tool and response conventions

Transport: Remote Streamable HTTP at https://vid.ai/api/mcp.
Arguments: Each tool lists the fields it accepts. Extra fields and invalid values are rejected.
Results: Successful calls provide the same JSON in a text content block and in structuredContent.
Errors: Failed tool calls return isError: true with a clear error code and message.
Dates: Timestamps are ISO 8601 UTC strings.
Asynchronous work: Generation and rendering tools return a state immediately. Poll the matching status tool every 10 seconds for Shorts and every 30 seconds for long-form videos (progress.pollAfterSeconds).
Credits: Credit fields are snake_case: max_credits in, credits_charged and balance_after out.
Repeat calls: Calling generate or render again while it is running will not start a duplicate. Calling it after completion returns the completed state.

MCP tool result shape

{
  "content": [
    {
      "type": "text",
      "text": "{\"projectId\":\"cmu_project_id\",\"state\":\"generation_started\"}"
    }
  ],
  "structuredContent": {
    "projectId": "cmu_project_id",
    "state": "generation_started"
  }
}

Getting started

Video-generation workflow

Discover

list_voices, list_image_styles, list_avatars and list_upgrades show what this account can use.

Estimate

estimate_credits returns the itemised cost and the balance after.

Confirm

Show the estimate to the user and get a clear yes.

Create

Create the project with max_credits and receive editable sections.

Edit

Optionally replace section scripts, titles, content, or images.

Generate

Start narration, captions and visuals with the confirmed options and max_credits.

Poll media

Wait for a generated or failed state; progress shows the time left.

Render

Start the final video render (included).

Poll render

Wait for generated and share video.url.

Polling interval

Poll the matching status tool every 10 seconds for Shorts and every 30 seconds for long-form videos. Stop on generated or failed. Status tools are read-only and never start work. Cinematic intros, moving images and avatars add minutes to generation.

Credits and voices

Credits and confirmation

Every price comes from the server's own pricing code, the same code that charges. estimate_credits returns an itemised quote before anything is charged, and each charging tool takes a max_credits cap: if the server's price for that call is higher, the call is refused and nothing is charged.

Always confirm: show the user the line items, the total and their balance after, and wait for a clear yes before create_*, generate_* or add_custom_voice.
Per step: credits_by_step says what each tool charges. Pass that number as max_credits.
Long-form: creation charges the script; generation charges the rest when it starts (minutes, voice engine, custom voice, avatar, upgrades). Add-ons that are not delivered are refunded; a failed generation is refunded in full.
Shorts: creation charges the Short and any Moving frames; generation charges a custom voice's premium. Stock narrators add nothing.
Rendering is included.
Results: charging tools return credits_charged and balance_after; get_project shows what a project has cost so far.

Plan and availability

Upgrades follow your plan and what is switched on for everyone. list_upgrades shows what you can use; a paid option you can't use is refused with upgrade_unavailable and a reason, never dropped silently.

Core tools

TOOLhow_to_create_full_video_creation_to_render

Get the full video workflow guide

Return the complete workflow for Faceless Shorts and Faceless Videos: discover options, estimate credits, confirm with the user, create, edit, generate, poll, render and share. Includes allowed durations, image styles, narrator metadata, the confirmation rules, polling intervals and links to this documentation. This read-only tool does not create or render a video.

This tool does not accept arguments.

Access and credits

The result includes a Markdown guide and structuredContent with workflow steps, narrator options, documentationUrl, and workflowDocumentationUrl. See Complete workflows below for example sequences.

Tool arguments

{}

Core tools

TOOLget_user

Get authenticated user

Return the Vid.AI account attached to the active OAuth access token or MCP key, including the current plan and credit balance.

This tool does not accept arguments.

Tool arguments

{}

Structured result

{
  "user": {
    "id": "clx_user_id",
    "email": "[email protected]",
    "name": "Creator",
    "subscriptionType": "PRO",
    "credit": 240
  }
}

Core tools

TOOLget_credit_balance

Get credit balance

Return the current credit balance (read fresh), the plan, whether it includes the Plus and Pro add-ons, the plan's longest long-form video, and the base prices.

This tool does not accept arguments.

Tool arguments

{}

Structured result

{
  "balance": 240,
  "plan": {
    "subscriptionType": "PRO",
    "paid": true,
    "premiumMedia": true,
    "maxLongFormMinutes": 20
  },
  "pricing": {
    "longFormCreditsPerMinute": 5,
    "longFormCreationCredits": 5,
    "shortCredits": 5,
    "renderCredits": 0
  }
}

Core tools

TOOLget_projects

List projects

Return visible projects owned by the authenticated account, with pagination and optional status, tool, and name filters.

Name	Type	Required	Description
page	integer	No	Page number. Defaults to 1.
limit	integer	No	Items per page. Defaults to 20; maximum 100.
status	enum	No	One of: DRAFT, ONGOING, MEDIA_GENERATING, MEDIA_GENERATED, RENDERING, GENERATED.
tool	string	No	Exact tool identifier, such as faceless-shorts or faceless-video.
search	string	No	Project-name search, up to 100 characters.

Tool arguments

{
  "page": 1,
  "limit": 20,
  "tool": "faceless-shorts",
  "status": "MEDIA_GENERATED"
}

Structured result

{
  "projects": [
    {
      "id": "cmu2cthbl0001ijs3yk8nkgb6",
      "name": "History in 60 seconds",
      "tool": "faceless-shorts",
      "status": "MEDIA_GENERATED",
      "inputType": "PROMPT",
      "thumbnail": "https://storage.example/image.webp",
      "latestVersion": 2,
      "createdAt": "2026-09-15T08:10:00.000Z",
      "updatedAt": "2026-09-15T08:14:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalItems": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

Core tools

TOOLget_project

Get one project

Return one of your projects with every current setting (narrator or custom voice, voice engine, image style, upgrades, avatar, visual direction), its script and sections, its status, the video link once rendered, the credits spent on it and the next tool to call.

Name	Type	Required	Description
projectId	string	Yes	Faceless Shorts or Faceless Video project ID.

Tool arguments

{
  "projectId": "cmu_video_project_id"
}

Structured result

{
  "project": {
    "id": "cmu_video_project_id",
    "name": "The future of robotics",
    "videoType": "faceless_video",
    "status": "DRAFT",
    "editorUrl": "https://vid.ai/tools/faceless-video?id=cmu_video_project_id"
  },
  "settings": {
    "durationMinutes": 5,
    "voice": { "narrator": "matt" },
    "voiceEngine": "natural",
    "visualDirection": "Only show factories and labs.",
    "motionGraphics": true,
    "avatar": { "enabled": false }
  },
  "script": "The future of robotics\n\n\nMachines enter daily life\n\nHumanoid robots are moving...",
  "sections": [{ "index": 0, "title": "Machines enter daily life", "content": "Humanoid robots are moving..." }],
  "video": null,
  "credits": { "spent_on_project": 5, "charged": 5, "refunded": 0 },
  "next": "generate_faceless_video (estimate_credits first)"
}

Core tools

TOOLget_script

Get or download the script

Return the project's script as plain text, the same text as the editor's Download script button, with a suggested file name, the sections and the word count.

Name	Type	Required	Description
projectId	string	Yes	Faceless Shorts or Faceless Video project ID.

Tool arguments

{
  "projectId": "cmu_video_project_id"
}

Structured result

{
  "projectId": "cmu_video_project_id",
  "name": "The future of robotics",
  "videoType": "faceless_video",
  "fileName": "The_future_of_robotics.txt",
  "text": "The future of robotics\n\n\nMachines enter daily life\n\nHumanoid robots are moving...",
  "sections": [{ "index": 0, "title": "Machines enter daily life", "content": "Humanoid robots are moving..." }],
  "wordCount": 742
}

Discover options

TOOLlist_voices

List narrators and custom voices

Return every stock narrator (key, name, gender, accent, category, style tags, pace, preview URL, engines) and your saved custom voices (customVoiceId, name, preview, measured pace, extra credits per minute).

This tool does not accept arguments.

Tool arguments

{}

Structured result

{
  "narrators": [
    {
      "key": "matt",
      "name": "Matt",
      "gender": "male",
      "accent": null,
      "tags": ["male", "deep"],
      "wordsPerSecond": 2.56,
      "previewUrl": "https://vid-ai-main.nyc3.cdn.digitaloceanspaces.com/others/assets/ai-voices/elevenlabs/matt_v2.mp3",
      "engines": ["classic", "natural"],
      "appliesTo": ["faceless_shorts", "faceless_video"]
    }
  ],
  "customVoices": [
    {
      "customVoiceId": "k9Xc2...",
      "name": "Nia",
      "pace": "Slower than average: ~2.1 words/s",
      "extraCreditsPerMinute": 1
    }
  ],
  "customVoiceSettings": { "enabled": true, "eligible": true, "limit": 5, "saved": 1, "setupCredits": 2 }
}

Discover options

TOOLlist_voice_engines

List voice engines

Return the long-form narration engines: classic (the default) and natural (a more human delivery at a calmer pace), with the extra credits per started minute each costs.

This tool does not accept arguments.

Tool arguments

{}

Structured result

{
  "engines": [
    { "key": "classic", "label": "Classic", "default": true, "extraCreditsPerMinute": 0, "paceFactor": 1 },
    { "key": "natural", "label": "Natural", "default": false, "extraCreditsPerMinute": 1, "paceFactor": 0.86 }
  ]
}

Discover options

TOOLlist_image_styles

List AI image styles

Return every AI image style with a preview image. Use the key as imageTheme for Faceless Shorts, or as imageStyle (with aiImages true) for long-form videos.

This tool does not accept arguments.

Tool arguments

{}

Structured result

{
  "styles": [
    { "key": "cinematic", "name": "Cinematic", "previewImageUrl": "https://vid.ai/ai-themes/cinematic.webp" }
  ],
  "defaultStyle": "cinematic"
}

Discover options

TOOLlist_avatars

List avatars

Return the animated avatars you can put in a long-form video (your own and the built-in ones) with preview media, the placements that set where the avatar appears, and what each placement costs. New avatars are made in the Vid.AI app.

This tool does not accept arguments.

Tool arguments

{}

Structured result

{
  "avatars": [
    { "avatarId": "JX-nB41sCGC_YJcsBz8BW", "avatarSource": "GLOBAL", "name": "Coby", "type": "SVG", "parts": [{ "type": "body", "url": "https://vid.ai/avatars/global-v2/..." }], "ready": true }
  ],
  "placements": [
    { "placement": "intro-only", "label": "Intro only", "animatedAvatarCredits": 10 },
    { "placement": "intro-outro-20", "label": "Intro, outro + 20%", "animatedAvatarCredits": 30 }
  ]
}

Discover options

TOOLlist_upgrades

List the upgrades you can use

Return which upgrades your account can use right now, their credit prices, plan locks and the parameter that turns each on: motion graphics, cinematic intro (Standard and Premium), HD images, moving images, Moving frames for Shorts, animated avatar and email when ready. Offer only upgrades with available true.

This tool does not accept arguments.

Tool arguments

{}

Structured result

{
  "plan": { "subscriptionType": "PRO", "paid": true, "premiumMedia": false, "maxLongFormMinutes": 10 },
  "upgrades": [
    { "key": "cinematicIntro.premium", "label": "Cinematic intro (Premium)", "available": false, "planLock": "Plus and Pro plans", "unavailableReason": "Plus and Pro plans only.", "parameter": "cinematicIntro: 'premium' on generate_faceless_video" },
    { "key": "movingImages", "label": "Moving images", "available": true, "credits": 2, "creditsUnit": "per image", "addsMinutes": 3 }
  ]
}

Credits and voices

TOOLestimate_credits

Estimate credits before charging

Return the exact, itemised credit cost of a video before anything is charged, computed with the same functions the server charges with. Use it for a new video (videoType, project, generate) or for what is left to pay on an existing project (projectId, generate). Read-only.

Name	Type	Required	Description
videoType	'faceless_video' \| 'faceless_shorts'	Yes	Which kind of video.
project	object	Conditional	The create tool's arguments without name (prompt or script, duration, narrator or customVoiceId, voiceEngine, visualDirection; for Shorts also imageTheme and movingFrames). Use for a new video.
projectId	string	Conditional	An existing project. Provide projectId or project.
generate	object	No	generate_faceless_video options (aiImages, imageStyle, motionGraphics, cinematicIntro, hdImages, movingImages, avatar, visualDirection, memes, addChapterTitles). Long-form only.

Access and credits

Show line_items, total_credits and balance_after to the user and get a clear yes before any charging call. Then pass the matching credits_by_step number as max_credits. Moving images and Moving frames are priced for the most images or scenes the video can have (total_is_maximum), and what is not made is refunded.

Tool arguments

{
  "videoType": "faceless_video",
  "project": {
    "prompt": "Explain how humanoid robots may change daily life",
    "duration": 5,
    "narrator": "matt",
    "voiceEngine": "natural"
  },
  "generate": {
    "aiImages": true,
    "imageStyle": "cinematic",
    "cinematicIntro": "standard",
    "movingImages": "first"
  }
}

Structured result

{
  "videoType": "faceless_video",
  "stage": "new_video",
  "line_items": [
    { "key": "script", "label": "Script and project", "credits": 5, "charged_by": "create_faceless_video" },
    { "key": "video", "label": "Video", "credits": 20, "charged_by": "generate_faceless_video", "detail": "5 min at 5 credits a minute, less the 5 paid for the script" },
    { "key": "voice_engine", "label": "Natural voice engine", "credits": 5, "charged_by": "generate_faceless_video" },
    { "key": "motion_graphics", "label": "Motion graphics", "credits": 0, "charged_by": "generate_faceless_video", "detail": "Included" },
    { "key": "cinematic_intro", "label": "Cinematic intro (Standard)", "credits": 5, "charged_by": "generate_faceless_video" },
    { "key": "moving_images", "label": "Moving images", "credits": 10, "charged_by": "generate_faceless_video", "up_to": true },
    { "key": "render", "label": "Rendering", "credits": 0, "charged_by": "render_faceless_video" }
  ],
  "credits_by_step": { "create_faceless_video": 5, "generate_faceless_video": 40, "render_faceless_video": 0 },
  "total_credits": 45,
  "total_is_maximum": true,
  "balance": 240,
  "balance_after": 195,
  "sufficient_credits": true,
  "unavailable_options": [],
  "blocking_issues": []
}

Credits and voices

TOOLadd_custom_voice

Add a custom voice

Save a voice from the ElevenLabs Voice Library to your account, by voice ID or Voice Library link, so Shorts and long-form videos can narrate with it. Its speaking pace is measured so video length and credits follow it. Charges 2 credits once; a voice you already saved is returned free. Up to 5 saved voices.

Name	Type	Required	Description
source	string	Yes	Voice ID or Voice Library link.
max_credits	integer	No	Refuse, charging nothing, if the setup costs more.

Tool arguments

{
  "source": "https://elevenlabs.io/app/voice-library?voiceId=k9Xc2...",
  "max_credits": 2
}

Structured result

{
  "voice": { "customVoiceId": "k9Xc2...", "name": "Nia", "pace": "Slower than average: ~2.1 words/s" },
  "alreadySaved": false,
  "credits_charged": 2,
  "balance_after": 238
}

Credits and voices

TOOLremove_custom_voice

Remove a custom voice

Remove one of your saved custom voices. Videos already made with it keep working.

Name	Type	Required	Description
customVoiceId	string	Yes	customVoiceId from list_voices.

Tool arguments

{
  "customVoiceId": "k9Xc2..."
}

Structured result

{
  "removed": true,
  "customVoiceId": "k9Xc2...",
  "credits_charged": 0
}

Faceless Shorts

TOOLcreate_faceless_shorts

Create a Faceless Shorts project

Create a project, generate its scripts and section images, and return editable sections. Exactly one of prompt or script must be supplied.

Name	Type	Required	Description
name	string	Yes	Project name, 1-100 characters.
prompt	string	Conditional	Generation prompt. Required when script is omitted.
script	string	Conditional	Complete source script, up to 7,200 characters and at most 180 seconds of narration for a 60 second Short (225 for 90). Required when prompt is omitted.
duration	60 \| 90	Yes	Requested duration in seconds.
narrator	enum	Conditional	Narrator key from list_voices. Provide narrator or customVoiceId.
customVoiceId	string	Conditional	One of your saved custom voices (list_voices, add_custom_voice).
imageTheme	enum	Yes	AI image style from list_image_styles.
visualDirection	string	No	Directs the images separately from the script, up to 300 characters.
movingFrames	'off' \| 'first' \| 'all'	No	Animate the first scene or every scene. Defaults to off.
movingFramesModel	enum	No	Video model for Moving frames: wan-2.2 (default), seedance-1-pro-fast or kling-2.5-turbo-pro. Credits and plan per model in list_upgrades; Plus and Pro models are refused on other plans.
max_credits	integer	No	Refuse, charging nothing, if this step costs more.

Access and credits

An active paid subscription is required. This step charges the Short and any Moving frames (scenes that fail are refunded). A custom voice adds its premium when the voiceover is generated. The result includes credits_charged and balance_after.

Tool arguments

{
  "name": "The lost city of Atlantis",
  "prompt": "Explain the most compelling theories about Atlantis",
  "duration": 60,
  "narrator": "matt",
  "imageTheme": "cinematic",
  "movingFrames": "first",
  "max_credits": 7
}

Structured result

{
  "credits_charged": 7,
  "balance_after": 233,
  "project": {
    "id": "cmu2cthbl0001ijs3yk8nkgb6",
    "name": "The lost city of Atlantis",
    "tool": "faceless-shorts",
    "status": "DRAFT",
    "inputType": "PROMPT",
    "latestVersion": 0,
    "createdAt": "2026-09-15T08:10:00.000Z",
    "updatedAt": "2026-09-15T08:10:00.000Z"
  },
  "version": {
    "id": "cmu_version_id",
    "number": 0,
    "status": "DRAFT",
    "createdAt": "2026-09-15T08:10:00.000Z"
  },
  "sections": [
    {
      "index": 0,
      "script": "For centuries, sailors told stories of a lost city...",
      "image": "https://storage.example/image_0.webp"
    }
  ]
}

Faceless Shorts

TOOLedit_faceless_shorts_sections

Edit Faceless Shorts sections

Replace the script, image, or both for one or more generated sections before media generation.

Name	Type	Required	Description
projectId	string	Yes	Faceless Shorts project ID.
sections	array	Yes	Between 1 and 50 unique section updates.
sections[].index	integer	Yes	Zero-based existing section index.
sections[].script	string	Conditional	Replacement narration, up to 7,200 characters. The whole script must stay within 180 seconds of narration for a 60 second Short (225 for 90).
sections[].image	HTTP URL	Conditional	Replacement image URL. Provide script, image, or both.

Tool arguments

{
  "projectId": "cmu2cthbl0001ijs3yk8nkgb6",
  "sections": [
    {
      "index": 0,
      "script": "A revised opening hook for the video.",
      "image": "https://example.com/replacement.webp"
    },
    {
      "index": 2,
      "script": "A revised closing section."
    }
  ]
}

Structured result

{
  "projectId": "cmu2cthbl0001ijs3yk8nkgb6",
  "version": {
    "id": "cmu_version_id",
    "number": 2,
    "status": "DRAFT",
    "createdAt": "2026-09-15T08:12:00.000Z"
  },
  "sections": [
    {
      "index": 0,
      "script": "A revised opening hook for the video.",
      "image": "https://storage.example/replacement.webp"
    },
    {
      "index": 2,
      "script": "A revised closing section.",
      "image": "https://storage.example/image_2.webp"
    }
  ]
}

Faceless Shorts

TOOLgenerate_faceless_shorts

Start Faceless Shorts media generation

Start narration, captions, and section timing. The tool returns immediately, so use the status tool to check when generation is complete. Free with a stock narrator; a custom voice's premium is charged here and returned if narration fails.

Name	Type	Required	Description
projectId	string	Yes	Project containing generated scripts and valid storage data.
retry	boolean	No	Defaults to false. Set true only after a failed generation.
max_credits	integer	No	Refuse, charging nothing, if this step costs more.

State	Project status	Meaning
generation_started	MEDIA_GENERATING	Media generation started.
generation_in_progress	MEDIA_GENERATING	Generation was already active; no duplicate job was created.
generated	MEDIA_GENERATED or GENERATED	Media already exists; no regeneration occurred.

Tool arguments

{
  "projectId": "cmu2cthbl0001ijs3yk8nkgb6",
  "retry": false
}

Structured result

{
  "projectId": "cmu2cthbl0001ijs3yk8nkgb6",
  "state": "generation_started",
  "status": "MEDIA_GENERATING",
  "message": "Media generation started. Check again later.",
  "progress": { "stage": "generating_media", "percent": 0, "estimatedSecondsRemaining": 90, "pollAfterSeconds": 10 },
  "credits_charged": 1,
  "balance_after": 232
}

Faceless Shorts

TOOLget_faceless_shorts_generation_status

Get Faceless Shorts generation status

Check the current media-generation state. This tool only checks status and does not start or retry generation.

Name	Type	Required	Description
projectId	string	Yes	Faceless Shorts project ID.

State	Project status	Meaning
not_started	DRAFT or ONGOING	Media generation has not started.
generation_in_progress	MEDIA_GENERATING	Media is being generated.
generated	MEDIA_GENERATED or GENERATED	Media generation completed.
failed	Previous status	All attempts failed; retry explicitly with the generation tool.

Tool arguments

{
  "projectId": "cmu2cthbl0001ijs3yk8nkgb6"
}

Structured result

{
  "projectId": "cmu2cthbl0001ijs3yk8nkgb6",
  "state": "generated",
  "status": "MEDIA_GENERATED",
  "message": "Media generated successfully.",
  "version": {
    "id": "cmu_media_version_id",
    "number": 3,
    "status": "MEDIA_GENERATED",
    "createdAt": "2026-09-15T08:14:00.000Z"
  }
}

Faceless Shorts

TOOLrender_faceless_shorts

Start Faceless Shorts rendering

Start the final render for a MEDIA_GENERATED project. Only one render can run for a project at a time.

Name	Type	Required	Description
projectId	string	Yes	Project whose status is MEDIA_GENERATED.
retry	boolean	No	Defaults to false. Set true only after a failed render.
emailWhenReady	boolean	No	Email the account a link when the video is ready.

Access and credits

Rendering is included: credits_charged is 0.

State	Project status	Meaning
render_started	RENDERING	Rendering started.
rendering_in_progress	RENDERING	Rendering was already active; no duplicate render was started.
generated	GENERATED	A rendered video already exists and videoLink is returned.

Tool arguments

{
  "projectId": "cmu2cthbl0001ijs3yk8nkgb6",
  "retry": false
}

Structured result

{
  "projectId": "cmu2cthbl0001ijs3yk8nkgb6",
  "state": "render_started",
  "status": "RENDERING",
  "message": "Rendering started. Check again later."
}

Faceless Shorts

TOOLget_faceless_shorts_rendering_status

Get Faceless Shorts rendering status

Check the current render state. A completed response includes the latest video URL.

Name	Type	Required	Description
projectId	string	Yes	Faceless Shorts project ID.

State	Project status	Meaning
not_ready	DRAFT, ONGOING, or MEDIA_GENERATING	Media must finish before rendering.
not_started	MEDIA_GENERATED	The project is ready, but rendering has not started.
rendering_in_progress	RENDERING	The video is rendering. progress has an estimated percent and time left.
generated	GENERATED	Rendering completed: videoLink and video (url to watch and share from our CDN, downloadUrl, fileName, thumbnail, duration), title, editorUrl and the script. Hosts that show UI display a video card with download, copy link and open in editor.
failed	MEDIA_GENERATED	All attempts failed; retry explicitly with the render tool.

Tool arguments

{
  "projectId": "cmu2cthbl0001ijs3yk8nkgb6"
}

Structured result

{
  "projectId": "cmu2cthbl0001ijs3yk8nkgb6",
  "state": "generated",
  "status": "GENERATED",
  "message": "Rendering completed successfully.",
  "version": {
    "id": "cmu_render_version_id",
    "number": 4,
    "status": "GENERATED",
    "createdAt": "2026-09-15T08:18:00.000Z"
  },
  "videoLink": "https://render.example/video.mp4",
  "video": {
    "url": "https://render.example/video.mp4",
    "thumbnailUrl": "https://storage.example/thumbnail.jpg",
    "durationSeconds": 58.4,
    "width": 1080,
    "height": 1920
  },
  "script": "The lost city of Atlantis

For centuries, sailors told stories of a lost city...",
  "progress": { "stage": "done", "percent": 100 }
}

Faceless Videos

TOOLcreate_faceless_video

Create a Faceless Video project

Create a long-form Faceless Video project and generate editable script sections. Exactly one of prompt or script must be supplied.

Name	Type	Required	Description
name	string	Yes	Project name, 1-100 characters.
prompt	string	Conditional	Generation prompt. Required when script is omitted.
script	string	Conditional	Complete source script. Required when prompt is omitted.
duration	integer	Yes	Duration in minutes, from 1 through 20. The plan may enforce a lower maximum.
narrator	enum	Conditional	Narrator key from list_voices. Provide narrator or customVoiceId.
customVoiceId	string	Conditional	One of your saved custom voices (list_voices, add_custom_voice).
voiceEngine	'classic' \| 'natural'	No	Narration engine (list_voice_engines). Defaults to classic.
visualDirection	string	No	Directs the footage and AI images separately from the script, up to 300 characters.
max_credits	integer	No	Refuse, charging nothing, if this step costs more.

Access and credits

A paid subscription is required and the balance must cover the whole video. Creation charges the script credits; generate_faceless_video charges the rest (minutes, voice premiums, avatar and upgrades). estimate_credits returns both steps. The result includes credits_charged and balance_after.

Tool arguments

{
  "name": "The future of robotics",
  "prompt": "Explain how humanoid robots may change daily life",
  "duration": 5,
  "narrator": "matt",
  "voiceEngine": "natural",
  "visualDirection": "Only show factories and labs.",
  "max_credits": 5
}

Structured result

{
  "credits_charged": 5,
  "balance_after": 235,
  "project": {
    "id": "cmu_video_project_id",
    "name": "The future of robotics",
    "tool": "faceless-video",
    "status": "DRAFT",
    "inputType": "PROMPT",
    "latestVersion": 0,
    "createdAt": "2026-09-15T09:10:00.000Z",
    "updatedAt": "2026-09-15T09:10:00.000Z"
  },
  "version": {
    "id": "cmu_video_version_id",
    "number": 0,
    "status": "DRAFT",
    "createdAt": "2026-09-15T09:10:00.000Z"
  },
  "sections": [
    {
      "index": 0,
      "title": "Machines enter daily life",
      "content": "Humanoid robots are moving from research labs into homes and workplaces..."
    }
  ]
}

Faceless Videos

TOOLedit_faceless_video_sections

Edit Faceless Video sections

Update the title, content, or both for existing sections before media generation.

Name	Type	Required	Description
projectId	string	Yes	Faceless Video project ID.
sections	array	Yes	Between 1 and 100 unique section updates.
sections[].index	integer	Yes	Zero-based existing section index.
sections[].title	string	Conditional	Replacement title, up to 500 characters.
sections[].content	string	Conditional	Replacement content, up to 100,000 characters. Provide title, content, or both.

Tool arguments

{
  "projectId": "cmu_video_project_id",
  "sections": [
    {
      "index": 0,
      "title": "Robots move beyond the lab",
      "content": "Humanoid robots are beginning to take on practical roles..."
    }
  ]
}

Structured result

{
  "projectId": "cmu_video_project_id",
  "version": {
    "id": "cmu_video_version_2",
    "number": 1,
    "status": "DRAFT",
    "createdAt": "2026-09-15T09:13:00.000Z"
  },
  "sections": [
    {
      "index": 0,
      "title": "Robots move beyond the lab",
      "content": "Humanoid robots are beginning to take on practical roles..."
    }
  ]
}

Faceless Videos

TOOLgenerate_faceless_video

Start Faceless Video media generation

Start narration, captions, stock footage and AI images, with every option the editor has. Charges the video when it starts: the minutes, voice premiums, avatar and upgrades (add-ons that are not delivered are refunded; a failed generation is refunded in full). A paid option your plan or the server does not allow is refused with upgrade_unavailable, never dropped silently.

Name	Type	Required	Description
projectId	string	Yes	Faceless Video project containing editable sections.
aiImages	boolean	No	AI images (true) or stock footage only (false).
imageStyle	enum	No	AI image style from list_image_styles. Defaults to cinematic with aiImages true. imageTheme is the older name; null means stock footage only.
addChapterTitles	boolean	No	Generate chapter-title scenes. Defaults to false.
memes	boolean	No	Add meme clips where they fit.
motionGraphics	boolean	No	Motion graphics for key facts and places. Included, on by default.
cinematicIntro	'off' \| 'standard' \| 'premium'	No	A 5 second AI video opener. Premium is for Plus and Pro.
cinematicIntroModel	enum	No	Video model for the intro: seedance-1-pro-fast (Standard), veo-3.1-fast or seedance-2.5 (Premium). Credits and plan per model in list_upgrades.
hdImages	boolean	No	Sharper AI images for the whole video. Needs aiImages; Plus and Pro.
movingImages	'off' \| 'first' \| 'all'	No	Animate the first five AI images or all of them. Needs aiImages.
movingImagesModel	enum	No	Video model for Moving images: wan-2.2 (default), seedance-1-pro-fast or kling-2.5-turbo-pro. Credits and plan per model in list_upgrades.
avatar	object	No	{ enabled, avatarId, avatarSource, placement, customCoveragePercent } from list_avatars. Omit to keep the saved setting.
visualDirection	string	No	Replaces the saved visual direction.
retry	boolean	No	Defaults to false. Set true only after a failed generation.
max_credits	integer	No	Refuse, charging nothing, if this step costs more.

State	Project status	Meaning
generation_started	MEDIA_GENERATING	Media generation started.
generation_in_progress	MEDIA_GENERATING	Generation was already active; no duplicate job was created.
generated	MEDIA_GENERATED or GENERATED	Media already exists; no regeneration occurred.

Tool arguments

{
  "projectId": "cmu_video_project_id",
  "aiImages": true,
  "imageStyle": "cinematic",
  "addChapterTitles": true,
  "cinematicIntro": "standard",
  "movingImages": "first",
  "avatar": { "enabled": true, "avatarId": "JX-nB41sCGC_YJcsBz8BW", "avatarSource": "GLOBAL", "placement": "intro-outro" },
  "max_credits": 60
}

Structured result

{
  "projectId": "cmu_video_project_id",
  "state": "generation_started",
  "status": "MEDIA_GENERATING",
  "message": "Media generation started. Check again later.",
  "progress": { "stage": "generating_media", "percent": 0, "estimatedSecondsRemaining": 735, "pollAfterSeconds": 30 },
  "credits_charged": 60,
  "balance_after": 175,
  "charge_breakdown": [
    { "key": "video", "label": "Video", "credits": 20 },
    { "key": "voice_engine", "label": "Natural voice engine", "credits": 5 },
    { "key": "avatar", "label": "Animated avatar", "credits": 20 },
    { "key": "motion_graphics", "label": "Motion graphics", "credits": 0 },
    { "key": "cinematic_intro", "label": "Cinematic intro (Standard)", "credits": 5 },
    { "key": "moving_images", "label": "Moving images", "credits": 10, "up_to": true }
  ]
}

Faceless Videos

TOOLget_faceless_video_generation_status

Get Faceless Video generation status

Check the current media-generation state without starting or retrying generation.

Name	Type	Required	Description
projectId	string	Yes	Faceless Video project ID.

State	Project status	Meaning
not_started	DRAFT or ONGOING	Media generation has not started.
generation_in_progress	MEDIA_GENERATING	Media is being generated.
generated	MEDIA_GENERATED or GENERATED	Media generation completed.
failed	Previous status	All attempts failed; retry explicitly with the generation tool.

Tool arguments

{
  "projectId": "cmu_video_project_id"
}

Structured result

{
  "projectId": "cmu_video_project_id",
  "state": "generation_in_progress",
  "status": "MEDIA_GENERATING",
  "message": "Media generation is already in progress. Check again later.",
  "progress": {
    "stage": "generating_media",
    "startedAt": "2026-09-15T09:14:00.000Z",
    "elapsedSeconds": 240,
    "estimatedTotalSeconds": 735,
    "estimatedSecondsRemaining": 495,
    "percent": 33,
    "percentIsEstimate": true,
    "pollAfterSeconds": 30
  }
}

Faceless Videos

TOOLrender_faceless_video

Start Faceless Video rendering

Start the final render for a MEDIA_GENERATED Faceless Video project. Use the status tool to check when it is complete.

Name	Type	Required	Description
projectId	string	Yes	Faceless Video project whose status is MEDIA_GENERATED.
retry	boolean	No	Defaults to false. Set true only after a failed render.
emailWhenReady	boolean	No	Email the account a link when the video is ready.

Access and credits

Rendering is included: credits_charged is 0.

State	Project status	Meaning
render_started	RENDERING	Rendering started.
rendering_in_progress	RENDERING	Rendering was already active; no duplicate render was started.
generated	GENERATED	A rendered video already exists and videoLink is returned.

Tool arguments

{
  "projectId": "cmu_video_project_id",
  "retry": false
}

Structured result

{
  "projectId": "cmu_video_project_id",
  "state": "render_started",
  "status": "RENDERING",
  "message": "Rendering started. Check again later."
}

Faceless Videos

TOOLget_faceless_video_rendering_status

Get Faceless Video rendering status

Check the current render state without starting or retrying a render. Completion includes the latest video URL.

Name	Type	Required	Description
projectId	string	Yes	Faceless Video project ID.

State	Project status	Meaning
not_ready	DRAFT, ONGOING, or MEDIA_GENERATING	Media must finish before rendering.
not_started	MEDIA_GENERATED	Media is ready, but rendering has not started.
rendering_in_progress	RENDERING	The video is rendering. progress has an estimated percent and time left.
generated	GENERATED	Rendering completed: videoLink and video (url to watch and share from our CDN, downloadUrl, fileName, thumbnail, duration), title, editorUrl and the script. Hosts that show UI display a video card with download, copy link and open in editor.
failed	MEDIA_GENERATED	All attempts failed; retry explicitly with the render tool.

Tool arguments

{
  "projectId": "cmu_video_project_id"
}

Structured result

{
  "projectId": "cmu_video_project_id",
  "state": "generated",
  "status": "GENERATED",
  "message": "Rendering completed successfully.",
  "version": {
    "id": "cmu_video_render_version",
    "number": 3,
    "status": "GENERATED",
    "createdAt": "2026-09-15T09:35:00.000Z"
  },
  "videoLink": "https://render.example/faceless-video.mp4",
  "video": {
    "url": "https://render.example/faceless-video.mp4",
    "thumbnailUrl": "https://storage.example/thumbnail.jpg",
    "durationSeconds": 301.2,
    "width": 1920,
    "height": 1080
  },
  "script": "The future of robotics


Machines enter daily life

Humanoid robots are moving...",
  "progress": { "stage": "done", "percent": 100 }
}

Reference

Allowed values

Faceless Shorts durations

60, 90 seconds

Faceless Shorts narrators

mattadamstonerachelmatildapriyam-v2adamkaylatimmyandyivanthemightymichaelmouserudraallisonrusselljessicalilyWolffsantaClaustylerrichardYuryanfredericksurreydariansawyereddiealiciajadelawrencecalebtaliawarrenkaelenflorencewyatt

Faceless Shorts image themes

naturalanimecinematiccomic-artisometricwater-colorline-drawinggraffiti-artpixel-artoil-paintingneon-artcubism

Faceless Video durations

1-20 minutes. The account plan may set a lower maximum.

Faceless Video narrators

bill is retired. It still works and new projects get tyler. Projects already made with it keep their voice.

Faceless Video image themes

Pass one as imageStyle with aiImages: true, or aiImages: false for stock footage only.

naturalanimecinematiccomic-artisometricwater-colorline-drawinggraffiti-artpixel-artoil-paintingneon-artcubism

Voice engines (long-form)

classicnatural

Upgrade values

cinematicIntro: off, standard, premium
movingImages (long-form) and movingFrames (Shorts): off, first, all
motionGraphics, hdImages, memes: true or false
emailWhenReady (render tools): true or false

Avatar placements

intro-onlyintro-outrointro-outro-10intro-outro-20intro-outro-30custom

Project statuses

DRAFTONGOINGMEDIA_GENERATINGMEDIA_GENERATEDRENDERINGGENERATED

Reference

Errors

A missing, invalid, expired, or revoked credential returns 401. Tool errors include an error.code and a readable message.

401 response

{
  "error": "invalid_token",
  "error_description": "A valid MCP bearer credential is required."
}

Tool error result

{
  "content": [
    {
      "type": "text",
      "text": "{\"error\":{\"code\":\"insufficient_credits\",\"message\":\"The account does not have enough credits.\"}}"
    }
  ],
  "structuredContent": {
    "error": {
      "code": "insufficient_credits",
      "message": "The account does not have enough credits."
    }
  },
  "isError": true
}

Category	Common codes	Meaning
Authentication	invalid_token	The bearer credential is missing, invalid, expired, revoked, or attached to a disabled account.
Billing	subscription_required, insufficient_credits, max_credits_exceeded	The plan or balance does not allow the operation, or it costs more than max_credits. Nothing was charged.
Options	upgrade_unavailable, invalid_options, invalid_visual_direction	A requested option is not available for this plan or project (the message says why), or options conflict.
Voices and avatars	invalid_narrator, custom_voices_unavailable, custom_voice_not_found, limit_reached, daily_limit_reached, not_found, avatar_not_found, invalid_avatar_config	A narrator, custom voice or avatar is not one you can use, or a voice limit was reached.
Project	project_not_found, invalid_project_state, project_state_changed	The project is missing, belongs to another account, is not ready, or changed while work was starting.
Input	duration_limit_exceeded, script_duration_exceeded, invalid_narrator, section_not_found	A requested value or section does not satisfy the operation contract.
Images	invalid_image_url, image_download_failed, invalid_image, image_too_large	A replacement image could not be accepted.
Generation	media_generation_failed, media_generation_unavailable	Generation could not start or finish.
Rendering	render_state_changed, render_failed, render_unavailable	Rendering could not start or finish, or the project changed.
Server	internal_error	An unexpected error occurred.

Safe retry behavior

Retry generation or rendering with retry: true only after the matching status tool returns failed with retryable: true.

Reference

Complete MCP workflows

Ask the client to run these tools in sequence. Preserve the project.id returned by creation and pass it as projectId to every later call.

Faceless Shorts sequence

1. list_voices, list_image_styles, list_upgrades

2. estimate_credits
   {"videoType":"faceless_shorts","project":{"prompt":"Explain Atlantis theories","duration":60,"narrator":"matt","imageTheme":"cinematic","movingFrames":"first"}}
   Show line_items and total_credits to the user. Continue only after a clear yes.

3. create_faceless_shorts
   {"name":"Atlantis","prompt":"Explain Atlantis theories","duration":60,"narrator":"matt","imageTheme":"cinematic","movingFrames":"first","max_credits":<credits_by_step.create_faceless_shorts>}

4. generate_faceless_shorts
   {"projectId":"<project.id>","max_credits":<credits_by_step.generate_faceless_shorts>}

5. get_faceless_shorts_generation_status
   {"projectId":"<project.id>"}
   Repeat every 10 seconds until state is "generated" or "failed".

6. render_faceless_shorts
   {"projectId":"<project.id>","emailWhenReady":true}

7. get_faceless_shorts_rendering_status
   {"projectId":"<project.id>"}
   Repeat every 10 seconds until state is "generated" or "failed", then share video.url.

Faceless Video sequence

1. list_voices, list_upgrades, list_avatars

2. estimate_credits
   {"videoType":"faceless_video",
    "project":{"prompt":"Explain the future of humanoid robots","duration":5,"narrator":"matt","voiceEngine":"natural"},
    "generate":{"aiImages":true,"imageStyle":"cinematic","cinematicIntro":"standard","movingImages":"first"}}
   Show line_items and total_credits to the user. Continue only after a clear yes.

3. create_faceless_video
   {"name":"Robotics","prompt":"Explain the future of humanoid robots","duration":5,"narrator":"matt","voiceEngine":"natural","max_credits":<credits_by_step.create_faceless_video>}

4. estimate_credits (optional, after edits)
   {"videoType":"faceless_video","projectId":"<project.id>","generate":{...same options}}

5. generate_faceless_video
   {"projectId":"<project.id>","aiImages":true,"imageStyle":"cinematic","addChapterTitles":true,
    "cinematicIntro":"standard","movingImages":"first","max_credits":<generate total>}

6. get_faceless_video_generation_status
   {"projectId":"<project.id>"}
   Repeat every 30 seconds until state is "generated" or "failed".

7. render_faceless_video
   {"projectId":"<project.id>","emailWhenReady":true}

8. get_faceless_video_rendering_status
   {"projectId":"<project.id>"}
   Repeat every 30 seconds until state is "generated" or "failed", then share video.url.

Example conversation

User: Make a 5 minute video about humanoid robots, natural voice, with a cinematic intro.

Assistant: (list_upgrades, estimate_credits)
  That comes to 45 credits: 5 for the script, 20 for the video, 5 for the Natural voice,
  5 for the cinematic intro and up to 10 for moving images (unused ones are refunded).
  Motion graphics and rendering are included. You'd have 195 of 240 credits left. Go ahead?

User: Yes.

Assistant: (create_faceless_video max_credits 5, generate_faceless_video max_credits 40)
  Charged 45 credits. The video is generating, about 12 minutes. I'll let you know.
  (get_faceless_video_generation_status ... render_faceless_video ... get_faceless_video_rendering_status)
  Here it is: https://... (5:01). Want the script as a file too? (get_script)

Result handling

On a generated render state, read video.url (also videoLink), the thumbnail, the duration and the script from structuredContent. Progress percentages are estimates from elapsed time; completion is only the generated state.

Ready to connect an MCP client?

Create an OAuth client or direct MCP key from your Vid.AI account.

Manage MCP credentials

Vid.AI MCP Reference

Connection options

Connect with OAuth

Discovery endpoints

Connect with an MCP key

Client configuration

Tool and response conventions

Video-generation workflow

Credits and confirmation

Get the full video workflow guide

Get authenticated user

Get credit balance

List projects

Get one project

Get or download the script

List narrators and custom voices

List voice engines

List AI image styles

List avatars

List the upgrades you can use

Estimate credits before charging

Add a custom voice

Remove a custom voice

Create a Faceless Shorts project

Edit Faceless Shorts sections

Start Faceless Shorts media generation

Get Faceless Shorts generation status

Start Faceless Shorts rendering

Get Faceless Shorts rendering status

Create a Faceless Video project

Edit Faceless Video sections

Start Faceless Video media generation

Get Faceless Video generation status

Start Faceless Video rendering

Get Faceless Video rendering status

Allowed values

Faceless Shorts durations

Faceless Shorts narrators

Faceless Shorts image themes

Faceless Video durations

Faceless Video narrators

Faceless Video image themes

Voice engines (long-form)

Upgrade values

Avatar placements

Project statuses

Errors

Complete MCP workflows

Prefer to make videos without code?