Vivideo

io.github.egocen-vivideoPublished by GitHub account egocen-vivideov1.0.2Updated Oct 27, 2026

AI video generation via the Vivideo API: auto or manual mode, avatars, voices, brand kits.

VerifiedStreamable HTTPWeb executableMedia & DesignAI & ML

Overview

AI-generated overview

Vivideo lets an assistant generate AI-avatar videos through the Vivideo API, in auto or manual mode, with avatars, voices and brand kits.

What you can do
  • Check configuration and account plan, premium status and remaining credits
  • List video models with their durations, resolutions, aspect ratios and per-second credit rates
  • List avatars, voices and brand kits to use in auto-mode videos
  • Estimate credit cost before generating, then create auto-mode or manual-mode videos
  • Poll, wait for and list videos, and render a preview once a free account upgrades
When to use it
Useful when you want an assistant to draft and render short AI-avatar or model-based videos from a prompt, check whether the account can afford a render, or track existing video jobs without leaving the chat.
Requirements
Either the remote endpoint at api.vivideo.ai with an Authorization bearer header, or the local npm package @vivideo/mcp run over stdio with Node 18.17 or later. A Vivideo API key (vv_live_...) is required, supplied as VIVIDEO_API_KEY or the Authorization header. Rendering needs a premium plan and enough credits.
Before you install
The API key is an account-scoped secret that can spend credits; keep it server-side and revocable. Creating videos charges credits (free accounts get previews until they upgrade), and there is no cancel endpoint, though failed renders are refunded. Prompts and image URLs are sent to Vivideo's API.

Installation

In SourceWeft

  1. Open Vivideo in the dashboard and add it to a workspace.
  2. Connect Authorization token credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.egocen-vivideo%2Fvivideo/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "vivideo": {
      "type": "http",
      "url": "https://api.vivideo.ai/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

README

Vivideo Toolchain

The developer + agent integration layer for the Vivideo API — a shared client, an MCP server, a CLI, and Skills. Agents are a primary user, not an afterthought.

Everything sits on top of the public API (the source of truth). No backend business logic is duplicated here — the toolchain only adds client-side ergonomics and guardrails.

vivideo-toolchain/            npm workspaces monorepo (TypeScript)├── packages/core   @vivideo/core   one typed API client + guardrails (shared)├── packages/mcp    @vivideo/mcp    MCP server (stdio) — 13 agent tools├── packages/cli    @vivideo/cli    `vivideo` CLI — humans, scripts, CI, agents├── skills/                          reusable agent Skills (SKILL.md)└── docs/                            installation, configuration, workflows

Architecture

One client, one set of types, derived from packages/core/openapi.yaml. The MCP server and CLI both call @vivideo/core — there is exactly one representation of each request/response, so the tools, CLI, docs and OpenAPI stay consistent.

@vivideo/core adds only client-side concerns, never business logic:

GuardrailWhat it does
Rate limitingToken-bucket cap on request rate (default 8/s) — the client can't become a request flood.
Concurrency capSemaphore limits in-flight requests (default 4).
Bounded retriesRetries only retryable failures, with full-jitter backoff, capped attempts.
Honors Retry-AfterOn 429 it waits the API-specified delay before retrying.
IdempotencyEvery video-create sends an Idempotency-Key; retries reuse it → no duplicate charges.
TimeoutsPer-request AbortController timeout (default 30s).
Safe waitingwaitForVideo polls at the API's suggested interval, with a hard timeout — never a while(true).
Secret redactionAPI keys / signing secrets are stripped from every log, error, and output.

These complement — and never bypass — the API's own auth, rate limits, idempotency, credit checks, premium gates, ownership and error model.

Quick start

bash
# from the repo (until packages are published to npm)npm installnpm run build
# authenticate (stored 0600 in ~/.vivideo/config.json), or use VIVIDEO_API_KEYexport VIVIDEO_API_KEY="vv_live_..."   # from https://app.vivideo.ai/account/api-keys
# CLInode packages/cli/dist/index.js accountnode packages/cli/dist/index.js create auto --prompt "A 20s product teaser" --wait
# MCP server (stdio) — point an MCP client at this commandnode packages/mcp/dist/index.js

Once published: npm i -g @vivideo/cli (gives vivideo), and npx @vivideo/mcp for the server.

Docs

Authentication & security

  • Keys are read from (in order): explicit option → VIVIDEO_API_KEY env → ~/.vivideo/config.json (written owner-only 0600).
  • The key is never printed — all output passes through secret redaction; configure stores it without echoing it.
  • Keys are account-scoped secrets. Keep them server-side; one per integration so a leak is revocable in isolation.

Not included (honest scope)

  • Cancellation — the public API has no cancel endpoint, so no cancel tool/command is offered. Failed/stuck renders are auto-refunded by the API.
  • Agent/chat mode — not exposed by the public API, so not in the toolchain.
  • Nothing here publishes to npm, provisions DNS, or deploys — those are external steps (see the final section of docs/mcp.md).

Development

bash
npm run build       # build all three packages (tsc -b)npm run typecheck   # type-check the whole workspacenpm test            # vitest

Requires Node ≥ 18.17.

Source: README.md at commit f0b911e

Tools

13

check_configuration

Check whether a Vivideo API key is present on this request. Call this FIRST. Returns { configured: boolean }. If false, ask the user to add an Authorization: Bearer vv_live_... header to the MCP server config (a key from https://app.vivideo.ai/account/api-keys). Never asks for or exposes the key.

Takes no parameters.

check_account

Get the account plan, premium status, and remaining credit balance. Use this to decide whether the user can generate a video (rendering needs a premium plan and enough credits). Returns plan, premium, credits, free_video_available, and links (upgrade / buy_credits). Cheap and safe to call often.

Takes no parameters.

list_models

List the video models available for MANUAL mode plus the auto-generate pipeline (id "vivideo-auto"). Each model lists its operations, allowed durations, resolutions, aspect ratios, style presets and per-second credit rate — use these to build a valid create request. Filter with `mode` to keep the response small.

Parametersmode

list_avatars

List available avatars for auto-mode videos (the stock catalogue plus the account's own avatars). Stock avatars are grouped by person, each with a `looks` array — pass a looks[].avatar_id (or an owned avatar's id) as `avatar_id` in create_auto_video. Use `search`/`limit` to keep responses small.

Parameterslimitgendersearch

list_voices

List available voices for auto-mode videos. Returns voice ids to pass as `voice_id` in create_auto_video. Filter by language/gender/search and cap with `limit`. Voice cloning is not available via the API.

Parameterslimitgendersearchlanguage

list_brand_kits

List the account's brand kits (logo, colors, fonts, motion style). Returns brand_ref ids to pass as `brand_kit_id` in create_auto_video to produce an on-brand video.

Takes no parameters.

estimate_credits

Estimate the credits a generation will cost, from the published per-model rates — BEFORE creating it. This is an estimate, not a charge; the exact amount is returned as credits_charged when you create the video. Use it with check_account to confirm the user can afford the request.

Parametersmoderequiredmodelresolutionduration_seconds

create_auto_video

Create a video in AUTO mode: Vivideo writes the script and produces a complete AI-avatar video from your prompt. Returns immediately with a video id and status "processing" (paid) or "preview" (free accounts — see the preview field and upgrade link). Then call wait_for_video or get_video. An Idempotency-Key is sent automatically so a retry never creates a duplicate. Rendering requires a premium plan and credits.

Parametersnamepromptrequiredvoice_idavatar_idfolder_idorientationbrand_kit_ididempotency_keyduration_seconds

create_manual_video

Create a video in MANUAL mode: send your prompt straight to a specific model (get ids/options from list_models). The operation is inferred from inputs — add image_url for image-to-video. resolution/duration/aspect_ratio must match the model (an invalid value returns a 400 listing what is allowed). Returns a video id and status; then wait_for_video or get_video. Idempotency handled automatically.

Parametersnameseedmodelrequiredstylepromptrequiredfolder_idimage_urlresolutionaspect_ratiogenerate_audioidempotency_keynegative_prompt+1 more

get_video

Get a video's current status and result. status is one of queued | processing | completed | failed | preview. When completed, video_url is the MP4. When failed, credits are refunded and error explains why. Cheap; prefer wait_for_video for polling instead of calling this in a tight loop.

Parametersidrequired

wait_for_video

Wait for a video to reach a terminal state (completed / failed / preview), then return it. Polls safely at the API-suggested interval for up to ~20 seconds per call (HTTP requests are time-capped). If it does not finish in time it returns { timed_out: true } with the latest status — simply call it again with the same id to keep waiting. It never blocks indefinitely or over-polls.

Parametersidrequiredtimeout_seconds

list_videos

List the account's videos, newest first. Filter by status and limit the count to keep responses small.

Parameterslimitstatus

render_preview

For FREE accounts only: after the user upgrades, render a video that was returned as status "preview". Charges run on the same project (the first video after upgrading is free). If the video is already rendering/complete, returns its current state. If the account is still free, returns an upgrade_required error with an upgrade link.

Parametersidrequired

Version history

1
  1. v1.0.2LatestSep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts