始める

VlogMe / 開発者向け

コードやAIエージェントから使えるAI動画生成API。

REST APIでVlogMeのAI動画を見積もり・生成し、ネイティブStreamable HTTP MCPでAIエージェントと連携できます。非同期ジョブ、Webhook、話すAIアバター生成に対応します。

APIトークンを作成 →AI動画の作り方ガイドReplicateでAvatarを実行
AIエージェント
REST API
MCP
生成
Webhook
curl https://vlogme.ai/api/v2/projects \
  -X POST \
  -H "Authorization: Bearer $VLOGME_TOKEN" \
  -H "Idempotency-Key: quickstart-001" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Welcome demo",
    "aspect_ratio": "16:9",
    "quality": "Balanced",
    "storyboard": [],
    "tracks": {"visual":[],"avatar_voice":[],"music":[],"sfx":[],"captions":[],"text":[]}
  }'
01AI動画生成APIでできること02ReplicateでVlogMe Avatarを実行03認証04クイックスタート05RESTエンドポイント06AI動画を生成する07スクリプト記法08Webhook09MCPサーバー10MCPクライアント設定11AIエージェント連携の一連の例12エージェント用skill13エラーと再試行
13全13セクション — タップして移動
  1. 01AI動画生成APIでできること
  2. 02ReplicateでVlogMe Avatarを実行
  3. 03認証
  4. 04クイックスタート
  5. 05RESTエンドポイント
  6. 06AI動画を生成する
  7. 07スクリプト記法
  8. 08Webhook
  9. 09MCPサーバー
  10. 10MCPクライアント設定
  11. 11AIエージェント連携の一連の例
  12. 12エージェント用skill
  13. 13エラーと再試行
01
概要

AI動画生成APIでできること

Webアプリと同じアカウント、クレジット、履歴を使い、AI動画プロジェクトと話すアバターをプログラムから生成できます。

バックエンドや自動化にはREST、AIエージェントがツール確認・料金見積もり・生成実行を行う場合はMCPを使います。

公開v1 APIは非同期です。ジョブIDを保存し、ポーリングまたは署名付きWebhookで完了を確認します。生成には正確な予約を満たすクレジットが必要です。

  • クレジット消費前に料金を見積もる。
  • 人物写真とテキスト＋音声、または録音音声からアバター動画を生成。
  • 進捗と期限付き署名URLを取得。
  • Idempotency-Keyで有料リクエストの再送を安全にする。
02
Hosted

ReplicateでVlogMe Avatarを実行

画像＋音声のシンプルなエンドポイントが必要な場合、公開VlogMe Avatar bridgeをReplicateでも利用できます。

すでにReplicateでインフラと請求を管理している場合に便利です。クレジット、履歴、REST、MCPを含む完全な連携はVlogMe APIを使います。

Hosted bridgeは字幕を標準で含む縦型の話すアバターMP4を返します。

ReplicateでAvatarを実行 GitHubのサンプル
03
設定

認証

保護されたすべてのリクエストでBearer tokenを送信します。トークンは作成時に一度だけ表示されます。

Settings → APIで作成し、シークレット管理に保存します。ブラウザコード、モバイルアプリ、公開リポジトリ、クライアントログには含めないでください。

RESTのベースURLは https://vlogme.ai/api/v2 です。漏えいの可能性がある場合はローテーションします。

http
Authorization: Bearer vlm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
url
https://vlogme.ai/api/v2
04
開始

クイックスタート

トークン作成、料金見積もり、レンダリング開始、最終状態までの確認という順で実装します。

例では人物写真URL、スクリプト、voice_id、アスペクト比を送ります。プレースホルダーはVlogMeのサーバーから取得できる素材に置き換えます。

POST成功時は202 Acceptedがすぐ返ります。約10秒ごとに確認するか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"
  }'
05
REST

RESTエンドポイント

OpenAPI 3.1、安定したエラーコード、レート制限ヘッダーを備えたJSON APIです。

/api/v2/openapi.jsonから型付きクライアントを生成したり、PostmanやInsomniaへ取り込めます。

すべてのレスポンスにX-Request-Idが含まれ、非同期POST /videosはポーリング先をLocationでも返します。

GET/projectsユーザーID、プラン、クレジット残高
POST/projects音声合成に使えるvoice_id
GET/projects/:id非同期レンダリングを開始
PATCH/projects/:id状態と署名付きダウンロードURL
POST/renders最近の生成履歴をページ取得
GET/jobs/:id課金せず必要クレジットを見積もり
POST/jobs/:id/cancel対象ジョブを削除またはキャンセル
POST/projects/:id/director-proposals認証不要の稼働確認
bash
curl https://vlogme.ai/api/v2/jobs/$JOB_ID \
  -H "Authorization: Bearer $VLOGME_TOKEN"
06
REST

AI動画を生成する

人物写真と、script＋voice_idまたは音声素材を送信します。レンダリングは非同期で進みます。

portrait_urlまたはportrait_base64を使います。音声はscript＋voice_id、またはaudio_url/audio_base64です。aspect_ratio、emotion_preset、live_subtitles、title、webhook_urlも指定できます。

有料POSTでは一意のIdempotency-Keyが必須です。同じキーで再送すると二重課金せず元のジョブを返します。

  • アスペクト比: 標準9:16、16:9、1:1。
  • トップレベルのinsertsでoverlayまたはcutのB-rollを追加。
  • 背景音のaudio_modeはauto、prompt、asset、off。
  • 202レスポンス: id、status、credits_charged、estimated_seconds、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"
  }'
07
スクリプト

スクリプト記法

シーン切替、B-roll、音声挿入、間、音声演技タグを機械可読なDSLで指定します。

@imageNで話者シーンを切り替え、波括弧でoverlay/chain B-roll、@audioNで音声素材、[shocked]などのElevenLabsタグを記述します。

ダウンロード仕様はツールとLLM向けの契約言語を維持します。MCPではscript_grammar_helpから同じ仕様を取得できます。

.mdをダウンロード仕様のURLを開く
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.
08
REST

Webhook

webhook_urlを渡すと、成功または失敗時にイベントを送信し、一時的な配信エラーでは再試行します。

Settings → APIの専用whsec_シークレットでtimestamp + raw_bodyに対するX-Vlogme-Signatureを検証します。5分より古い時刻を拒否し、X-Vlogme-Event-Idで重複排除します。

5秒以内に2xxを返してください。ネットワーク障害と5xxはバックオフ再試行、4xxは恒久的な拒否です。URL期限切れ時は動画を再GETします。

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
09
MCP

MCPサーバー

VlogMeトークンまたは対話型OAuthを使い、Streamable HTTPでAIエージェントを接続します。

MCPツールはREST v1の薄いラッパーで、データ形式、クレジット計算、エラーコードを共有します。追加変更に備えて未知のフィールドを無視してください。

音声、残高、見積もり、人物写真、生成、状態、キャンセル、履歴のツールがあります。権限のある内部アカウントは作業項目も扱えます。

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
10
MCP

MCPクライアント設定

Claude Code、Cursor、CodexはStreamable HTTPに対応し、古いstdio専用クライアントはmcp-remoteを利用できます。

対話型OAuthまたは環境変数のAPI tokenのどちらか一つを選び、混在させないでください。

MCP設定を変更したら、新しいクライアントセッションを開始してツールを再検出します。

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" }
    }
  }
}
11
MCP

AIエージェント連携の一連の例

自然言語の依頼が、確認可能なツール呼び出しの順序に変換されます。

エージェントは音声一覧、料金見積もり、ユーザー確認、generate_video、最終状態までのget_videoを順に実行できます。

取得可能な人物写真と十分なクレジットが必要です。MCPと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.
12
エージェント

エージェント用skill

見積もり、承認、非同期状態の扱いを短い運用ルールとしてエージェントへ渡します。

VlogMeを使う条件、ツール順序、冪等性の維持、ポーリング終了条件を記述します。

skillファイルに実トークンを入れず、クライアント環境またはOAuthストアで管理してください。

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.
13
リファレンス

エラーと再試行

エラー形式は { error: { code, message } } です。翻訳されるmessageではなく安定したcodeで分岐します。

問い合わせ時はX-Request-Idを伝えてください。429はRetry-Afterを含みます。認証・入力エラーは無条件に再試行せず修正します。

OpenAPIに全スキーマとエラー一覧があります。成功レスポンスにはレート制限のlimit、remaining、resetが含まれます。

codeHTTP
missing_token401
invalid_token401
token_expired401
insufficient_credits402
invalid_input400
invalid_asset400
invalid_json400
not_found404
method_not_allowed405
already_started409
billing_conflict409
rate_limited429
internal_error500
Worth to Know

開発者 の質問

プログラムによる話すアバター動画生成が必要なものは何でも可能です。パーソナライズされたセールス動画、AIチューター、ニュースキャスター、製品説明、NPCダイアログ、大規模なローカライズされたナレーションなど。1つのPOSTリクエストでポートレートURL + スクリプト + 音声IDを受け取り、完成したMP4を返します。

Vlogmeは、Streamable-HTTP MCPエンドポイントを/api/mcpで公開しています。このページにあるCLIスニペットで一度追加すると、エージェントはlist_voices、generate_video、get_videoをネイティブに呼び出すことができます。グルーコードや追加のSDKは不要です。

ウェブアプリと同じで、完成した動画の1秒あたり約1クレジット、最低10クレジットです。/videosにPOSTしたときにクレジットが課金され、レンダリングが失敗したり、完了前に削除したりすると自動的に返金されます。

APIリクエストにはユーザー単位のレート制限があります。成功レスポンスのX-RateLimitヘッダーを確認し、429ではRetry-Afterに従ってください。

はい。すべてのウェブフックにはX-Vlogme-Signatureヘッダー（生ボディのsha256 HMAC、パスワードとしてトークン）が含まれています。配信に失敗した場合、24時間指数関数的なバックオフでリトライされます。

APIとMCPは、認証済みトークンの所有者なら誰でも利用できます。生成にはウェブアプリと同じクレジット残高、見積もり、予約、スコープ、レート制限が適用されます。