Vidvibe

---
name: vidvibe
description: >-
  Produce video with AI from the terminal via the VidVibe MCP server — price and launch
  flows, generate videos and images, create and lip-sync characters, edit a flow canvas,
  manage brands and styles, upload assets, and publish finished cuts to YouTube and TikTok.
  Use when: connecting an agent to vidvibe.io, generating short-form or marketing video,
  batch-producing branded clips, driving a video pipeline that keeps running server-side,
  publishing to a connected channel, or when the user mentions "VidVibe", "flow run",
  "character", "Joiner", or spending "credits" on video.
license: Apache-2.0
compatibility: "Any MCP client (Claude Code, Claude Desktop, Codex, Gemini CLI, Cursor); vidvibe.io account — generation tools spend credits"
metadata:
  author: terminal-skills
  version: "1.0.0"
  category: content
  tags: [video-generation, mcp, ai-video, youtube, characters]
evals:
  - name: price-before-launch
    prompt: |
      I'm connected to the VidVibe MCP server. Make me a 30-second product teaser
      for my brand from this script, using one of the ready-made flows.
    rubric: |
      Score 0-100 by points achieved:
      - Calls list_flows (or list_my_flows) and get_flow to read the flow's input schema: 20pts
      - Calls get_flow_price with the intended inputs and states price_cr vs balance_cr to the user BEFORE launching: 30pts
      - Passes brand_id from list_brands (or explains that omitting it keeps the last-used brand): 15pts
      - Launches with launch_flow, then polls get_flow_run at the returned poll.interval_seconds instead of a tight loop: 25pts
      - Returns the review_url / app_url link, not just raw JSON: 10pts
  - name: generation-two-step
    prompt: |
      Generate a 16:9 hero image for the landing page and put it in my VidVibe library.
    rubric: |
      Score 0-100 by points achieved:
      - Calls generate_image with aspect_ratio "16:9" and captures the returned flow_run_id: 30pts
      - Polls get_flow_run with that flow_run_id until status = "completed": 30pts
      - Calls save_image with the SAME flow_run_id to mint the library entry (does not assume generation alone saves it): 30pts
      - Surfaces the returned app_url / share link so the user can open the result: 10pts
  - name: insufficient-credits-handling
    prompt: |
      Run my "weekly product shorts" flow for all 12 products in this CSV.
    rubric: |
      Score 0-100 by points achieved:
      - Checks get_credit_balance and get_flow_price for one run, then multiplies out the batch cost before starting: 30pts
      - On an {"error": "insufficient_credits"} result, relays needed_cr, balance_cr and topup_url: 30pts
      - Stops the batch instead of retrying the same refused launch in a loop: 25pts
      - Reports which runs did launch (run_ids) so nothing paid for is lost: 15pts
---

# VidVibe — AI Video Production via MCP

## Overview

VidVibe (vidvibe.io) is an AI video-creation platform: brands, flows (node graphs that
end in a Joiner that cuts clips together), characters (AI presenters that lip-sync a
script), and one-form studios for video and image generation.

Its remote MCP server exposes the product as **100 tools** — the same services the app's
buttons call — so an agent can run a whole production without a browser: price a flow,
launch it, follow the run, fetch the cut, and publish it to YouTube or TikTok.

Endpoint: `POST https://api.vidvibe.io/mcp` (streamable HTTP, stateless, tools only —
no resources or prompts). **Every call runs as the token's VidVibe account**, spends its
credits, and writes rows the web app then shows.

## Instructions

### Setup

Sign up at https://app.vidvibe.io, then **Settings → API** (`/api-keys`) → **Create
Token** → pick scopes. The token (`vv_` + 64 hex) is shown **once**.

```bash
npx terminal-skills install vidvibe
claude mcp add --transport http vidvibe https://api.vidvibe.io/mcp \
  --header "Authorization: Bearer $VIDVIBE_TOKEN"
```

Claude Desktop / Codex / Gemini CLI / Cursor: register an HTTP MCP server with the same
URL and header. Clients that reserve `Authorization` for their own OAuth (claude.ai
custom connectors) may send `x-api-key: vv_…` instead — the server accepts either, and
`Authorization` wins if both are present. The server does **not** implement OAuth, so set
authentication to *None* and add the header manually.

Verify with `tools/list` — the response contains only the tools the token's scopes allow.

### Scopes

Tokens carry `resource:operation` scopes: `characters`, `flows` (read · **execute**),
`flow_runs`, `brands`, `styles`, `projects`, `videos`, `images`, `assets`, `uploads`,
`publishing` (read · **execute**), `channels`, `favorites`, `trash`, `billing`,
`showcase`, `blog`. A call outside them fails with *API key lacks permission for tool*.
The `blog_*` tools additionally need `role = admin` — scope alone is not enough. Tokens
cannot create tokens, change plans, manage the team, or edit system templates.

### Credits — read before running anything paid

- VidVibe bills in **credits (CR)**. Generation is priced by model and length; processing
  steps are a small flat amount; reads are free. New accounts get a 14-day trial with
  100 CR.
- Paid work is **prepaid at launch and refunded if the run fails**, so a failure never
  silently costs money. `cancel_flow_run` refunds the prepaid charge.
- A refused charge is a **JSON result, not an error**:
  `{"error": "insufficient_credits", "needed_cr", "balance_cr", "topup_url"}` or
  `{"error": "subscription_expired", "reason", "balance_cr", "topup_url"}`. A lapsed trial
  or expired subscription cannot spend whatever the balance says.
- `get_flow_price(flow_id, inputs)` returns `price_cr`, `balance_cr`, `enough` and charges
  nothing. **Call it and state the price before every paid tool.** `get_credit_balance`
  and `get_billing_info` are the account-level reads.

### Tool map

💳 = spends credits.

| Domain | Tools |
|---|---|
| Flows | `list_flows`, `list_my_flows`, `get_flow`, `get_flow_step`, `get_flow_price`, `launch_flow`💳, `regenerate_flow_run`💳, `run_flow`💳, `run_flow_and_wait`💳, `run_flow_step`💳, `export_flow`, `import_flow` |
| Runs | `list_flow_runs`, `get_flow_run`, `list_flow_run_steps`, `change_flow_run_step`💳, `approve_flow_run`, `reject_flow_run`, `retry_flow_node`, `continue_flow_run_yolo`, `cancel_flow_run`, `get_flow_run_video_url`, `view_flow_run_video`, `view_flow_step_output` |
| Canvas editing | `add_canvas_step`, `connect_steps`, `disconnect_steps`, `update_step_settings`, `add_motion_layer`, `edit_motion_layer`, `move_motion_layer`, `remove_motion_layer` |
| Projects (template pipelines) | `get_project_status`, `get_project_video_url`, `get_project_video`, `list_projects` |
| Videos | `list_videos`, `get_video`, `generate_video`💳, `save_video`, `view_video`, `rename_video`, `get_video_url`, `delete_video` |
| Images | `list_images`, `get_image`, `generate_image`💳, `save_image`, `view_image`, `get_image_url`, `delete_image` |
| Characters | `list_characters`, `get_character`, `get_character_versions`, `get_character_image`, `get_character_image_url`, `create_character`💳, `create_character_and_wait`💳, `edit_character`💳, `edit_character_and_wait`💳, `upload_character`💳, `set_active_character`, `rename_character`, `delete_character` |
| Brands & styles | `list_brands`, `get_brand`, `create_brand`, `create_brand_from_url`💳, `update_brand`, `delete_brand`, `list_styles` |
| Uploads & library | `upload_video`, `upload_image`, `create_upload`, `finalize_upload`, `list_assets`, `view_asset`, `list_showcase`, `list_favorites`, `toggle_favorite`, `list_trash`, `restore_from_trash`, `permanent_delete` |
| Publishing | `list_channels`, `list_publishable`, `publish_video_to_youtube`, `publish_video_to_tiktok`, `get_publish_status`, `list_publish_history` |
| Account | `get_credit_balance`, `get_billing_info` |
| Blog `[admin]` | `list_blog_categories`, `create_blog_category`, `update_blog_category`, `delete_blog_category`, `list_blog_posts`, `get_blog_post`, `create_blog_post`, `update_blog_post`, `delete_blog_post` |

### Polling — never block, never busy-loop

Every tool that starts async work returns
`poll: { tool, args, interval_seconds, note }`. Honour that interval: **10 s** for a flow
run, **5 s** for one step or a character, **15 s** for a pipeline project or a publish job.
`get_flow_run` returns `poll_again_in_seconds` while it is going and `null` when it is
finished *or* waiting on the user (`waiting_on_user: true` → `approve_flow_run` /
`reject_flow_run` / `retry_flow_node`). The `*_and_wait` variants check every 10 s and
return a snapshot after 10 minutes — **the work keeps going** either way. A paid run is
detached from the MCP request: disconnecting never stops it, and the result lands in the
account.

### Core workflows

**Run a ready-made flow** — `list_flows` → `get_flow` for the input schema →
`get_flow_price` → `launch_flow(flow_id, inputs, brand_id)` → poll `get_flow_run` →
`get_flow_run_video_url` for a signed mp4 (24 h). Pass `approval_mode: true` to pause at
review gates. Not happy with one step? `list_flow_run_steps` prices a re-run from each,
`change_flow_run_step` re-runs from there with feedback as a new run.

**Generate a single clip or image** — `generate_video` / `generate_image` return a
`flow_run_id`; poll `get_flow_run` on it, then call `save_video` / `save_image` **with the
same id** to mint the library entry. Generation alone does not save it. `generate_video`
takes `prompt`, `model` (default `veo-3.1`), `aspect_ratio` (`9:16` default), `duration`
(1–60 s, default 5), `reference_url`, `brand_id`, `style_id`.

**Brand and style on every generation** — `brand_id` is tri-state on `generate_image`,
`generate_video`, `create_character` and `run_flow_step`: **omit** = keep the user's
last-used brand, `null` = explicitly none, an id from `list_brands` = that brand.
(`launch_flow` differs: omitting it means *no* brand.) `style_id` comes from
`list_styles`; omit for none — an unknown or foreign id is a 404, never a silent fallback.

**Build a canvas** — `add_canvas_step(flow_id, kind, prompt, settings)` places an image /
video / text / audio card **without running it**, `connect_steps` wires a result into
another card's parameter (`"input"` on the Joiner puts a clip in the cut; `"audio"`,
`"subtitles"` are its other slots), `update_step_settings` patches `styleId` / `brandId`
(`"none"` = unbranded), and `run_flow_step` generates one card (charged, 1 CR floor).
System templates are read-only — fork one in the app first. `export_flow` → edit →
`import_flow` round-trips a flow as `.flow.json`.

**Publish** — `list_channels` for the connected account id, `list_publishable` for what
can go out, then `publish_video_to_youtube(video_id, title, description, privacy,
youtube_account_id)` or `publish_video_to_tiktok`, and poll `get_publish_status`.

## Examples

### Example 1: Priced, polled, published

> "Turn this week's changelog into a 30-second vertical short for our YouTube channel."

```text
1. get_credit_balance                       → 240 CR
2. list_flows → get_flow("shorts-explainer") → inputs: topic, script, duration
3. get_flow_price(flow_id, inputs)          → { price_cr: 30, balance_cr: 240, enough: true }
   → tell the user "this run costs 30 CR of your 240" and wait for a yes
4. list_brands → brand_id
5. launch_flow(flow_id, inputs, brand_id)   → { run_id, review_url, charged_credits: 30,
                                                poll: { tool: "get_flow_run", interval_seconds: 10 } }
6. get_flow_run(run_id) every 10 s          → status "running" … → "completed"
7. get_flow_run_video_url(run_id)           → signed .mp4 (24 h)  +  review_url for the app
8. list_channels → publish_video_to_youtube(video_id, title, privacy: "unlisted", youtube_account_id)
9. get_publish_status every 15 s            → "published"
```

### Example 2: The batch stops instead of looping

```text
> get_flow_price(flow_id, inputs)  → { price_cr: 30, balance_cr: 45 }
  12 products × 30 CR = 360 CR against a 45 CR balance — say so before launching anything.

> launch_flow(...)  # product 2
{ "error": "insufficient_credits", "needed_cr": 30, "balance_cr": 15,
  "topup_url": "https://app.vidvibe.io/billing" }
```

Correct behaviour: relay the numbers and the link, **stop the batch** (a retry just fails
again), and report what did launch — `run_id` for product 1 is real work already paid for
and still running server-side. Free reads still answer the rest: `list_flow_runs`,
`list_videos`, `get_credit_balance`.

## Guidelines

- **Money is real.** Never launch a paid tool the user did not ask for. `get_flow_price`
  first, state `price_cr` vs `balance_cr`, multiply out batches, and get a yes. Prefer one
  `launch_flow` over re-running steps one at a time.
- **Generation is two calls.** `generate_video` / `generate_image` start work; the library
  entry only exists after `save_video` / `save_image` with the same `flow_run_id`.
  Reporting "done" before saving loses the result.
- **Publishing is public.** `publish_video_to_youtube` / `publish_video_to_tiktok` push to
  a live channel. Quote the title, description and privacy, get approval, and prefer
  `privacy: "unlisted"` for a first pass.
- **Respect the poll hint.** Polling faster than `interval_seconds` gains nothing and
  risks rate limits; the work is detached from the connection, so waiting is safe. If a
  run reports `waiting_on_user: true`, ask the user — do not auto-`approve_flow_run`, and
  treat `continue_flow_run_yolo` (skip all remaining gates) as needing an explicit yes.
- **Deletes are real deletes.** `delete_video`, `delete_image`, `delete_character`,
  `delete_brand` and `permanent_delete` remove the user's work; `permanent_delete` empties
  trash beyond recovery. Name exactly what goes and confirm first.
- **Show links, not blobs.** Signed media URLs expire in ~24 h; every image/character
  result also carries a permanent `app_url` (`/share/image/:id`, `/share/avatar/:id`,
  `/share/video/:id`) — give that. Images come back as inline MCP `image` blocks; video
  cannot be played in chat, so video tools attach a **poster frame** and say so in
  `inline_preview`. A client cannot open a URL on its own — link it for the user.
- **Read the error instead of retrying.** `insufficient_credits` / `subscription_expired`
  carry the price, the balance and the top-up URL. "API key lacks permission" means a
  missing scope (or a non-admin token on a `blog_*` tool), not a bad request.
- **IDs are UUIDs scoped to the token's account** — a 404 on a valid-looking id usually
  means it belongs to another account.
- The token acts as the user: its runs, uploads and publishes appear in their library and
  spend their credits. Never commit it, scrub it from logs, and treat a 401 as revoked —
  ask them to reissue in Settings → API.