[ HOME ][ BLOG ][ KUON ][ X ][ INSTAGRAM ]

Claude Code × Replicate APIで作る「全自動コンテンツ生成」の仕組み

2026-05-29 | AIモデル, WEB技術

「プロンプトを一行投げるだけで、画像が生成されて適切なフォルダに保存される」——こうした作業を毎回手作業でやっていると、地味に時間が溶けていきます。
私は先日、Claude CodeにReplicate APIを叩かせ、生成された画像をMac上の指定フォルダへ自動保存する仕組みを構築しました。

この記事では、その仕組みの考え方と作り方を、実際のコマンド例とともに整理します。
一度組んでしまえば、Claude Codeに「○○の画像を作って」と頼むだけで、生成からダウンロード、保存までが一気通貫で走るようになります。

なお、内容はReplicateの公式HTTP APIドキュメント(2026年5月時点)に基づいて確認していますが、API仕様は更新されることがあるため、本番運用前に公式ドキュメントで最新仕様の確認をおすすめします。

なぜ「Claude Code × Replicate」なのか

Replicateは、FLUXやStable Diffusionといった画像生成モデルをはじめ、多数のAIモデルをAPI経由で実行できるプラットフォームです。
これ単体でも便利ですが、APIを叩くには「リクエストを投げ、生成完了をポーリングで待ち、出力URLからファイルをダウンロードして保存する」という一連の手続きが必要になります。

Claude Codeを組み合わせる旨味は、まさにこの「一連の手続き」を肩代わりしてくれる点にあります。
Claude Codeはターミナル上でcurlを実行でき、JSONレスポンスを解釈し、ファイルを任意の場所へ保存し、さらにエラーが出れば自分で原因を切り分けて修正します。

つまり人間は「何を作るか」だけを伝え、「どうやって取得・保存するか」はClaudeに任せられる、という役割分担が成立します。

全体像 ── 3つのステップ

仕組みは大きく三段階に分かれます。
まず認証情報の安全な格納で、ReplicateのAPIトークンを環境変数やファイルとして用意します。
次に生成リクエストと結果の取得で、Claude CodeがAPIを叩いて画像を生成し、ポーリングで完了を待ちます。
最後に保存の自動化で、出力された画像URLからファイルを指定フォルダへダウンロードします。

以下、それぞれを具体的に見ていきます。

ステップ1:APIトークンを安全に格納する

Replicateのトークンは簡単にで取得でき、r8_で始まる文字列となります。

これはパスワードと同等の秘密情報なので、コードに直接書き込まず、環境変数で管理するのが鉄則です。
漏れたら大変ですので、ここに慣れていない方は必ずAIチャットで環境変数管理に関する知識を習得してください。

Replicate公式も同じ推奨をしています。

最もシンプルなのは、シェルの設定ファイルに環境変数として書く方法です。

Copy# ~/.zshrc または ~/.bashrc に追記
export REPLICATE_API_TOKEN="r8_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

ただし、ご質問にあった「APIキーの格納フォルダ」をプロジェクト内に持つ運用なら、専用のディレクトリに環境ファイルを置き、.gitignoreで確実に除外する形が扱いやすいです。

Copymkdir -p ~/replicate-content/.secrets
echo 'REPLICATE_API_TOKEN=r8_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' > ~/replicate-content/.secrets/replicate.env
echo '.secrets/' >> ~/replicate-content/.gitignore

ここで一点、安全面の注意があります。
Claude Codeに自動でAPIキーを扱わせる場合、キーが記載されたファイルが誤ってログやコミットに流出しないよう、トークン値そのものをClaudeに復唱させないことと、保存先ディレクトリを必ずバージョン管理の対象外にしておくことが重要です。
また重要な事実として、万が一漏れた場合、トークンはいつでもReplicate側で失効・再発行できることも覚えておいてください。

ステップ2:Claude Codeに生成リクエストを叩かせる

Replicateの画像生成は、HTTPのPOSTで「予測(prediction)」を作成するところから始まります。
ここで知っておくべき重要な仕様が二つあります。

一つは、FLUXのような公式モデル(official models)は{owner}/{model_name}の形式でモデル名を指定するだけで動く点です。
一方、コミュニティ製の一般モデルは64文字のバージョンIDが必要になります。FLUXのblack-forest-labs/flux-schnellのような公式モデルなら、専用エンドポイントを使うとバージョンID不要で手軽です。

もう一つがPrefer: waitヘッダーです。
これを付けると、リクエストが最大60秒間オープンのまま生成完了を待ってくれます。
生成が速いモデル(flux-schnellなど)であれば、これだけで「投げて即結果が返る」同期的な使い方ができ、ポーリングのコードを書く必要がありません。

公式モデルを同期モードで叩く例は次の通りです。

Copysource ~/replicate-content/.secrets/replicate.env

curl -s -X POST \
  https://api.replicate.com/v1/models/black-forest-labs/flux-schnell/predictions \
  -H "Authorization: Bearer $REPLICATE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait" \
  -d '{
    "input": {
      "prompt": "a serene Japanese garden at dawn, soft morning light, ultra detailed",
      "aspect_ratio": "16:9",
      "output_format": "png"
    }
  }'

成功すると、レスポンスのJSON内にstatus(succeededなど)とoutput(画像のHTTPS URL配列)が含まれます。
Claude Codeはこのレスポンスを読んで、次のダウンロード処理へ自動的に進めます。

生成に時間がかかるモデルや、Prefer: waitの60秒を超えるケースでは、レスポンスはstarting状態で返ります。
その場合は、レスポンスに含まれる予測IDを使って完了までポーリングします。
ここはClaude Codeに任せると、statusがsucceededかfailedになるまで数秒おきに確認するループを自分で書いて回してくれます。

Copy# ポーリングの考え方(Claudeが自動生成するロジックの例)
PREDICTION_ID="ここに予測IDが入る"
curl -s \
  https://api.replicate.com/v1/predictions/$PREDICTION_ID \
  -H "Authorization: Bearer $REPLICATE_API_TOKEN"

ここで運用上とても重要な注意があります。
API経由で作成した予測の入出力データは、デフォルトで1時間後に自動削除されます。
つまりoutputのURLは永続的ではないので、生成が成功したら速やかにダウンロードして保存する必要があります。
次のステップが「自動保存」である理由はここにあります。

ステップ3:出力画像を指定フォルダへ自動保存する

outputに入っている画像URL(replicate.deliveryドメイン)からファイルをダウンロードし、目的のフォルダに保存します。
出力ファイルの取得時にもAuthorizationヘッダーが必要になる点に注意してください。

Copymkdir -p ~/replicate-content/output

# outputのURLをimage_urlに取り出した前提
curl -s -L "$IMAGE_URL" \
  -H "Authorization: Bearer $REPLICATE_API_TOKEN" \
  -o ~/replicate-content/output/$(date +%Y%m%d_%H%M%S).png

ファイル名にタイムスタンプを使うと、連続生成しても上書きされず、生成履歴がそのまま残ります。
Claude Codeにこの保存先と命名ルールをあらかじめ伝えておけば、毎回同じ規則でファイルが整理されていきます。

仕組みを「再利用可能」にする ── ここが本題

ここまでは手順の説明ですが、毎回これらのコマンドをClaudeに口頭指示していたら自動化とは言えません。
Claude Codeでこの仕組みを定着させる鍵は、カスタムスラッシュコマンドやスキルとして手順を保存しておくことです。

具体的には、プロジェクトの.claude/commands/ディレクトリにMarkdownファイルを置くと、それが独自のスラッシュコマンドになります。
たとえばgenerate-image.mdに「Replicate APIで画像を生成し、outputフォルダにタイムスタンプ付きで保存する。
トークンは.secrets/replicate.envから読む。失敗したらリトライする」といった手順を書いておけば、以降は/generate-image 夕暮れの海のように呼ぶだけで全工程が走ります。

さらに踏み込むなら、CLAUDE.md(Claude Codeが自動的に読み込むプロジェクト設定ファイル)に「画像生成は常にflux-schnellを使い、出力はPNG、保存先は~/replicate-content/output」といったプロジェクト全体のルールを書いておくと、毎回の指示がさらに短くなります。

仕組みの「設計図」をファイルとして固定することで、再現性と引き継ぎやすさが一気に上がります。

おすすめしたい発展テクニック

ここからは、構成にさらに価値を足せる関連テクニックをいくつか紹介します。

第一に、Webhookによる完全非同期化です。
ポーリングはシンプルですが、生成に数分かかる重いモデルでは効率が悪くなります。
Replicateは予測作成時にwebhookURLを指定でき、生成完了時にそのURLへPOSTを飛ばしてくれます。

webhook_events_filterを["start", "completed"]にすれば、完了通知だけ受け取れます。
ローカルでこれを受けるにはエンドポイントの用意が必要なのでやや上級者向けですが、大量生成のパイプラインを組むなら検討に値します。

第二に、バッチ生成とプロンプトの構造化です。
Claude Codeに「このリストのプロンプトを順に全部生成して」と渡せば、配列をループして連続生成・連続保存ができます。
プロンプトをJSONやCSVで管理し、それをClaudeに読ませる形にすると、サムネイル20枚を一晩で作るといった用途にそのまま乗ります。

第三に、前回の記事で触れたRoutinesとの連携です。
Routines(クラウドで定期実行されるClaude Codeの自動化機能)と組み合わせれば、「毎朝決まったテーマのアイキャッチ画像を自動生成しておく」といった完全無人運用も視野に入ります。
ただしRoutinesはクラウド環境で動くため、ローカルのMacフォルダには保存できません。
生成物はクラウドストレージやリポジトリへcoミットする設計に切り替える必要がある点だけ留意してください。

第四に、コスト管理です。
Replicateは実行時間(GPU秒)に応じた従量課金です。
終了した予測レスポンスにはmetrics.predict_timeという実行時間が含まれるので、Claudeにこれを生成ログとして記録させておくと、後からコストの当たりがつけられます。
また、create predictionは毎分600リクエストというレート制限があるため、大量バッチでは適度な間隔を空ける設計が安全です。

1分間に600リクエストの処理が必要なプロジェクトの場合は、RunpodでGPUレンタルするほうが効率的ですし経済的でしょう。

まとめ

整理すると、この仕組みの本質は「人間は何を作るかを決め、Claude Codeが取得・保存・整理の手間を引き受ける」という役割分担にあります。
組み立てる順序としては、まずトークンを環境変数として安全に格納し、次にPrefer: waitヘッダーを使った同期リクエストで一枚生成してみて、保存まで通ったらカスタムコマンドやCLAUDE.mdに手順を固定する、という流れが無理がありません。

最初の一枚が指定フォルダに落ちてきた瞬間の手応えはなかなかのものです。
そこまで来れば、あとはプロンプトを変えるだけで、コンテンツ制作の最も面倒な部分が静かに自動化されていきます。

«