What can I build with the vlogme.ai API?

Anything that needs programmatic talking-avatar video generation: personalised sales videos, AI tutors, news anchors, product explainers, NPC dialogue, localized voice-overs at scale. One POST request takes a portrait URL + script + voice ID and returns a finished MP4.

How does the MCP server work with Claude Code, Codex, and Cursor?

Vlogme exposes a Streamable-HTTP MCP endpoint at /api/mcp. Add it once with the CLI snippet on this page and your agent can call list_voices, generate_video, and get_video natively — no glue code, no extra SDK.

How are credits billed for API renders?

The V2 render estimate is reserved when you POST /api/v2/renders, settled at completion, and released automatically after a terminal failure or cancellation.

Is there a rate limit?

API requests use a per-user rate limit. Read the X-RateLimit headers on successful responses and honor Retry-After after a 429.

How do webhooks work — signatures and delivery?

Every webhook includes X-Vlogme-Signature — verify it as a sha256 HMAC of the raw body using sha256(raw API token) as the secret. Delivery is best-effort and attempted once: if your endpoint is unreachable the event is dropped and not retried, so always also poll GET /videos/:id until status is completed or failed.

Who can use API and MCP access?

Every authenticated token owner can use API and MCP. Generation uses the same credit wallet, estimates, reservations, scopes and rate limits as the web app.

AI Video Generation API & MCP | VlogMe Developers

1313 sections — tap to jump

01What you can build
02Run VlogMe Avatar on Replicate
03Authentication
04Quickstart
05REST endpoints
06Create an AI video
07Script grammar
08Webhooks
09MCP server
10Client setup
11End-to-end agent example
12Agent skill
13Errors and retries

Intro

What you can build

Programmatically create video projects and talking-avatar clips with the same account, credits and job history as the web app.

Use REST from a backend, automation or product integration. Use MCP when an AI agent should inspect tools, estimate cost and submit a render itself.

The public v1 surface is asynchronous: submit a job, keep its id, then poll or receive a signed webhook. Generation requires enough credits for the exact reservation.

Estimate before spending credits.
Generate a portrait-based video from text and a voice, or from uploaded audio.
Read progress and receive a temporary signed download URL.
Use idempotency keys to make paid retries safe.

Hosted

Run VlogMe Avatar on Replicate

For a simple image-plus-audio endpoint, the public VlogMe Avatar bridge is also available as a hosted Replicate model.

Use this route when Replicate already handles your infrastructure and billing. The direct VlogMe API remains the complete integration surface for credits, job history, REST and MCP.

The hosted bridge returns a vertical talking-avatar MP4 and keeps subtitles enabled by default.

Run Avatar on Replicate GitHub examples

Setup

Authentication

Send a Bearer token with every protected request. A token is displayed only once, so store it in a secret manager.

Create the token in Settings → API and never expose it in browser code, mobile bundles, public repositories or client logs.

The REST base URL is https://vlogme.ai/api/v2. Rotate a token if it may have leaked.

http

Authorization: Bearer vlm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

url

https://vlogme.ai/api/v2

Start

Quickstart

Create a token, estimate the request, submit a render and poll until the status becomes terminal.

The example sends a portrait URL, script, voice id and aspect ratio. Replace all placeholders with assets your server can fetch.

A successful POST returns 202 Accepted immediately. Keep polling roughly every ten seconds, or pass a webhook_url.

bash

curl -X POST https://vlogme.ai/api/v2/renders \
  -H "Authorization: Bearer $VLOGME_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "PROJECT_UUID",
    "revision_id": "REVISION_UUID",
    "preset": "balanced",
    "idempotency_key": "video-request-001"
  }'

REST

REST endpoints

A compact JSON API with OpenAPI 3.1, stable error codes and rate-limit headers.

The machine-readable specification is available at /api/v2/openapi.json. Generate a typed client or import it into Postman or Insomnia.

Every response carries X-Request-Id. Async POST /videos also returns Location with the polling URL.

GET/projectsUser id, plan and credit balance

POST/projectsVoice IDs available for synthesis

GET/projects/:idStart an asynchronous render

PATCH/projects/:idRead status and signed download URL

POST/rendersList recent renders with pagination

GET/jobs/:idEstimate credits without charging

POST/jobs/:id/cancelDelete or cancel an eligible render

POST/projects/:id/director-proposalsLiveness probe; authentication not required

bash

curl https://vlogme.ai/api/v2/jobs/$JOB_ID \
  -H "Authorization: Bearer $VLOGME_TOKEN"

REST

Create an AI video

Provide a portrait and either script plus voice_id or an audio asset. Rendering continues asynchronously.

Use portrait_url or portrait_base64. For speech, send script with voice_id, or audio_url/audio_base64. Optional fields include aspect_ratio, emotion_preset, live_subtitles, title and webhook_url.

Every paid POST requires a unique Idempotency-Key. Retrying with the same key returns the original render instead of charging twice.

Supported aspect ratios: 9:16 by default, 16:9 and 1:1.
Top-level inserts can add overlay or cut b-roll.
audio_mode can use auto, prompt, asset or off for project background audio.
The 202 response includes id, status, credits_charged, estimated_seconds and warnings.

bash

curl -X POST https://vlogme.ai/api/v2/renders \
  -H "Authorization: Bearer $VLOGME_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "PROJECT_UUID",
    "revision_id": "REVISION_UUID",
    "preset": "balanced",
    "idempotency_key": "video-request-001"
  }'

Scripts

Script grammar

The machine-readable DSL describes scene switches, b-roll, audio inserts, pauses and inline voice-performance tags.

Use @imageN to switch the speaking scene, curly-brace inserts for overlay or chain b-roll, @audioN for audio assets and ElevenLabs performance tags such as [shocked].

The downloadable specification is intentionally language-neutral for tools and LLMs. MCP clients can read the same contract with script_grammar_help.

Download .md Open raw specification

SCRIPT-GRAMMAR.md

# V2 script grammar compatibility

This document describes the supported V2 plain-text import grammar. Current
Create authoring uses typed `CreateSnapshot` revisions and does not serialize
its editor state through this grammar.

The V2 bridge `flatToPayloads()` converts the grammar into `ScenePayload[]`.
Provider-specific payloads are derived later by render and integration
infrastructure; the browser never constructs them.

## Forms

| Form                   | Meaning                                    |
| ---------------------- | ------------------------------------------ |
| `@imageN <text>`       | Avatar speech anchored to image N          |
| `@imageN { <prompt> }` | Standalone generated video from image N    |
| `{ @imageN <prompt> }` | Overlay on the current avatar              |
| `{ <prompt> }`         | Continue from the preceding rendered frame |
| `@audioN`              | Uploaded audio on the current avatar       |

Plain text following an avatar line continues that avatar's speech. Video,
overlay and Continue forms may add `:D` after the closing brace to request a
duration. Advanced brace segments support `v:`, `n:`, `s:`, `an:`,
`am:auto|prompt|asset|off`, `ag:` and transition `tK`.

Whitespace and indentation do not change token meaning. Tags must begin a line
or appear at the start of a brace body; nested braces and inline image tags in
speech are invalid. Provider-specific prompt and duration limits are validated
before submission.

Legacy bare image lines remain parser-compatible for existing V2 projects, but
new generated V2 scripts should use the explicit forms above.

## Create boundary

Create visual blocks carry their own typed `visual_kind`, entry source,
timeline placement and media plan. In particular, Create Continue is an
independent visual block with `entry.mode = previous_exit`, an explicit
predecessor and the predecessor's accepted terminal-frame fingerprint. It is
not derived from the V2 brace syntax.

REST

Webhooks

Pass webhook_url and VlogMe sends one completion or failure event, with retries when delivery is transiently unavailable.

Verify X-Vlogme-Signature against timestamp + raw_body using the dedicated whsec_ signing secret from Settings → API. Reject timestamps older than five minutes and deduplicate on X-Vlogme-Event-Id.

Return any 2xx within five seconds. Network errors and 5xx responses are retried with backoff; 4xx is treated as a permanent rejection. A delayed event may contain an expired URL, so GET the video again for a fresh signed link.

python

ts = request.headers["X-Vlogme-Timestamp"]
secret = "whsec_..."  # Settings -> API
expected = "sha256=" + hmac_sha256(secret, ts + "." + raw_body).hex()
assert constant_time_eq(expected, request.headers["X-Vlogme-Signature"])
assert abs(now() - int(ts)) < 300

MCP

MCP server

Connect an AI agent through native Streamable HTTP using a VlogMe token or interactive OAuth.

The MCP tools wrap REST v1 and share its data shapes, credit formula and stable error codes. Changes are additive: clients should ignore unknown fields.

Generation tools cover voices, balance, estimates, portraits, job submission, status, cancellation and history. Authorized internal accounts may also use the work-item tools.

endpoint

POST  https://mcp.vlogme.ai/api/mcp

script_grammar_helplist_voicesget_balanceestimate_creditslist_portraitsgenerate_videoget_videocancel_videolist_my_videoslist_bugsget_bugreport_bugupdate_bug_status

MCP

Client setup

Claude Code, Cursor and Codex support Streamable HTTP. Older stdio-only clients can use mcp-remote.

Choose exactly one authentication mode: interactive OAuth or an API token environment variable. Do not combine them.

After changing an MCP configuration, start a new client session so it discovers the tools again.

bash

# OAuth
codex mcp add vlogme --url https://mcp.vlogme.ai/api/mcp
codex mcp login vlogme --scopes mcp:full,mcp:work_items

# or API token
export VLOGME_TOKEN=vlm_live_xxxxxxxxxxxx
codex mcp add vlogme --url https://mcp.vlogme.ai/api/mcp --bearer-token-env-var VLOGME_TOKEN

json

{
  "mcpServers": {
    "vlogme": {
      "url": "https://mcp.vlogme.ai/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN_HERE" }
    }
  }
}

MCP

End-to-end agent example

A natural-language request becomes a sequence of tool calls that remains visible and auditable.

An agent can list voices, estimate the requested render, ask for approval, call generate_video and monitor get_video until a terminal status.

The agent still needs an accessible portrait and sufficient credits. Token scope, ownership, expiration and the same per-user rate limit apply to MCP and REST.

prompt

Create a 16:9 talking-avatar video from this portrait.
Use a warm, natural voice. Estimate the credits first and ask before generating.
After approval, monitor the job and return the final download URL.

Agents

Agent skill

Give an agent a short operating policy so it estimates cost, requests approval and handles asynchronous status correctly.

The skill should tell the agent when VlogMe is appropriate, which tools to call, how to preserve idempotency and when to stop polling.

Never place a live token inside the skill file. Keep credentials in the client environment or OAuth store.

markdown

---
name: vlogme-video
description: Estimate and generate VlogMe video jobs through MCP.
---
1. Validate the portrait and requested format.
2. Call estimate_credits before generation.
3. Ask for approval with the estimate.
4. Use a stable idempotency key for transport retries.
5. Poll get_video until a terminal status.

Reference

Errors and retries

Errors use { error: { code, message } }. Branch on the stable code rather than the translated human-readable message.

Use X-Request-Id when contacting support. A 429 includes Retry-After; authentication and validation errors should be corrected rather than blindly retried.

The OpenAPI document contains the complete schemas and error list. Successful responses expose rate-limit limit, remaining and reset headers.

codeHTTPMeaning

missing_token401{ error: { code: "missing_token", message } }

invalid_token401{ error: { code: "invalid_token", message } }

token_expired401{ error: { code: "token_expired", message } }

insufficient_credits402{ error: { code: "insufficient_credits", message, needed, balance } }

invalid_input400{ error: { code: "invalid_input", message } }

invalid_asset400{ error: { code: "invalid_asset", message } }

invalid_json400{ error: { code: "invalid_json", message } }

not_found404{ error: { code: "not_found", message } }

method_not_allowed405{ error: { code: "method_not_allowed", message } }

already_started409{ error: { code: "already_started", message } }

billing_conflict409{ error: { code: "billing_conflict", message } }

rate_limited429{ error: { code: "rate_limited", message } }

internal_error500{ error: { code: "internal_error", message } }

AI video generation API for code, agents and LLMs.

What you can build

Run VlogMe Avatar on Replicate

Authentication

Quickstart

REST endpoints

Create an AI video

Script grammar

Webhooks

MCP server

Client setup

End-to-end agent example

Agent skill

Errors and retries

Developer questions