REST APIとMCPのワークフロー

REST APIとMCPサーバーは、VlogMeアプリと同じジョブ（Director、Video・Image・Audio Studio、Aisma、DUB、ニュース動画）を、同じアカウント、同じクレジット残高、同じLabで実行します。

アクセス：APIとMCPは、VlogMeに登録したすべてのアカウントで利用できます。Account → API & MCPでキーを作成してください。サポートの承認は不要です。大量の利用やチームでの連携については、sales@vlogme.aiまでご連絡ください。

連携は次の5つの手順で進みます。

1. APIキーを作成します（Account → API & MCP。管理画面は現在英語のみです）。
2. ジョブに必要な写真、動画、音声をアップロードするか、Labのファイルを使います。
3. ジョブの見積もりを取ります。VlogMeが正確なクレジット料金を返します。
4. その見積もりでジョブを開始します。異なる料金で実行されることはありません。
5. ポーリングまたはWebhookで状況を確認します。結果はLabに保存されます。

エージェントはMCPサーバーで同じことができます。ツールはジョブ、Director、Labのファイル、プロジェクト、テンプレート、音声、ニュース動画、SNSへの公開を扱い、RESTと同じキー、残高、確認を使います。

APIとMCPの変更は開発日誌でお知らせします。

AIエージェントは、MCPサーバーhttps://vlogme.ai/mcpを通じて、同じアカウント、キー、残高、料金で動きます。クライアントごとの手順はMCPサーバーの設定にあります。

• Claude Code、Cursor、VS Code
• Gemini CLI、Codex
• n8nのワークフロー

Claude Codeでは、キーをVLOGME_API_KEYに入れて、次のコマンドを1回実行するだけです。

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

エージェントは、有料のジョブの前に必ず見積もりを取り、クレジット額を示します。すべてのツールと必要なキーの権限は、下のMCPサーバーの章に載っています。

すべてのリクエストは、Authorizationヘッダーでキーを送ります。

Authorization: Bearer vma_…

• キーでできることは、Account → API & MCPで作成時にチェックした内容です。
  • read：Labのファイル、ジョブ、残高の一覧と見積もりの取得。すべてのキーに付きます。
  • write：ファイルのアップロードとインポート、名前の変更とアーカイブ、プロジェクトの保存、Directorでの計画と素材の準備、見積もり額での有料ジョブの開始。
  • delete：ファイル、プロジェクト、クローン音声、ニュースモニターの削除。削除は元に戻せません。
  • share：公開共有リンクの作成と取り消し。
  • publish：連携したSNSアカウントへの動画の投稿や予約。
• この選択ができる前に作成したキーは、これまでどおりの権限を保ちます。「Read」キーは読み取りのみ、「Read and create jobs」キーは以前と同じく削除と共有もできます。
• キーに許可されていないリクエストは、403とcode: scope_missingで拒否されます。GET /api/meで、そのキー自身のtoken.scopesを確認できます。
• キーの有効期間は1〜365日（既定は90日）です。Account → API & MCPでいつでも無効にでき、そのキーを使う連携はすぐに停止します。
• キーでは、プランの変更、別のキーの作成、アカウントの削除、管理ツールの利用はできません。これらにはログインしたセッションが必要です（code: session_required）。

キーは秘密にしてください。キーはアカウントの権限で動作し、そのアカウントのクレジットを消費します（利用規約）。

2つの公開アドレスで、連携から送れる内容をすべて確認できます。キーは不要です。

• GET /api/catalogは、すべてのジョブのkind（workflowまたはモデルごと）を一覧にします。入力のJSON Schema、使うLabのファイル、選べる長さ・アスペクト比・画質、料金ルール、入力例とそのクレジット数、現在利用できるかどうかが含まれます。?kind=videoで絞り込めます。Directorのスキーマ（新規プロジェクト、編集コマンド、チャットの発言、素材の準備）もここにあります。
• GET /api/openapi.jsonは、REST APIのOpenAPI 3.1の定義です。各操作のx-scopeに、必要なキーの権限が書かれています。

server_fillsに挙がる項目（動画の長さなど）は、VlogMeがファイルから測定するため、送らなくてもかまいません。

ジョブは1つの作業単位です。クリップ、アバター、画像、音声トラック、編集、吹き替え、Aismaでの変更、ニュース動画の動画、Directorのレンダリングなどがあります。kindはvideo, avatar, image, audio, video_edit, dub, trend, aisma, voice_clone, directorのいずれかで、inputにはアプリの対応する画面と同じ設定を入れます。

通常のImage Editorでの変更はブラウザーで書き出すため、サーバーのジョブではありません。AIによる画像生成・編集には、対応するworkflowとkind: imageを使ってください。

たとえば、画像の見積もりを取ってから開始する場合：

curl https://vlogme.ai/api/jobs/quote \
  -H "Authorization: Bearer $VLOGME_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "image", "input": {…}}'

curl https://vlogme.ai/api/jobs \
  -H "Authorization: Bearer $VLOGME_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b8e-7d4a-4f0e-9b1a-2c3d4e5f6a7b" \
  -d '{"kind": "image", "input": {…}, "quoted_credits": 12, "quote_fingerprint": "…"}'

見積もりの後に料金や入力が変わった場合、開始は409で拒否され、何も請求されません。もう一度見積もりを取ってください。失敗したジョブの対象クレジットは、自動的に残高に戻ります。開始したジョブは取り消せません。提供元がジョブを止められるとは限らないためです。

Aismaの編集のクリップを1つだけ変更する。完了したAismaの編集は、動画全体を作り直さなくても、クリップを1つだけ生成し直せます。GET /api/jobs/{id}/clips（idは編集そのもののジョブ）は、編集のクリップを、番号indexと生成し直す場合の料金creditsとともに返します。inputを{"clip": {"job_id": "<編集のジョブID>", "op": "regenerate", "part": <index>, "clarification": "…"}}としたaismaジョブの見積もりを取り、開始してください。補足のclarificationは任意で、クリップは編集と同じバージョン・画質で作られます。請求されるのはそのクリップの分だけです。Aismaが補足を適用しなかった場合、クリップを作れなかった場合、撮影したままにした場合は、何も請求されません。終了したジョブのinput.clip_resultには、結果のoutcomeと、補足が適用されなかった場合の理由reasonが入ります。ジョブの結果は更新された動画全体で、Labの新しいファイルになります。読み取れるクリップがない編集では、clipsはnullです。クリップを変更できるようになる前に作られた編集か、元の動画と一緒にファイルが削除された編集です。それ以外では、disabledが今どのクリップも変更できない理由（starting、failed、busy、materialsのいずれか。変更できるときはnull）を、finishが動画全体を最新にする方法（assemble: {"clip": {"job_id": "…", "op": "assemble"}}のジョブを開始します。reassemble: POST /api/jobs/{id}/reassembleを呼びます。null: 最新です）を示します。modeがchangeのクリップは、Aismaが撮影したままにしたクリップです。キーで生成し直すには補足が必要です。請求なしで終わった更新には、1時間あたりの上限があります。上限は編集ごとにあり、アカウント内のすべての編集の合計にもあります。どちらかを超えると、見積もりもジョブの開始も429とretry_after_sを返します。Aismaが確認の質問をするのはアプリの中だけです。キーで開始した編集に質問が届くことはありません。

write権限のあるキーで、アイデアから完成した動画ファイルまで進められます。

1. POST /api/director/projectsに{"version": 2, "concept": "…"}を送ると、プロジェクトが作成されます。
2. 新しいclient_request_idとプロジェクトのbase_revisionを付けてPOST /api/director/projects/{id}/turnsを送ると、Directorが計画を立てます。GET /api/director/turns/{発言のid}?wait=30で、計画ができるかDirectorが質問するまで待ちます。質問にはPOST /api/director/turns/{発言のid}/answerで答えます。
3. POST /api/director/projects/{id}/prepareで無料の画像、音声、音楽を用意し、GET /api/director/projects/{id}/viewで準備状況を確認します。準備には時間がかかるため、すべてのmaterialsがreadyになるまで/viewを読み直してください。
4. POST /api/director/projects/{id}/render/quoteで動画の見積もりを取り（remake_scene_numbersで選んだシーンを作り直せます）、そのrevision、quoted_credits、quote_fingerprintとIdempotency-Keyを付けてPOST /api/director/projects/{id}/renderで開始します。見積もり後に計画が変わっていれば、開始は409（code: revision_conflict）で拒否され、何も請求されません。
5. ジョブが終わるまでGET /api/jobs/{ジョブのid}?wait=30を繰り返し、GET /api/director/projects/{id}/resultで動画と字幕を15分間有効なリンクとともに受け取ります。

キーによる計画、チャット、無料の準備は、アプリと同じアカウントの無料枠を使います。多く計画するエージェントは、アプリの分の無料枠も使い切ります。いったん使い切ると、応答にlimited: trueが入ります。

上限内では人物や場所の画像は無料です。無料アカウントが上限を超えると画像は作られず、/prepareの応答でplan_required（skippedにも）に入ります。続けるにはプランが必要です。プランがあれば、無料枠を超えた画像は/prepareの応答のchargedに料金とともに返ります。POST /api/jobs/quote（kind director、input {"v": 2, "stage": "materials", "project_id": "…", "revision": 3, "keys": ["…"]}）で見積もりを取り、ほかの有料ジョブと同じように開始してください。レンダー時に/viewでまだmissingの画像はレンダー内で作られ、その見積もりに含まれます。作成済みの画像を作り直す（もう一度試す）ときは、その画像のキーをkeysに入れ、"regenerate": trueを付けてPOST /api/director/projects/{id}/prepareを送ります。

計画を変えるには、/turnsにメッセージを送る（一部のシーンだけ変えるときはscope.block_idsを付ける）か、GET /api/catalogのdirector.edit_command_schemaに沿った構造化された編集をPOST /api/director/projects/{id}/editsに送ります。POST /api/director/projects/{id}/undoで以前のリビジョンに戻せます。各変更には、読み取ったbase_revisionと新しいclient_request_idを付けます。古いリビジョンは409で拒否され、同じclient_request_idを再送すると、変更は二重にならず再生されます。

計画に追加するファイルにはrights_confirmed: trueが必要です。キーから送った場合、それはファイルとそこに写る人物を使う権利があることを、あなた自身が確認したものとして扱われます（利用規約）。

• GET /api/assetsはLabのファイルを新しい順に返します。section=mainはファイル（完成した動画、結果、アップロード）、workingは制作中のプロジェクトが使うファイル、archivedはアーカイブ、all（既定）はアーカイブ以外のすべてのファイルです。kind、project_id（またはnone）、qで絞り込み、fields=compactでメタデータを省き、limitと返されたnext_offsetでページを進めます。GET /api/assets/working-projectsは作業ファイルをプロジェクトごとにまとめます。
• mime_type、bytes、titleを付けたPOST /api/assets/intentでLabのファイルを予約し、再開可能なアップロード（tus）のアドレスとトークンを受け取ります。画像：JPEG、PNG、WebP、BMP。動画：MP4、MOV、M4V（150分まで）。音声：MP3、M4A、WAV、OGG。1ファイル1GBまでです。
• content_sha256（ファイルのSHA-256、小文字の16進数64文字）を付けると、すでにアップロード済みの同じファイルを再利用します。応答は200で、reused: trueとそのファイルが返り、アップロードは不要です。2つ目のコピーを残したいときはallow_duplicate: trueも送ってください。
• POST /api/assets/{id}/completeでアップロードを確認すると、そのファイルをジョブのinputで使えるようになります。
• APIキーでは、intentの応答にput_urlも含まれます。tusの代わりに、1回のPUTでファイル全体を送れる署名付きアドレスです（curl -T clip.mp4 -H "Content-Type: video/mp4" "$put_url"）。Idempotency-Keyヘッダー（UUID）を付けると、再送しても同じファイルが返ります。
• POST /api/assets/importに{"url": "https://…"}とIdempotency-Keyを送ると、公開HTTPSアドレスのファイルをバックグラウンドで取り込みます。応答は新しいファイルのidを含む202で、その後GET /api/assets/{id}のimport.statusで、準備完了まで、またはerror_code付きのfailedを確認できます。VlogMe自身のアドレス、プライベートネットワーク、IPアドレスは拒否されます。
• PATCH /api/assets/{id}にtitleを送ると名前を変更し、archived: trueでアーカイブへ移します（falseで戻します）。制作中のプロジェクトが使うファイルは作業ファイルに残ります。
• DELETE /api/assets/{id}はファイルを完全に削除します（delete権限）。実行中のジョブがまだ使うファイルは、409で拒否されます。
• GET /api/assets/working-projects/{id}/cleanupは、1つのプロジェクトでクリーンアップが削除するファイル（以前のテイク、使われていない画像、残りもの）を、それぞれの理由とともに示します。同じアドレスに、そのプレビューのasset_idsを付けてPOSTすると、1回のリクエストで5つまで削除します（delete権限）。自動で削除されることはありません。
• GET /api/assets/{id}/downloadは60秒間有効な非公開リンクを返します。ttlで最大1時間まで延ばせ、redirect=1ではファイルへのリダイレクトで応答するため、curl -Lでダウンロードできます。

APIでアップロードしたファイルも、アプリでアップロードしたファイルと同じく、Labの中で非公開のまま保存されます。

• GET /api/projectsはプロジェクトを新しい順に返します。Directorのプロジェクト（アイデアと概要つき）と、ニュース動画、Aisma、DUB、Image Editorの下書き（保存したデータつき）です。kindで絞り込み、limitと返されたnext_cursorでページを進めます。
• POST /api/projectsにkind、title、dataを送ると新しい下書きを保存します。Idempotency-Keyヘッダーを付けると、再送しても同じ下書きが返ります。PUT /api/projects/{id}に下書きの現在のrevisionを付けると変更を保存し、古いリビジョンは409で拒否されます。DELETE /api/projects/{id}はプロジェクトを削除します（delete権限）。Labのファイルは残ります。
• Directorのプロジェクトは下書きではなく、POST /api/director/projects（上記）で作成します。
• GET /api/templatesは公開中のAismaテンプレートの一覧（category、q、limit、cursor）、GET /api/templates/{id}は1つのテンプレートを返し、POST /api/templates/{id}/openにIdempotency-Keyを付けると新しいプロジェクトとして開きます。
• GET /api/voicesは、ジョブやDirectorの配役で使える音声（プリセット音声と、準備ができたクローン音声）の一覧です。GET /api/voice-clonesはクローン音声と状態の一覧、DELETE /api/voice-clones/{id}は音声の提供元からも含めてクローンを削除します（delete権限）。

• GET /api/trends/search?q=…は最近のニュースを検索します（languageはenまたはru。country、category、domains、sort_by）。POST /api/trends/scriptはニュースの出典に基づく台本を書き、POST /api/trends/verifyは台本を出典と照らし合わせます。
• ニュースモニターは、スケジュールに沿って新しい話題を探します：GETとPOST /api/trends/monitors、PUTとDELETE /api/trends/monitors/{id}。
• GET /api/social/connectionsは連携したSNSアカウント、GET /api/social/publicationsは投稿とその状態を返します。アカウントの連携には、アプリへのログインが必要です。
• POST /api/social/publicationsにasset_id（準備ができた動画）とplatform、必要に応じてcaption、headline、visibility、cover_asset_id、scheduled_at、そしてIdempotency-Keyを送ると、動画を投稿または予約します。publish権限が必要で、キーにこの権限があるのは作成時にチェックした場合だけです。投稿は誰でも見られます。エージェントは動画、投稿先、キャプションを示し、あなたがはっきり承認してから投稿してください。
• POST /api/social/publications/{id}/cancelは、まだ投稿されていない公開を取り消します（publishまたはwrite権限）。
• 動画エディターのプレビュー（POST /api/video-editor/preview）はMP4のストリームを返すため、RESTでのみ使えます。

作業の終了を知る方法は2つあります。

ロングポーリング。GET /api/jobs/{id}?wait=30とGET /api/director/turns/{id}?wait=30は、ジョブや発言が終わるまで指定した秒数（0〜30）待ってから、waited_secondsとともに返します（発言はDirectorが質問したときにも止まります）。まだ実行中なら、retry_after_sが次に問い合わせる目安です。Webhookを受け取れないノートPC上のエージェントは、この方法で待ちます。

Webhook。APIキーでジョブを開始するときに公開HTTPSアドレスのwebhook_urlを指定すると、ジョブの終了時にVlogMeがイベントを送信します。

{"id": "job.<job id>.succeeded", "type": "job.succeeded", "created_at": "…",
 "job": {"id": "…", "kind": "image", "status": "succeeded", "result_asset_id": "…", "error_code": null}}

• 種類はjob.succeeded、job.failed、job.partialのいずれかです（job.partialは、一部の結果がLabにあり、欠けたパートのクレジットが返却された状態）。確認中のジョブ（needs_review）はまだ終了していないため、終了した時点でイベントが届きます。
• 最終的な結合に失敗した一部完了のジョブは、POST /api/jobs/{id}/reassembleで無料で結合し直せます。結合が終わると、その結果を伝える新しいイベントが届きます。結合が再び失敗し、ジョブが一部完了のままの場合も同じです。結果ごとにイベントIDは異なります（一部完了の場合は末尾にerror_codeが付きます：job.<job id>.partial.<error code>。無料の結合し直しがn回失敗したあとは、さらに.retry<n>が付きます）。この回数はGET /api/jobs/{id}のreassembly_failuresで確認できます。クリップを変更したAismaの編集は、結合の方法が異なります。このリクエストは409（clip_job_required）で拒否され、動画はinputを{"clip": {"job_id": "<編集のジョブID>", "op": "assemble"}}としたジョブで無料で結合します。クリップのジョブがaisma_clip_video_pendingで一部完了になった場合も、同じジョブで動画を結合します。
• 各送信にはX-VlogMe-Event-Id、X-VlogMe-Timestamp、X-VlogMe-Signature: v1=<hex>が付きます。署名は、APIキーのSHA-256ダイジェストを鍵とした<timestamp>.<body>のHMAC-SHA256です。署名を検証し、古いタイムスタンプは拒否してください。
• 2xxの応答がない送信は、30秒後から間隔を広げて最長1時間おきに、最大8回まで再送されます。キーを無効にすると送信は止まります。

Model Context Protocolに対応したAIエージェントは、同じAuthorization: Bearerキーでhttps://vlogme.ai/mcp（HTTP POSTによるJSON-RPC 2.0）に接続します。https://vlogme.ai/api/mcpも同じサーバーの別のアドレスです。対応するプロトコルバージョンは2026-07-28（ステートレス、Mcp-MethodとMcp-Nameヘッダーとserver/discoverを使用）と、2025-11-25、2025-06-18、2025-03-26（initializeあり。クライアントが求めたバージョンで応答します）です。MCP-Protocol-Versionヘッダーのないリクエストは2025-03-26として扱います。1リクエストは1MBまでです。

ツールは、キーでRESTからできることを扱います。各ツールには表の権限が必要です。ツールの一覧は、キーの権限によって変わりません。キーに許可されていない呼び出しは、code: scope_missingの拒否として返ります。URLに?tools=allを付けると（https://vlogme.ai/mcp?tools=all）、一覧に表のすべてのツールが載ります。クライアントごとの接続方法はMCPサーバーの設定をご覧ください。

• 読み取りだけのツールにはreadOnlyHintが付きます。削除するツールにはdestructiveHintが付き、説明は「Irreversible.」で始まります。何かを公開するツールの説明は「Public.」で始まり、有料のツールはクレジットがかかることを明記しています。エージェントは、これらの呼び出しを先にあなたに確認する必要があります。
• 引数は各ツールのスキーマで確認されます。誤った引数や未知の引数は、何も送信される前に、isError: trueとcode: invalid_inputの結果として拒否されます。
• 一覧を返すツールはすべてlimit（1〜50、既定は20）とcursorを受け取り、next_cursor（最後のページではnull）を返します。
• vlogme_wait_jobとvlogme_director_turnは、1回の呼び出しで最大30秒待ちます。応答にretry_after_sがある間は、もう一度呼び出してください。
• リソース：resources/readは、vlogme://docs/agents（エージェント向けガイド：アイデアから動画まで、料金のルール、待ち方、エラー）、vlogme://catalog（ジョブのカタログ）、vlogme://openapi（OpenAPIの定義）を返します。initializeは、同じ流れを短くまとめた説明を返します。

MCPでジョブを開始する手順：

1. kindとinputを指定してvlogme_quote_jobを呼び出し、返されたcreditsを確認します。
2. 同じkindとinput、新しいUUIDのidempotency_key、返されたcreditsを設定したquoted_credits、変更していないquote_fingerprintを指定してvlogme_create_jobを呼び出します。Aismaでは、見積もりのquote_proofも変更せずに渡してください。
3. 確認の有効期限が切れた場合や、料金・入力が変わった場合は、新しい見積もりを取得して確認してから再試行します。受け付け済みのリクエストを同じidempotency_keyで再送すると、同じジョブが返ります。

Directorの動画も同じルールです。vlogme_director_quote_renderで見積もり、料金を示してから、その見積もりとidempotency_keyを付けてvlogme_director_renderを呼び出します。

任意のwebhook_urlで、上記のジョブイベントを受け取れます。MCPはRESTと同じAPIキー、残高、料金の確認を使います。

Codexでは、~/.codex/config.tomlにサーバーを追加し、キーは環境変数VLOGME_API_KEYに保存します。

[mcp_servers.vlogme]
url = "https://vlogme.ai/mcp"
bearer_token_env_var = "VLOGME_API_KEY"
tool_timeout_sec = 120

• ジョブのクレジットはアプリと同じで、同じ残高から差し引かれます。見積もりがそのまま料金です。
• Idempotency-KeyはUUIDです。同じキーを別のリクエストに使うと拒否されます。
• Aismaのジョブには、見積もりが返すquote_proofが必要です。有効期限があるため、切れたら見積もりを取り直してください。
• Aismaのジョブには任意のengineを指定できます。値はv1かv2で、省略するとv2です。バージョンによって料金と使える参考写真の枚数が異なり、それぞれの上限はGET /api/catalog?kind=aismaで確認できます。見積もりはバージョンごとのものなので、別のバージョンで開始するには見積もりを取り直してください。テンプレートから開いたプロジェクトは常にv2で実行されます。
• エラーはHTTPステータスとともにJSONの{"error": "…", "code": "…"}で返ります。400は入力の誤り（invalid_input）、403はキーの権限で許可されていないリクエスト（scope_missing、session_required）、404は見つからない場合、409は料金・入力・計画の変更、429はリクエストが多すぎる場合、503はサービスまたは提供元が一時的に利用できない場合です。
• リクエスト数には上限があります。上限を超えると429、code: rate_limited、Retry-Afterヘッダーが返ります。その秒数だけ待ってから再試行してください。
• MCPでは、拒否されたツール呼び出しはHTTPエラーにならず、isError: trueのツール結果として返ります。中身は同じJSON（error、status、あればcode）です。MCPでHTTPエラーになるのは、キーがないか無効な場合（401）、APIアクセスのないアカウントや別のOriginからの場合（403）、形式が正しくないリクエストだけです。
• APIで作成したものにも、アプリで作成したものと同じく利用規約が適用されます。