Developers

Vlogme Talking-Avatar API & MCP

Generate talking-avatar videos from your code or AI agent. Same engine and credit pricing as the web app. Available on paid plans (Basic and higher). Create a token →

Authentication

All requests need a Bearer token in the Authorization header. Generate one in Settings → API. Tokens are shown once.

Authorization: Bearer vlm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Base URL

https://vlogme.ai/api/public/v1

Endpoints

GET /me

Returns your user id, plan, and current credit balance.

curl https://vlogme.ai/api/public/v1/me \
  -H "Authorization: Bearer $VLOGME_TOKEN"

GET /voices

Lists the voice IDs you can pass to generate.

curl https://vlogme.ai/api/public/v1/voices \
  -H "Authorization: Bearer $VLOGME_TOKEN"

POST /videos

Start a new render. Returns immediately with id and status: "preparing". Credits are charged up front (≈1 credit per second of output, minimum 10). Provide a portrait (URL or base64) and either a script (with voice_id) or an audio file.

curl -X POST https://vlogme.ai/api/public/v1/videos \
  -H "Authorization: Bearer $VLOGME_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "portrait_url": "https://example.com/portrait.jpg",
    "script": "Hello from the Vlogme API.",
    "voice_id": "EXAVITQu4vr4xnSDxMaL",
    "emotion_preset": "natural",
    "live_subtitles": true,
    "webhook_url": "https://yourapp.com/webhooks/vlogme"
  }'

Optional fields: title, face_restore (0–1), watermark_text, video_prompt, video_negative_prompt, audio_url, audio_base64, portrait_base64.

GET /videos/:id

Returns current status. When status is completed, video_url is a signed download URL valid for 1 hour.

curl https://vlogme.ai/api/public/v1/videos/$VIDEO_ID \
  -H "Authorization: Bearer $VLOGME_TOKEN"

GET /videos

Lists your recent renders (newest first). Supports ?limit (max 100) and ?cursor.

DELETE /videos/:id

Deletes a render. If it's still in progress, credits are refunded.

Webhooks

If you pass webhook_url in the create request, we POST to it once when the render finishes (success or failure). Verify the X-Vlogme-Signature header — it is sha256=<hmac> where the HMAC secret is the lowercase hex sha256 of your raw API token (we never store the raw token, so we sign with the same hash we keep in our database — your code derives the secret once from the token).

# Pseudocode for verifying X-Vlogme-Signature
secret = sha256(YOUR_RAW_TOKEN).hex()           # lowercase hex
expected = "sha256=" + hmac_sha256(secret, raw_body).hex()
assert constant_time_eq(expected, request.headers["X-Vlogme-Signature"])

{
  "event": "video.completed",
  "video": { "id": "...", "status": "completed", "video_url": "https://...", ... }
}

MCP server

Vlogme exposes an MCP (Model Context Protocol) Streamable-HTTP endpoint at https://vlogme.ai/api/mcp. Authenticate with the same Bearer token. Available tools: list_voices, get_balance, generate_video, get_video, list_my_videos.

Smoke-test the endpoint directly:

curl -X POST https://vlogme.ai/api/mcp \
  -H "Authorization: Bearer $VLOGME_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Claude Code (native HTTP transport)

claude mcp add --transport http vlogme https://vlogme.ai/api/mcp \
  --header "Authorization: Bearer $VLOGME_TOKEN"

Cursor (native HTTP transport)

Add to ~/.cursor/mcp.json (or the project's .cursor/mcp.json):

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

Codex CLI / Claude Desktop / any stdio client

Clients that only speak stdio (OpenAI Codex CLI, Claude Desktop, etc.) need the mcp-remote bridge. For Codex, add to ~/.codex/config.toml:

[mcp_servers.vlogme]
command = "npx"
args = ["-y", "mcp-remote", "https://vlogme.ai/api/mcp", "--header", "Authorization: Bearer ${VLOGME_TOKEN}"]
env = { VLOGME_TOKEN = "vlm_live_xxxxxxxxxxxx" }

For Claude Desktop / generic JSON (claude_desktop_config.json):

{
  "mcpServers": {
    "vlogme": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://vlogme.ai/api/mcp",
        "--header", "Authorization: Bearer YOUR_TOKEN_HERE"
      ]
    }
  }
}

Agent skill

Drop this into .agents/skills/vlogme/SKILL.md (or the equivalent location for your agent) so the agent knows when and how to use the tools:

---
name: vlogme
description: Generate talking-avatar videos via the Vlogme MCP server. Use when the user wants to turn a portrait + script into a short video.
---

You have access to the `vlogme` MCP server. Workflow:

1. Call `list_voices` once per session to discover voice ids; cache the result.
2. Call `get_balance` to confirm the user has enough credits (≈ 1 credit per second of output, minimum 10 per render).
3. Call `generate_video` with:
   - `portrait_url` (https URL of a clear face photo, 9:16 or square works best) OR `portrait_base64`.
   - `script` (text to speak, ≤ 30 000 chars) AND `voice_id` from step 1
     — OR `audio_url`/`audio_base64` if narration already exists.
   - Optional: `emotion_preset` (calm | natural | expressive | sad), `live_subtitles` (default true),
     `title`, `video_prompt`.
4. Poll `get_video { id }` every 10 s until `status` is `completed` (typical 1–3 minutes).
   Then `video_url` is a signed mp4 link valid for 1 hour — surface or download it immediately.

If `status` becomes `failed`, read `error_message`. Credits are auto-refunded on failure.

Tips: scripts under ~150 words render fastest. Portrait must show exactly one clear face.
Output is always 9:16 vertical.

Errors

Errors are JSON: { "error": { "code": "...", "message": "..." } }. Common codes:

• missing_token / invalid_token — 401
• plan_required — 403 (Free plan)
• insufficient_credits — 402
• invalid_input — 400 (validation, unknown voice_id, etc.)
• invalid_asset — 400 (portrait/audio URL unreachable, too large, or bad base64)
• invalid_json — 400 (request body is not JSON)
• not_found — 404
• internal_error / db_error — 500