Veedio

MCP server · API key auth

Give your agent a video pipeline.

Claude, Cursor, ChatGPT and any other MCP client can write, render and publish a Veedio short through six tools. Same pipeline, same credits, same refund on failure as the app. Paste one URL and one header.

Connect the MCPGet the CLIOpen API docs
Works with
  • Claude
  • Claude Code
  • Cursor
  • ChatGPT
  • Windsurf
  • VS Code
  • Any MCP client

Six tools, not sixty

A tool list is a prompt: every entry costs the model context and a decision. Each one here is something an agent needs to finish a job — make it, watch it, price it, ship it, know what is left.

Quotes before spending

calculate_credits returns the price of a job and the balance without charging anything. An agent that finds out what something costs by spending it is the reason people distrust agents with a budget.

Readable failures

Out of credits, video not found and the rest come back as isError results with a sentence in them, not JSON-RPC errors — so the model can act on the problem instead of stalling on it.

Safe to retry

publish_video refuses a second post to a platform the video is already live on. An agent unsure whether its call landed can send it again without putting a duplicate on someone's account.

MCP, CLI, or API? Pick your interface

All three wrap the same generation pipeline. Choose by where your agent or your code runs.

Veedio MCP

Tool-calling agents: Claude, Cursor, ChatGPT, VS Code and anything built on an MCP SDK.

www.veedio.co/api/mcp

Veedio CLI

Terminal agents, CI jobs and cron. Stable --json output, --wait polling, meaningful exit codes.

install from packages/cli

Public API

Backend code that wants full control. Six endpoints, one of which makes videos.

POST /api/v1/videos

Quick connect

Connect your agent in under a minute

Every client connects the same way: the server URL plus an Authorization header with a key from Settings → API keys. There is no OAuth — a client that only offers a sign-in flow cannot connect yet.

Show the configuration for

Remote MCP server URL

https://www.veedio.co/api/mcp

Your API key

Create one in Settings → API keys. The plaintext is shown once and only its hash is stored. Requests made with it spend credits from your account, so keep it in an environment variable rather than a repository.

Create a key
Show the raw call for

Agent-readable reference

# Veedio MCP quick reference
endpoint: https://www.veedio.co/api/mcp
transport: Streamable HTTP, JSON-RPC 2.0 over POST, protocol 2025-03-26 (GET returns 405; no SSE stream)
auth: API key in Authorization: Bearer vd_live_... (also x-api-key, x-veedio-api-key, key). No OAuth.
primary flow: calculate_credits -> create_video -> get_video_status (until status = ready) -> publish_video
tools: create_video, get_video_status, list_videos, calculate_credits, publish_video, get_account
workflows: prompt-to-video, script-to-video, idea-to-video, article-to-video
credits: 3 base + 2 per still scene (13 with AI motion), deposited on create and settled when the scenes are written
agent-readable docs: https://www.veedio.co/llms.txt, https://www.veedio.co/faq-for-llms.md
limits: no file uploads (text and URLs only), no webhooks, no OAuth. Length 30/60/90/180s, free plan up to 60s. Narration in 29 languages from five voices
  • Four headers are accepted — Authorization: Bearer, x-api-key, x-veedio-api-key and key — so a config written for another vendor usually works with a one-line change.
  • A GET to the endpoint answers 405 with a JSON explanation rather than opening an SSE stream: this server only answers, it never pushes, so a stream would carry nothing.

Agent workflow

From prompt to published video

Four calls, in this order. Everything in between is the pipeline's problem, not the agent's.

1Price it

Call calculate_credits with the scene count you expect. It answers with the cost and the balance and charges nothing.

2Make it

Call create_video with a workflow and a source. It returns an id and the deposit immediately — the video does not exist yet.

3Watch it

Poll get_video_status every few seconds until status is ready. Scenes appear as they are produced, so there is something to report.

4Ship it

Call publish_video with the platforms. It refuses a platform the video is already live on, so a retry is safe.

The six tools

Names and descriptions are the ones the server answers tools/list with — this table is generated from them.

  • create_video

    Start generating a short-form video. Returns immediately with an id and the deposit charged; generation takes a few minutes. Poll get_video_status until it is 'ready'. Costs credits — call calculate_credits first if the user has not agreed to a price.

    • workflow*
    • source*
    • title
    • preset
    • voice
    • captionStyle
    • musicTrack
    • visualStyle
    • aspectRatio
    • mediaType
    • avatarId
    • soundEffects
    • photoUrl
    • quality
    • motionModel
    • language
    • targetSeconds

  • get_video_status

    The current status of a video, plus its scenes as they are produced and where it has been published. Status is one of queued, processing, ready, failed. `videoUrl` is the finished MP4 and is null until then. `publications` carries one row per platform the video was published to, each with the post's url once the platform has accepted it.

    • id*

  • list_videos

    The user's videos, newest first, with the status and the finished MP4 of each. Use it to find a video the user is referring to by name.

    • limit

  • calculate_credits

    What a generation would cost in credits, and what the balance is, without spending anything. A credit is a unit of pipeline cost: a fixed base plus a charge per scene that follows what fills the scene — a still or stock clip is cheap, AI motion is six times that and the premium video models more again. The quote is an upper bound (`upperBound`): clips are priced at the longest one the model will be asked for, and the final charge is settled against the script. Call this before create_video when the cost matters.

    • sceneCount
    • mediaType
    • quality
    • motionModel
    • soundEffects
    • targetSeconds

  • publish_video

    Publish a finished video to connected social accounts. The video must be 'ready' and the platform must already be connected in Settings; publishing costs no credits.

    • id*
    • platforms*
    • caption
    • force

  • get_account

    Who this API key belongs to, their plan, and their credit balance.

    No arguments.

* required argument

Supported workflows

The workflow argument of create_video. Each has its own page with the fields that apply to it.

Credits

A generation costs 3 credits plus a charge per scene that follows what fills it: 2 for a still or stock footage, 13 for a scene the video model sets in motion. A 5-scene short is 13 credits with stills and 68 animated.

Veedio CLI

Create videos from any terminal agent

For agents that run in a shell rather than a tool-calling loop, and for cron jobs that have no model in them at all.

Install

git clone https://github.com/milletgilmore/veedio.git
npm install -g ./veedio/packages/cli
export VEEDIO_API_KEY=vd_live_...
veedio --help

Agent commands

veedio create --prompt "why indie launches fail" --wait --json
veedio status 8f1c0f2e-... --json
veedio list --json
veedio estimate --scenes 6 --json
veedio publish 8f1c0f2e-... --platforms tiktok,youtube --json
Full CLI reference

Frequently asked questions

What is the Veedio MCP server?

A Streamable HTTP Model Context Protocol server at https://www.veedio.co/api/mcp that lets an AI agent create, poll, publish and price short-form videos through six tools. It wraps the same public API the web app uses, so a video an agent makes goes through the same pipeline, the same credit deposit and the same refund on failure as one made in the browser.

How do I connect Claude, Cursor or ChatGPT?

Add a custom HTTP MCP server pointing at https://www.veedio.co/api/mcp with an Authorization: Bearer header carrying an API key from Settings → API keys. Claude Desktop and Cursor take that as JSON in their config file, Claude Code takes it as a one-line claude mcp add command, and ChatGPT takes it as a custom connector.

Do I need an API key, or is there OAuth?

You always need an API key. There is no OAuth: a client that only offers a sign-in flow and cannot set a header cannot connect yet. We would rather say that plainly than have you find out inside a connector dialog.

How much does a video cost through the MCP?

The same as anywhere else: 3 credits plus 2 per scene with stills, so a five-scene short is 13 credits; a scene the video model sets in motion is 13. The deposit is charged when the job is queued and settled once the scenes are written; an abandoned generation is refunded in full. Call calculate_credits first — it is free, it returns the balance, and its quote is an upper bound.

Can an agent upload footage, images or audio?

Not as bytes: the API takes text and URLs, so there is no pushing a file up the wire and no captioning footage you already have or repurposing a podcast recording. Links do more than you might expect. photoUrl takes a hosted image and makes it the opening frame, and a url source pointing at a PDF is read as a document, so photo-to-video and PDF-to-video both work if the file is reachable — the web app's uploader exists to turn a local file into exactly that kind of link. Every other frame is generated.

Is there a webhook when a video is finished?

Not yet. Poll get_video_status every few seconds; generation takes a few minutes. A completion webhook is the next thing planned for this surface.

Can I use the API without the MCP?

Yes. The REST API at https://www.veedio.co/api/v1 is the same product with the JSON-RPC envelope taken off, and the CLI in packages/cli is a thin client over it for shells and cron jobs — install it from a clone until the npm package is published. Pick MCP for tool-calling agents, the CLI for terminals, REST for backend code.