runpod

RunPod クラウド GPU

RunPod serverless を使って、オープンソースの AI モデルをクラウド GPU で実行します。秒単位の課金で、最低利用料金はありません。

セットアップ

# 1. Create account at https://runpod.io
# 2. Add API key to .env
echo "RUNPOD_API_KEY=your_key_here" >> .env

# 3. Deploy any tool with --setup
uv run tools/image_edit.py --setup
uv run tools/upscale.py --setup
uv run tools/dewatermark.py --setup
uv run tools/sadtalker.py --setup
uv run tools/qwen3_tts.py --setup

各 --setup コマンドは、次の処理を行います。

1. Docker イメージから RunPod のテンプレートを作成します
2. 適切な GPU を備えた serverless エンドポイントを作成します
3. エンドポイント ID を .env に保存します（例：RUNPOD_QWEN_EDIT_ENDPOINT_ID）

利用可能なイメージ

すべてのイメージは GHCR で公開されているため、認証は不要です。

ツール	Docker イメージ	GPU	VRAM	一般的なコスト
image_edit	ghcr.io/conalmullan/video-toolkit-qwen-edit:latest	A6000/L40S	48GB+	約$0.05-0.15/ジョブ
upscale	ghcr.io/conalmullan/video-toolkit-realesrgan:latest	RTX 3090/4090	24GB	約$0.01-0.05/ジョブ
dewatermark	ghcr.io/conalmullan/video-toolkit-propainter:latest	RTX 3090/4090	24GB	約$0.05-0.30/ジョブ
sadtalker	ghcr.io/conalmullan/video-toolkit-sadtalker:latest	RTX 4090	24GB	約$0.05-0.15/ジョブ
qwen3_tts	ghcr.io/conalmullan/video-toolkit-qwen3-tts:latest	ADA 24GB	24GB	約$0.01-0.05/ジョブ

月間合計コスト： 頻繁に使用しても、10ドルを超えることはほとんどありません。

仕組み

すべてのツールは同じパターンに従います。

Local CLI → Upload input to cloud storage → RunPod API → Poll for result → Download output

1. ファイル転送： Cloudflare R2 が設定されている場合（R2_ACCOUNT_ID、R2_ACCESS_KEY_ID、R2_SECRET_ACCESS_KEY、R2_BUCKET_NAME）、ツールは Cloudflare R2 を使用し、設定されていない場合は無料のアップロードサービスにフォールバックします
2. RunPod API： ツールは /run エンドポイントを呼び出した後、完了するまで /status/{job_id} をポーリングします
3. コールドスタートとウォームスタート： アイドル状態の後に最初のリクエストを受けると、ワーカーが起動します（約30～90秒）。その後のリクエストは高速です（約5～15秒）

エンドポイント管理

ワーカー

workersMin: 0    — Scale to zero when idle (no cost)
workersMax: 1    — Max concurrent jobs (increase for throughput)
idleTimeout: 5   — Seconds before worker scales down

すべてのエンドポイントで、RunPod プランに応じた合計ワーカープールを共有します。上限に達した場合は、現在使用していないエンドポイントの workersMax を減らしてください。

エンドポイントの状態を確認する

各ツールはエンドポイント ID を .env に保存します。

ツール	環境変数
image_edit	RUNPOD_QWEN_EDIT_ENDPOINT_ID
upscale	RUNPOD_UPSCALE_ENDPOINT_ID
dewatermark	RUNPOD_DEWATERMARK_ENDPOINT_ID
sadtalker	RUNPOD_SADTALKER_ENDPOINT_ID
qwen3_tts	RUNPOD_QWEN3_TTS_ENDPOINT_ID

エンドポイントを無効にする

エンドポイントを削除せずにワーカースロットを解放するには、RunPod ダッシュボードまたは GraphQL API から workersMax=0 に設定します。

RunPod API リファレンス

エンドポイントをプログラムから照会・管理するには、次の API を使用します。RunPod は GraphQL のイントロスペクションを無効にしているため、以下のフィールド名は検証済みであり、正確に指定する必要があります。

認証

すべての API 呼び出しで Authorization: Bearer $RUNPOD_API_KEY が必要です。

• GraphQL： POST https://api.runpod.io/graphql
• REST（Serverless）： https://api.runpod.ai/v2/{endpoint_id}/...

GraphQL クエリ

すべてのエンドポイントを一覧表示：

query { myself { endpoints { id name gpuIds templateId workersMax workersMin } } }

現在の支出率：

query { myself { currentSpendPerHr spendDetails { localStoragePerHour networkStoragePerHour gpuComputePerHour } } }

Pod を一覧表示：

query { myself { pods { id name runtime { uptimeInSeconds } machine { gpuDisplayName } desiredStatus } } }

よくある間違い： フィールド名は完全な単語を使った camelCase です。localStoragePerHr ではなく localStoragePerHour を使用してください。エンドポイントは serverlessWorkers ではなく endpoints です。spending はフィールドではありません。currentSpendPerHr と spendDetails を使用してください。

GraphQL Mutation

エンドポイントの GPU または設定を更新：

mutation { saveEndpoint(input: {
  id: "endpoint_id",
  name: "endpoint-name",
  templateId: "template_id",
  gpuIds: "AMPERE_24",
  workersMin: 0,
  workersMax: 1
}) { id gpuIds } }

更新の場合でも saveEndpoint には name と templateId が必要です。まずクエリを実行して現在の値を取得してください。

REST API（Serverless）

操作	メソッド	URL
ジョブを送信	POST	/v2/{id}/run
状態を確認	GET	/v2/{id}/status/{job_id}
ジョブをキャンセル	POST	/v2/{id}/cancel/{job_id}
保留中のジョブを一覧表示	GET	/v2/{id}/requests
ヘルス／統計情報	GET	/v2/{id}/health

ヘルスレスポンスには、ジョブ数とワーカーの状態が含まれます。

{
  "jobs": { "completed": 16, "failed": 1, "inProgress": 0, "inQueue": 2, "retried": 0 },
  "workers": { "idle": 0, "initializing": 1, "ready": 0, "running": 0, "throttled": 0 }
}

注： /requests が返すのは保留中またはキューに入っているジョブのみです。完了したジョブの履歴は API から取得できません。ログは RunPod のウェブコンソールで確認してください。

GPU タイプ ID

ID	GPU	VRAM	一般的な料金
AMPERE_24	RTX 3090	24GB	約$0.34/時
ADA_24	RTX 4090	24GB	約$0.69/時
AMPERE_48	A6000	48GB	約$0.76/時
AMPERE_80	A100	80GB	約$1.99/時

利用可能状況に関する注意： RunPod では ADA_24（4090）が頻繁にスロットリングされたり、利用できなくなったりします。ジョブがキューにいつまでも滞留しないよう、エンドポイントには常に複数のフォールバック GPU タイプ（カンマ区切り）を設定してください。

gpuIds: "AMPERE_24,ADA_24"   # Try 3090 first, fall back to 4090

すべてのツールキットツールでは、5 分のキュータイムアウトも適用されます。300 秒以内に GPU を利用できない場合、初期化の失敗が繰り返されて課金が続くのを防ぐため、ジョブは自動的にキャンセルされます。

AWS CLI 経由での Cloudflare R2

R2 は S3 互換 API を使用しますが、--region auto が必要です。

AWS_ACCESS_KEY_ID="$R2_ACCESS_KEY_ID" \
AWS_SECRET_ACCESS_KEY="$R2_SECRET_ACCESS_KEY" \
aws s3api list-objects-v2 \
  --bucket "$R2_BUCKET_NAME" \
  --endpoint-url "https://${R2_ACCOUNT_ID}.r2.cloudflarestorage.com" \
  --region auto

よくある間違い： --region auto を省略すると、InvalidRegionName エラーが発生します。R2 の有効なリージョン：wnam、enam、weur、eeur、apac、oc、auto。

トラブルシューティング

イメージの強制プル

新しい Docker イメージのバージョンをプッシュしても、RunPod がキャッシュされた古いイメージを使用する場合があります。強制的にプルするには：

1. テンプレートの imageName を更新し、@sha256:DIGEST 表記を使用します
2. ワーカーが再起動するまで待ちます
3. 確認後、:latest タグに戻します

コールドスタートが遅すぎる

• qwen3-tts： コールドスタート約70秒、ウォームスタート約7秒
• sadtalker： コールドスタート約60秒、ウォームスタート約10秒
• image_edit： コールドスタート約90秒、ウォームスタート約15秒

コールドスタートが問題になる場合は、workersMin: 1 を設定してください（アイドル時も料金が発生します）。

OOM によるジョブの失敗

モデルが GPU の搭載 VRAM より多くの VRAM を必要としています。次の方法があります。

• より大容量の GPU ティアを使用する
• dewatermark の場合：--resize-ratio を小さくする（安全のため、デフォルトは 0.5）
• image_edit の場合：--steps を小さくする

「利用可能なワーカーがありません」

プランの同時実行ワーカー上限に達しています。次のいずれかを実行してください。

• 実行中のジョブが完了するまで待つ
• 使用していないエンドポイントで workersMax=0 を設定する
• RunPod のプランをアップグレードする

Docker イメージ

すべての Dockerfile は docker/runpod-*/ にあります。各ツール間でレイヤーを共有するため、イメージはベースに runpod/pytorch を使用します。

RunPod 向けのビルド（Apple Silicon Mac から）：

docker buildx build --platform linux/amd64 -t ghcr.io/conalmullan/video-toolkit-<name>:latest docker/runpod-<name>/
docker push ghcr.io/conalmullan/video-toolkit-<name>:latest

GHCR のパッケージはデフォルトで非公開です。RunPod がプルできるように、手動で公開する必要があります。GitHub > Packages > Package Settings > Change Visibility に移動してください。

コストの最適化

• すべてのエンドポイントで workersMin: 0 を維持する（ゼロまでスケールダウン）
• 実際に必要なエンドポイントのみデプロイする
• 削除せずにアイドル状態のエンドポイントを無効にするには、workersMax=0 を使用する
• 音声のナレーションには、Qwen3-TTS の方が ElevenLabs より大幅に低コストです
• RunPod ダッシュボードで使用状況と請求を確認する