Streamable HTTP · Protocol 2025-06-18

VidAI MCP Reference

Connect an MCP-compatible AI client to VidAI. You can view projects and create, edit, generate, and render Faceless Shorts and Faceless Videos.

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 VidAI 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 VidAI's OAuth metadata and opens browser sign-in.
4. Sign in to the VidAI account whose projects and credits the client should use.

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 5 seconds.
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

Create

Create a project and receive editable sections.

Edit

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

Generate

Start narration, captions, and visual media.

Poll media

Wait for a generated or failed state.

Render

Start the final video render.

Poll render

Wait for generated and read videoLink.

Polling interval

Poll the matching status tool every 5 seconds. Stop on generated or failed. Status tools are read-only and never start work.

Core tools

TOOLget_user

Get authenticated user

Return the VidAI 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_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
  }
}

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. Required when prompt is omitted.
duration	60 \| 90	Yes	Requested duration in seconds.
narrator	enum	Yes	Narrator key from Allowed values.
imageTheme	enum	Yes	Image theme from Allowed values.

Access and credits

An active paid subscription and at least 5 credits are required. Successful content generation consumes 5 credits.

Tool arguments

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

Structured result

{
  "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 10,000 characters.
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.

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.

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

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.

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. No percentage is returned.
generated	GENERATED	Rendering completed and videoLink is available.
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"
}

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	Yes	Faceless Video narrator key from Allowed values.

Access and credits

A PRO subscription is required. The account must have 5 credits per requested minute. Creation deducts the first 5 credits; media generation handles the remaining duration credits.

Tool arguments

{
  "name": "The future of robotics",
  "prompt": "Explain how humanoid robots may change daily life",
  "duration": 5,
  "narrator": "matt"
}

Structured result

{
  "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, optional AI images, and optional chapter-title scenes for a Faceless Video project.

Name	Type	Required	Description
projectId	string	Yes	Faceless Video project containing editable sections.
imageTheme	enum \| null	No	AI image theme. Omit or use null for stock footage only.
addChapterTitles	boolean	No	Generate chapter-title scenes. Defaults to false.
retry	boolean	No	Defaults to false. Set true only after a failed generation.

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",
  "imageTheme": "cinematic",
  "addChapterTitles": true,
  "retry": false
}

Structured result

{
  "projectId": "cmu_video_project_id",
  "state": "generation_started",
  "status": "MEDIA_GENERATING",
  "message": "Media generation started. Check again later."
}

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

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.

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. No percentage is returned.
generated	GENERATED	Rendering completed and videoLink is available.
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"
}

Reference

Allowed values

Faceless Shorts durations

60, 90 seconds

Faceless Shorts narrators

mattadamstonerachelmatildapriyam-v2adamkaylatimmyandyivanthemightymichaelmouserudraallisonrusselljessicalilyWolffsantaClausbillrichardYuryanfredericksurreydariansawyereddiealiciajadelawrencecalebtaliawarrenkaelenflorencewyatt

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

Faceless Video image themes

Omit imageTheme or use null to generate with stock footage only.

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

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	The account plan or credit balance does not allow the operation.
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. create_faceless_shorts
   {"name":"Atlantis","prompt":"Explain Atlantis theories","duration":60,"narrator":"matt","imageTheme":"cinematic"}

2. generate_faceless_shorts
   {"projectId":"<project.id>"}

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

4. render_faceless_shorts
   {"projectId":"<project.id>"}

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

Faceless Video sequence

1. create_faceless_video
   {"name":"Robotics","prompt":"Explain the future of humanoid robots","duration":5,"narrator":"matt"}

2. generate_faceless_video
   {"projectId":"<project.id>","imageTheme":"cinematic","addChapterTitles":true}

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

4. render_faceless_video
   {"projectId":"<project.id>"}

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

Result handling

On a generated render state, read videoLink from structuredContent. Do not ask the client to infer completion from elapsed time.

Ready to connect an MCP client?

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

Manage MCP credentials