Poietra / developers

API & MCP

エージェントから、
動画をつくる。

編集できる Poietra のプロジェクトを SVG・PNG・MP4 へ。OpenAPI とローカル MCP から、エージェントを制作につなぎます。

OpenAPI JSON MCP を接続Markdown

セルフホスト HTTP API · ローカル stdio MCP

project.poietra.jsonSVG · PNG · MP4

描画サービスを起動する

Node 24 以降、pnpm 10.23.0、Python 3.12 以降を用意します。以下は POSIX シェル用で、固定したバージョンの MoonBit を導入し、描画エンジンをビルドします。描画時に Chromium・FFmpeg・OpenAI キーは不要です。

sh
git clone https://github.com/Poietra/poietra.git
cd poietra
pnpm install --frozen-lockfile
curl -fsSL https://cli.moonbitlang.com/install/unix.sh -o /tmp/install-moonbit.sh
bash /tmp/install-moonbit.sh "$(cat .moon-version)"
export PATH="$HOME/.moon/bin:$PATH"
node scripts/moon.mjs update
pnpm build:moonbit
pnpm render:api

起動したプロセスを残し、別のターミナルでサンプルを検査・描画します。サンプルには、編集できる１秒間のテキストが入っています。

sh
curl -fsS https://poietra.com/examples/hello.poietra.json -o hello.poietra.json
curl -fsS http://127.0.0.1:8799/inspect \
  -H 'Content-Type: application/json' \
  --data-binary @hello.poietra.json
curl -fsS 'http://127.0.0.1:8799/render?format=mp4&width=1280&fps=30' \
  -H 'Content-Type: application/json' \
  --data-binary @hello.poietra.json \
  -o hello.mp4

HTTP / OpenAPI

.poietra.json 全体を application/json の本文として送ります。出力条件はクエリに指定します。描画が成功すると、適切な Content-Type と実際のファイル本体が返ります。

GET/capabilities

Read supported formats, source media and limits

POST/inspect

Validate a portable project and report compatibility

POST/render

Render a portable project to SVG, PNG or MP4

text
format=svg|png|mp4
width=1280&height=720
fps=24|30|60
timeMs=1200

既定の形式は PNG です。timeMs は静止フレームの時刻で、MP4 では 0 にします。幅・高さの片方だけを指定すると、最初の Scene の縦横比を保ちます。MP4 の寸法は偶数が必要です。

ダウンロードする OpenAPI の接続先は http://127.0.0.1:8799 です。起動したサーバー自身の /openapi.json には、その実際の接続先が入ります。poietra.com の公開 URL は描画サーバーではありません。

ローカル MCP を接続する

ビルド後、MCP クライアントから apps/render/mcp.mjs を stdio で起動します。以下は mcpServers 形式の設定例です。絶対パスを置き換え、クライアントの設定形式に合わせてください。HTTP サーバーの起動は不要です。

json
{
  "mcpServers": {
    "poietra": {
      "command": "node",
      "args": [
        "/absolute/path/to/poietra/apps/render/mcp.mjs"
      ]
    }
  }
}
  • poietra_capabilities — 対応形式・素材・上限を確認。
  • poietra_inspect — ローカルの inputPath を検査。
  • poietra_render — inputPath を描画して新しい outputPath に保存。既存ファイルは上書きしません。
json
{
  "inputPath": "/absolute/path/to/hello.poietra.json",
  "outputPath": "/absolute/path/to/hello.mp4",
  "format": "mp4",
  "fps": 30
}

MCP の resources/list・resources/read からも、同じ仕様・プロジェクトスキーマ・サンプルを取得できます。ファイルパスは MCP プロセスが動く端末のものです。現在、リモートの /mcp エンドポイントはありません。

text
poietra://docs/openapi
poietra://docs/project-schema
poietra://examples/hello

編集できる構造を保つ

エージェントはプロジェクトのデータを編集し、検査してから描画します。オブジェクト ID は保ちます。Scene は共通の識別子と親子関係、Composition はそれぞれの見た目と変形を持ち、隣接する Composition を結ぶ Transition に時間・イージング・中間値を保存します。

プロジェクトスキーマはファイルの検証定義から生成しています。検査では参照関係や時間も確認します。issues が空でも、埋め込んだ全素材の復号成功を保証するものではありません。描画時のエラーは内容を修正してから再試行します。

対応形式と上限

  • 出力：SVG・PNG・H.264 MP4。MP4 内の音声は MP3。
  • 入力素材：埋め込み PNG/JPEG と PCM WAV。動画・WebP・圧縮音声・外部の素材 URL は未対応。
  • 入力 32 MiB 以下、出力 64 MiB 以下。各辺 1920 px 以下、合計 2,073,600 ピクセル以下。
  • MP4：60 秒以内かつ 1800 フレーム以内。音が出るトラックは最大 32 本。
  • HTTP の検査・描画は一度に１件。完了まで応答を待ちます。ジョブキュー・ジョブ ID・結果のホスト保存はありません。
  • 描画の既定タイムアウトは 120 秒。HTTP の切断や MCP のキャンセルで処理を中断します。

認証とエラー

既定ではループバックで待ち受けます。他のインターフェースで公開する場合は POIETRA_RENDER_TOKEN を設定し、Authorization: Bearer <token> を送ります。トークンを設定した場合はローカルでも必須です。Studio のログインとは別の認証です。

  • 400 — 未知・重複した出力条件。
  • 401 / 403 — 認証・Origin・Host の拒否。
  • 413 / 415 — 入力サイズ超過・Content-Type の不一致。
  • 422 — データ不正・未対応素材・描画失敗。error の内容を確認。
  • 429 — 処理中。先行する処理の完了後に再試行。
  • 504 — 描画タイムアウト。負荷を減らしてから再試行。
json
{"error":"format must be svg, png or mp4."}