AI から YukkuriGen を動かす

1. APIキーを発行

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

API/MCP の利用には有料プラン（スタンダード以上）、または API連携ライセンス（買い切り）が必要です。

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 / list_characters / get_credits

create_yukkuri_video の MP4（output:"mp4" / "preview"）は サーバ側のジョブとして受け付け、数秒で 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）。
• クレジットは受け付けの時点で押さえます。ジョブが 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 追加）は、本番で最後まで通した実績がまだありません。 まず少数の行で試し、進捗が完成を返すことを確かめてから本番の台本を流してください。

エンドポイント

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