AI から YukkuriGen を動かす

1. APIキーを発行

https://app.yukkurigen.com/settings/api-keys でキーを発行し、環境変数に入れます（発行時に一度だけ表示されます）。

無料プランの鍵でも、台本づくり・修正・音声の合成・共有リンクでの確認まで使えます。MP4 の書き出しには、 クレジットパック（買い切り・無料プランのままでも買えます）か、有料プラン（スタンダード以上）、または API連携ライセンス（買い切り）が要ります。 鍵から BGM を生成するには、有料プランか API連携ライセンスが要ります。 ChatGPT・Claude（claude.ai）は鍵の発行が要らず、コネクタに https://app.yukkurigen.com/api/mcp を貼って「許可する」を押すだけでつながります。 VS Code も同じで、この URL を種類 HTTP の MCP サーバーとして追加し、ブラウザで開く YukkuriGen の画面で「許可する」を押せば鍵は要りません（2026-10-05 に VS Code 1.139 で確認）。 Cursor などほかのエディタは URL だけでつながるかを確かめていないので、つながらなければ鍵を渡してください。

export YUKKURIGEN_API_KEY=yg_live_xxxxxxxx

2. MCP で繋ぐ（Claude Code / Cursor）

claude mcp add --transport http yukkurigen https://app.yukkurigen.com/api/mcp \
  --header "Authorization: Bearer $YUKKURIGEN_API_KEY"

主なツール: create_yukkuri_video / update_lines / generate_audio / render_mp4 / get_job / get_render / get_project / generate_bgm / list_characters / get_credits ほか多数。 全ツール一覧と使い方は skill.md を参照。

create_yukkuri_video の MP4（output:"mp4"）は サーバ側のジョブとして受け付け、数秒で jobId と projectId を返します。まだ完成していないので、get_job が succeeded になったら result.renderId を get_render に渡して完成を待ちます（jobId を get_render に渡さないこと）。 サーバの設定によってはジョブにならず、同期で待ってから renderId を直接返すこともあります。そのときは get_job を挟まず、その renderId を get_render に渡します。output:"draft" はこれまでどおり同期で、数秒で返ります（消費なし）。

3. REST で繋ぐ（1コールで MP4）

curl -X POST https://app.yukkurigen.com/api/v1/agent/generate \
  -H "Authorization: Bearer $YUKKURIGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ai-video-2026-09-15-sync-001" \
  -d '{
    "title": "AIの解説動画",
    "backgroundImageUrl": "https://example.com/bg.jpg",
    "script": [
      { "speaker": "reimu",  "text": "今日はAIについて解説するわ" },
      { "speaker": "marisa", "text": "よろしく頼むぜ" }
    ]
  }'
# → 200 { "projectId": "...", "renderId": "...", "status": "rendering" }

これは同期の呼び出しで、音声合成とレンダー開始を待ってから返ります。renderId で進捗（/render/{renderId}/progress）をポーリングして完成を待ちます。

10行の台本で45秒を超えることがあり、クライアントによってはそこで切れます。切れてもサーバ側では課金もレンダーも進んでいるので、何もせず投げ直すと二重に払うことになります。上の例のように Idempotency-Key を必ず付け、応答が返らなかったら同じ鍵で投げ直してください。最初の結果が返り、二重には課金されません （まだ処理中なら 409 in_flight が返るので、少し待って同じ鍵で再試行します）。 待ちたくないときは、次の Prefer: respond-async を使います。

待たずに受け付けてもらう（Prefer: respond-async）

Prefer: respond-async を付けると、認証・スコープ・プラン・レート上限・クレジットの確認をその場で済ませてから、 数秒で 202 と jobId / projectId を返します。残高不足などはその場でエラーが返り、 そのときプロジェクトもジョブも作られません。202 には renderId が入りません。

curl -X POST https://app.yukkurigen.com/api/v1/agent/generate \
  -H "Authorization: Bearer $YUKKURIGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -H "Idempotency-Key: ai-video-2026-09-15-001" \
  -d '{
    "title": "AIの解説動画",
    "backgroundImageUrl": "https://example.com/bg.jpg",
    "script": [
      { "speaker": "reimu",  "text": "今日はAIについて解説するわ" },
      { "speaker": "marisa", "text": "よろしく頼むぜ" }
    ]
  }'
# → 202 { "jobId": "...", "status": "queued", "pollUrl": "/api/v1/jobs/{jobId}", "projectId": "..." }

# 1. ジョブが succeeded になるまで待つ（音声合成とレンダー開始）
curl https://app.yukkurigen.com/api/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $YUKKURIGEN_API_KEY"
# → { "jobId": "...", "kind": "agent_generate", "status": "succeeded", "projectId": "...",
#     "result": { "projectId": "...", "renderId": "...", "status": "rendering" } }

# 2. result.renderId でレンダーの完成を待つ（done === true かつ outputFile が非空で成功）
curl https://app.yukkurigen.com/api/v1/projects/$PROJECT_ID/render/$RENDER_ID/progress \
  -H "Authorization: Bearer $YUKKURIGEN_API_KEY"

• ジョブの succeeded はレンダーの開始まで済んだという意味です。result は同期の 200 と同じ形（projectId・renderId・status: "rendering"）なので、 そのあと進捗で完成を待ちます。
• 必要なもの: Authorization: Bearer（API キー）と、スコープ render:mp4 と audio:generate の両方（ジョブの状態の取得は projects:read）。
• クレジットは受け付けの時点で押さえます。MP4 は長さがまだ決まらないので台本の長さから見積もった分を押さえ、 音声ができて実際の長さが決まったら精算します（押さえすぎた分は戻ります）。ジョブが failed になったら error.code に理由が入り、押さえた分は返金されます（反映まで少しかかることがあります）。レンダーを起動したあとは、 押さえた分はそのレンダーに引き継がれ、レンダーの成否に従います。まれにレンダーの起動後にジョブだけが失敗した場合は、 レンダーは課金されたまま動いています——renderId に agent-{jobId} を渡して進捗で結果を確かめてください（not_found なら起動しておらず、返金されます）。
• Idempotency-Key を必ず付けてください。同じ鍵で投げ直すと、ジョブが処理中・成功済みなら同じ jobId が返り、二重には課金されません。失敗したジョブの鍵は空くので、理由を直して同じ鍵でやり直せます （レンダーの起動後にジョブだけが失敗した場合は鍵が空かず、同じ鍵で投げ直すと起動済みのレンダーが 200 で返ります）。
• 202 が返ったらジョブを追い、200 が返ったら同期と同じ本文（renderId 入り）として扱ってください。同じ鍵の完了済み結果の再送などでは、Prefer を付けていても 200 が返ります。
• output:"draft" は常に同期です。Prefer を付けない呼び出しも既定では同期のままですが、 サーバの設定によっては一定時間だけ待ったあと 202 を返すことがあるので、202 も扱えるようにしておいてください。
• ジョブで受け付ける形（2026-09-15 追加）は、2026-09-25 に本番で最後まで通しました（台本→音声→MP4 の完成まで）。 まとめて作るバッチの MP4 出力はまだ本番で通していないので、初めての形の台本は少数の行で試し、 進捗が完成（done かつ outputFile）を返すことを確かめてから流してください。

エンドポイント

機械可読な定義: https://app.yukkurigen.com/openapi.json ・ エージェント用手順書: /skill.md