CheaperGen/skills

Cheaper Gen. API

公式動画・画像モデルを一つの非同期REST APIで提供します。課金はプリペイドUSD残高から行われ、動画は秒単位、画像は枚単位で課金され、失敗した生成は自動的に返金されます。

• ベースURL: https://cheapergen.com/api/v1
• 認証: Authorization: Bearer $CHEAPERGEN_API_KEY（キーは cg_live_ で始まります。https://cheapergen.com/dashboard/keys で作成）。キーは環境変数から読み取り、決して出力・ログ記録・コミットしないでください。
• MCP サーバーが接続されている場合はそちらを優先してください。 そのツールは list_models, get_model, quote, generate（wait_seconds と max_cost_usd 予算ガード付き）, get_generation, get_account, add_credits（残高不足時にユーザーが開く支払いリンク）です。HTTP 呼び出しの代わりにこれらを使用してください。以下のワークフローは同じです。接続するには、リモートサーバー https://cheapergen.com/api/mcp を追加します。ユーザーがブラウザでサインインして承認します（OAuth、キー不要）。Claude Code では: claude mcp add --transport http cheapergen https://cheapergen.com/api/mcp、その後 /mcp → 認証。完全なセットアップ: https://cheapergen.com/docs/mcp

ワークフロー

1. モデルを選ぶ: GET /models（公開）。各モデルの endpoints[].id と価格帯を返します。モデルは変更されるため、常に最新のリストを使用してください。
   • 動画: Seedance 2.0（最高品質、4K、音声同期）、Seedance 2.0 Fast / Mini（より安く高速）、Seedance 2.5（最新、最長の参照）、Wan 3.0 / Prime（Alibaba）、MiniMax H3 / H3 Max。
   • 画像: Seedream 5.0 Pro / Lite / Flash（テキスト→画像と edit）。
   • エンドポイントIDは {ベンダー}/{モデル}/{モード} の形式です。例: bytedance/seedance-2.0-fast/text-to-video, bytedance/seedream-5.0-lite/text-to-image。
2. 入力スキーマを読む: GET /models/{ベンダー}/{モデル}（公開）は endpoints[].input_schema（JSON Schema、enum、デフォルト、制限を含む）と pricing.tiers を返します。スキーマに記載されたフィールドのみを送信してください。未知のフィールドは400で拒否されます。
3. 見積もり: 入力を指定して POST /quote/{エンドポイント}（公開、無料）は { amount_usd, list_usd, discount_pct, available } を返します。高額なジョブ（1080p/4K動画、長時間、バッチ）の前にはユーザーに価格を伝えてください。
4. 投入: 入力をJSON本文として POST /run/{エンドポイント} は 202 と status: "queued" の生成を返します。この時点で残高から価格が保留されます。
5. 待機: GET /generations/{id} を status が succeeded, failed, canceled になるまでポーリングします。画像は1～2秒ごと、動画は3～5秒ごと（10秒までバックオフ）にポーリングします。5秒の動画クリップは通常1～3分かかります。または webhook_url を渡します（下記参照）。
6. 出力を利用: output.video.url（動画）または output.images[].url（画像）。URL は公開ですがアカウントの保持期間に従って期限切れになります（デフォルト1日、expires_at で確認）。価値のあるものはダウンロードしておいてください。

curl -s https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/text-to-video \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"A paper boat drifting down a rainy neon street, slow dolly-in","resolution":"720p","duration":5,"aspect_ratio":"16:9"}'
# → 202 {"id":"gen_…","status":"queued","cost":{"amount_usd":…,"estimated":true},…}
curl -s https://cheapergen.com/api/v1/generations/gen_… -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

import os, time, requests
API = "https://cheapergen.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['CHEAPERGEN_API_KEY']}"}

def generate(endpoint: str, inp: dict, timeout_s: int = 900) -> dict:
    r = requests.post(f"{API}/run/{endpoint}", json=inp, headers=H, timeout=60)
    r.raise_for_status()  # 4xx bodies: {"error": {"code", "message", "param"}}
    gen, delay, start = r.json(), 2.0, time.time()
    while gen["status"] in ("queued", "running"):
        if time.time() - start > timeout_s:
            raise TimeoutError(gen["id"])
        time.sleep(delay)
        delay = min(delay * 1.5, 10)
        r = requests.get(f"{API}/generations/{gen['id']}", headers=H, timeout=30)
        if r.status_code == 429 or r.status_code >= 500:
            continue  # 一時的: ポーリング継続
        r.raise_for_status()
        gen = r.json()
    if gen["status"] != "succeeded":
        raise RuntimeError(gen["error"])  # 保留は返金されました
    return gen  # gen["output"]["video"]["url"] または gen["output"]["images"][0]["url"]

モードと入力

• text-to-video および text-to-image: prompt とオプション（resolution, duration, aspect_ratio, size, seed, generate_audio…）を受け取ります。各モデルのenumはスキーマで確認してください。
• image-to-video: image_url（最初のフレーム）と、一部モデルでは end_image_url（最後のフレーム）を受け取ります。
• edit（Seedream）: image_urls（編集または合成する画像。「image 1」「image 2」のようにプロンプトで参照）と、prompt 内の指示を受け取ります。
• reference-to-video: reference_image_urls, reference_video_urls, reference_audio_urls を受け取ります。プロンプトでは1から始まる位置で参照します: @Image1, @Image2, @Video1, @Audio1（大文字小文字を区別しません）。対応する参照がないメンションは param: "prompt" の400エラーになります。例: "@Image1 walks through the market from @Image2, camera moves like @Video1"。
  • スキーマ内の reference_rules でファイルの最大数と、少なくとも1つの画像または動画が必要かどうかが設定されます（Seedance と H3 では音声のみでは不十分です）。
  • 参照動画と音声はサーバー側で（時間、サイズ、解像度、fps）が media_limits / x-media-limits に照らして測定されます。Seedance 2.0 は各2～15秒、合計15秒までのMP4/MOV動画を受け付けます。音声はMP3/WAVである必要があります。違反があると、ファイル名を指定した400エラーが返されます。例: @Video2 is 16 s long…。
  • 参照動画の秒数は出力秒数と一緒に課金されます。参照画像と音声は無料です。見積もりには reference_video_durations: [6.5]（クリップごとの秒数）を渡します。
• メディア入力は公開 https URL である必要があります。ローカルファイルの場合は、JSON { "filename", "content_type", "size" } で POST /uploads を呼び出します。これにより { upload_url, headers, url } が返されます。upload_url に指定された headers をそのまま使ってバイト列を PUT し、url を入力として使用します。制限: 画像（PNG/JPEG/WebP/GIF）20 MB以下、動画（MP4/MOV）50 MB以下、音声（MP3/WAV/M4A）15 MB以下。
• 各実行でオプション: webhook_url（HTTPS）と retention（immediate | 1h | 1d; 7d / 30d はアカウント設定が必要）。

Webhook

ジョブが完了したとき（成功または失敗）、{ "type": "generation.succeeded" | "generation.failed", "data": <generation> } を webhook_url に CheaperGen-Signature: t=<unix>,v1=<hex> ヘッダー付きで POST します。検証するには、アカウントの Webhook 署名シークレット（whsec_…、ダッシュボード → API キーで確認）を使って hex(HMAC_SHA256(secret, "<t>.<raw body>")) を計算し、定数時間で比較し、t が5分以上経過したリクエストは拒否します。生のリクエストボディを使用し、再シリアライズした JSON は使用しないでください。迅速に 2xx を返します。配信に失敗した場合は再試行されます（合計3回）。

料金と課金

• 料金は出力動画の秒数または画像1枚あたりです。GET /models は各階層の price_usd と list_price_usd（公式価格）を表示します。
• 投入時に、見積もり価格が保留されます（cost.estimated: true）。成功すると確定し、失敗またはキャンセルすると全額返金されます（cost.amount_usd: 0）。cost.official_usd と cost.saved_usd で節約額が分かります。
• 残高: GET /account は balance_usd と reserved_usd（進行中のジョブのために保留中）を返します。402 は残高不足を意味します。MCP 経由の場合は add_credits を呼び出し、ユーザーに支払いリンクを表示します。それ以外の場合は、ユーザーが https://cheapergen.com/dashboard/billing でクレジットを追加します。
• キューに入ったジョブをキャンセルするには POST /generations/{id}/cancel（実行中は409）。完了したジョブを削除するには DELETE /generations/{id}。

エラー

すべてのエラーは { "error": { "code", "message", "param"? } } の形をとります。

HTTP	code	対処法
400	invalid_request	param で指定されたフィールドを修正（スキーマ、enum、制限、メンションを確認）。変更せずに再試行しない。
401	unauthorized	キーがない、無効、または取り消された。
402	insufficient_balance	add_credits（MCP）で支払いリンクを取得してユーザーに支払いを依頼するか、より安い階層を選択する。
404	not_found	エンドポイントまたは生成IDが間違っている。
409	conflict	例: すでに開始したジョブのキャンセル。
429	rate_limited	バックオフして再試行。制限はバースト約20リクエスト、キーあたり毎秒10リクエストで補充、アカウントあたりの同時生成数の上限あり（デフォルト20）。
502	upstream_error	1回再試行し、それでもダメなら別のモデルを試す。
503	model_unavailable	後で再試行するか、モデルを切り替える。

failed で終了した生成には error.code（例: generation_failed, timeout）があり、返金されています。同じ入力で最大1回再試行します。

その他

• ドキュメント: https://cheapergen.com/docs, MCP セットアップ: https://cheapergen.com/docs/mcp
• このスキルと Claude Code プラグインのソース: https://github.com/CheaperGen/skills
• モデル別 API ページ: https://cheapergen.com/models/{ベンダー}/{モデル}/api
• 機械可読サマリー: https://cheapergen.com/llms.txt