AIをつなぐ

YukkuriGen で動画を作るのは、あなたが普段使っている AI です。サイトの編集画面を開く必要はありません。ここでは、AI をつなぐところまでを説明します。

ChatGPT・Claude（claude.ai・デスクトップアプリ）でつなぐ（鍵は不要）

コネクタに次の URL を追加するだけです。APIキーの発行は要りません。登録直後の「AIに接続する」の画面でも、同じ URL と手順を出しています。

https://app.yukkurigen.com/api/mcp

ChatGPT: 設定のコネクタ（アプリ）から、カスタムコネクタとして追加します。認証は OAuth を選びます。プランによっては開発者モードを有効にする必要があります。
Claude（claude.ai・デスクトップアプリ）: 設定 → コネクタ →「カスタムコネクタを追加」に入れ、追加したコネクタの「連携」を押します。無料プランでもカスタムコネクタを1つ追加できます。

追加すると YukkuriGen の「接続の許可」画面（「〇〇を YukkuriGen につなぎますか？」）が開きます。〇〇には、つなごうとしているアプリが名乗った名前が入ります。ログインして、アプリの名前と「接続先」を確かめてから「許可する」を押してください。つないだアプリは APIキー設定ページの「発行済みキー」に、同じアプリの名前と「OAuth で接続」の札付きで出て、そこでいつでも取り消せます。

YouTube への投稿は、許可の画面で「YouTube への投稿も許可する」を選んだときだけ、AI からできるようになります（選ばなければ付きません。AI から投稿できるのは、クレジットを使って書き出した MP4 だけです。→下の「キーが持つ権限」）。

メニューの名前は各アプリの更新で変わることがあります。見当たらないときは、各アプリのヘルプで「カスタムコネクタ」「リモート MCP サーバ」を探してください。

ChatGPT の無料プランや Gemini だけを使っている場合

ChatGPT: 設定に「作成」（カスタムコネクタ）が出なければ、そのプランでは URL を追加できません。開発者モードをオンにすると出るプランもあります。
Claude は無料プランでもカスタムコネクタを1つ追加できます（Anthropic のヘルプ。2026年10月15日に確認）。 claude.ai に無料で登録して、上の手順でつなぐのがいちばん早い方法です。
Gemini アプリ（gemini.google.com）: Google のヘルプでは、MCP の URL（カスタムアプリ）を追加できるのは米国在住・18歳以上・個人アカウント・英語表示の方に限られています（2026年10月15日に確認）。日本からは今のところ追加できません。
Gemini CLI を使う方は、下の手順で APIキーを発行してつなげます（「2-A. MCP でつなぐ」）。

VS Code でつなぐ（鍵は不要）

VS Code も、URL を入れて許可するだけでつながります（2026年10月5日に VS Code 1.139 で確認）。

VS Code で MCP サーバーを追加します。種類は HTTP を選び、URL に次を入れます。
```
https://app.yukkurigen.com/api/mcp
```
VS Code が「MCP サーバー定義 … が YukkuriGen に認証しようとしています」と聞くので、「許可」を押します。
ブラウザで YukkuriGen の画面（「Visual Studio Code を YukkuriGen につなぎますか？」）が開きます。ログインして「許可する」を押してください。
VS Code に戻ると、YukkuriGen のツールが一覧に出ます。

APIキーの発行は要りません。つないだ VS Code は APIキー設定ページに「Visual Studio Code」（「OAuth で接続」の札付き）として出て、そこでいつでも取り消せます。

Cursor・Windsurf など、ほかのエディタ

同じ URL を入れて、鍵なしでつながるか試してみてください。VS Code 以外のエディタでは、 URL だけでつながるかをまだ確かめていません。つながらなければ、下の手順で APIキーを発行して渡してください（鍵を渡す方法は、これまでどおりどのエディタでも使えます）。

以下は、Claude Code・Gemini CLI・Codex・Cursor のように鍵をヘッダーで渡す AI と、スクリプトから呼ぶ場合の手順です。登録直後の「AIに接続する」の画面では、「開発者向け（APIキーを使う）」を開いて「鍵を発行する」を押すと発行されます。

1. APIキーを発行する

APIキー設定ページを開き、キーの名前（例: my-agent）を入れて「発行」を押します。

キーは発行直後の1回しか表示されません。 その場でコピーして保管してください。無くしたときは、古いキーを失効させて新しく発行し直します。

キーの名前は、一覧で見分けるための覚え書きです（例: my-agent、Claude Code）。 URL・Authorization: Bearer …・設定の JSON・キーそのもの（yg_live_…）は名前に入れられません（入れると発行できず、案内が出ます）。設定は、発行したあとに表示されるものを AI 側に貼ります。

無料プランでもキーは発行できます。無料プランでは、台本づくり・音声合成・共有リンク（create_preview_link）での確認までが0クレジットで使えます。MP4 の書き出しには、クレジットパック（買い切り・¥2,500〜。無料プランのままでも買えます）か、スタンダード以上、または API連携ライセンス（買い切り）が必要です。詳しくは料金プランを参照してください。

2-A. MCP でつなぐ（Claude Code / Gemini CLI / Codex / Cursor）

MCP に対応した AI なら、1行登録するだけです。AI ごとのそのまま貼れる手順は APIキー設定ページにもあります。

claude mcp add --transport http yukkurigen https://app.yukkurigen.com/api/mcp \
  --header "Authorization: Bearer <YOUR_KEY>"

Gemini CLI の場合（書き方は Gemini CLI の MCP の説明。2026年10月6日更新のものを確認）:

gemini mcp add --transport http \
  --header "Authorization: Bearer <YOUR_KEY>" \
  yukkurigen https://app.yukkurigen.com/api/mcp

同じページによると、無料枠と Google One の利用者向けの Gemini CLI は、2026年6月18日に Antigravity CLI へ置き換わっています。

登録できたら、AI に話しかけるだけで使えます。

節約術のゆっくり解説を作って。オチのところでカメラを寄せて。

2-B. REST でつなぐ（どの AI でも）

MCP が無い環境では、REST を直接叩きます。仕様は skill.md と openapi.json に置いてあるので、 この2つのURLを AI に読ませるのが早いです。

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: my-first-video" \
  -d '{
    "title": "身近な熱力学のはなし",
    "script": [
      { "speaker": "reimu",  "text": "今日は熱力学第二法則を解説するわ" },
      { "speaker": "marisa", "text": "エントロピーってやつだな" },
      { "speaker": "reimu",  "text": "散らかった部屋が勝手に片付かないのと同じ理屈よ", "cameraMode": "dynamic" }
    ]
  }'

projectId と renderId が返ってきます。GET /api/v1/projects/{projectId}/render/{renderId}/progress でポーリングし、done: true かつ outputFile が入ったら完成です。

これは同期の呼び出しで、音声の合成とレンダーの開始を待ってから返ります。 10行の台本で45秒を超えることがあり、クライアントによってはそこで切れます。切れてもサーバ側では課金もレンダーも進んでいるので、上の例のように Idempotency-Key ヘッダを付けておき、投げ直すときは同じ鍵を使ってください。最初の結果が返り、二重には課金されません（まだ処理中なら 409 in_flight が返るので、少し待って同じ鍵で再試行します）。鍵は動画ごとに別のものにしてください。同じ鍵は同じ注文の投げ直しとして扱われ、24時間は最初の結果が返ります。

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

Prefer: respond-async を付けると、数秒で 202 とジョブが返ります。 対象は output が mp4（既定）のときで、draft は常に同期です。

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: my-second-video" \
  -d '{
    "title": "身近な熱力学のはなし",
    "script": [
      { "speaker": "reimu",  "text": "今日は熱力学第二法則を解説するわ" },
      { "speaker": "marisa", "text": "エントロピーってやつだな" }
    ]
  }'

{ "jobId": "...", "status": "queued", "pollUrl": "/api/v1/jobs/{jobId}", "projectId": "..." }

この応答に renderId は入りません。 GET /api/v1/jobs/{jobId} をポーリングします。

curl https://app.yukkurigen.com/api/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $YUKKURIGEN_API_KEY"

`status`	意味	次にすること
`queued` / `running`	処理中（音声の合成とレンダーの開始）	少し待って再度 GET
`succeeded`	レンダーが始まった（動画はまだ焼いている途中）	`result.renderId` を上の progress に渡して完成を待つ
`failed`	失敗	`error.code` に理由。押さえたクレジットは返金される（下の例外を除く）

注意:

ジョブの受け付けには Authorization: Bearer（APIキー）が要ります。キーには render:mp4 に加えて audio:generate の権限が要ります（どちらも既定で付いています）。ジョブの GET には projects:read が要ります。
クレジットは受け付けた時点で押さえます。 残高不足・プラン不足・レート上限などはその場で返り、そのときプロジェクトもジョブも作られません。ジョブが failed になったら返金されます（反映まで少しかかることがあります）。
MP4 の値段は動画1分につき1クレジット（端数は切り上げ）です。受け付けた時点では長さがまだ決まらないので、 台本の長さから見積もった分を押さえ、音声ができて実際の長さが決まったら精算します（押さえすぎた分は戻ります）。
例外は、レンダーを起動したあとでジョブだけが失敗した場合（まれ）です。レンダーは課金されたまま動いていて返金されません。renderId に agent-{jobId} を渡して progress を見れば結果が分かります（not_found なら起動しておらず、返金されます）。
同じ Idempotency-Key で投げ直すと、ジョブが処理中・成功済みなら同じ jobId が返り、課金は起きません。ジョブが failed になると鍵は空くので、理由を直してから同じ鍵でやり直せます。上の例外のときだけは鍵が空かず、同じ鍵で投げ直すと起動済みのレンダーの renderId が 200 で返ります（2本目は作られません）。
callbackUrl を渡したときの callbackSecret は、この 202 にだけ入ります。ジョブの GET には入らないので、ここで控えてください。
Prefer を付けない呼び出しも、サーバの設定によっては待ったあとに 202 を返すことがあります。 202 を受けたら、上と同じくジョブを追ってください。
ジョブで受け付ける形の create_yukkuri_video から MP4 までは、2026年9月25日に本番で最後まで通しました（22行の台本2本）。何本かをまとめて作るバッチ（POST /api/v1/agent/generate/batch）で MP4 まで出す形は、本番ではまだ確かめていません。初めての形の台本は、短い台本（30秒ほどなら1クレジット）で試してください。
output: "preview"（低解像度の MP4 プレビュー）は 2026年9月27日に廃止しました。指定すると課金されずに断られます。書き出す前の確認は、output: "draft" で作ってから共有リンク（create_preview_link）で行います（0クレジット・全編・音つき）。

全項目の定義は openapi.json にあります。

キーが持つ権限

発行したキーには、次の権限が付きます。YouTube への投稿（youtube:upload）だけは、自分で選んだときにしか付きません（表の下を参照）。

権限	何ができるか
`projects:read` / `projects:write`	台本を読む・直す
`audio:generate`	音声を作る
`render:mp4`	MP4 をレンダーする
`credits:read`	残高を見る

youtube:upload（AI から YouTube に投稿する。MCP の upload_to_youtube）は既定では付きません。付くのは次のときだけです。

APIキー設定ページでキーを発行するときに「YouTube への投稿も許可する」を選んだ
ChatGPT・Claude のコネクタや VS Code（OAuth）でつなぐとき、YukkuriGen の許可の画面で「YouTube への投稿も許可する」を選んだ（AI 側が求めていても、選ばなければ付きません）

権限はキーを作るときに決まります。あとから足したいときは、選び直してキーを発行し直すか、コネクタ・VS Code ならつなぎ直して許可の画面で選びます。

付いていても、AI から投稿できるのは、クレジットを使って書き出した MP4 だけです（render_mp4、または create_yukkuri_video の MP4 で書き出したもの。書き出しに失敗して返金されたものは投稿できません）。プランは問いません。クレジットパックだけの無料プランでも、パックのクレジットで書き出した MP4 なら投稿できます。共有リンクだけで MP4 を書き出していない動画は、先に MP4 を書き出す（動画1分につき1クレジット）か、アプリのサイドバーの「動画」の「YouTube」から自分で投稿します（こちらは従来どおり）。公開範囲は、指定しなければ非公開です。回数の上限は画面からでも AI からでも同じで、1人1日10本・同じ書き出しは3回まで（どちらも失敗した投稿は数えません）、失敗も含めた試行は1日20回までです（→「YouTube アップロード連携のトラブル対処」）。

台本を書くのは、つないだ AI です。YukkuriGen のサーバーは台本を生成しないので、台本づくりのための権限はありません。

つながらないとき

応答	意味	対処
`401 unauthenticated`	キーが違う・失効している	APIキーページで発行し直す
`402 plan_required`	無料プランで、買ったクレジット（パック）も無いのに本番の MP4 レンダーを呼んだ	確認だけなら共有リンク（`create_preview_link`・0クレジット）で見る。MP4 が必要ならクレジットパックを買うかプランを上げる
`402 insufficient_credits`	残高が足りない	クレジットパックを買えば、すぐに書き出せる（無料プランのままでも買える）。プランの毎月の付与分は、次の請求サイクルの開始日に補充される
`403 insufficient_scope`	キーにその権限が無い（YouTube への投稿なら、発行時・許可の画面で「YouTube への投稿も許可する」を選んでいない）	APIキーは選び直して発行し直す。コネクタ・VS Code はつなぎ直して、許可の画面で選ぶ

次は「使い方」で、作る・直す・出すの流れを見てください。