CheaperGen/skills

Cheaper Gen. API

一個適用於官方影片與圖片模型的非同步 REST API。計費方式使用預付美元餘額：按影片秒數或圖片數量付費，失敗的生成會自動退款。

• Base 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（阿里巴巴）、MiniMax H3 / H3 Max。
   • 圖片：Seedream 5.0 Pro / Lite / Flash（文字轉圖片與 edit）。
   • 端點 ID 格式為 {vendor}/{model}/{mode}，例如 bytedance/seedance-2.0-fast/text-to-video、bytedance/seedream-5.0-lite/text-to-image。
2. 讀取輸入結構：GET /models/{vendor}/{model}（公開）會回傳 endpoints[].input_schema（含列舉、預設值與限制的 JSON Schema）與 pricing.tiers。僅傳送結構中的欄位：未知欄位會回傳 400 錯誤。
3. 報價：POST /quote/{endpoint} 並附上輸入（公開、免費）會回傳 { amount_usd, list_usd, discount_pct, available }。在進行昂貴的工作（1080p/4K 影片、長時間、批次）前，告知使用者價格。
4. 提交：POST /run/{endpoint} 並將輸入作為 JSON 主體，會回傳 202 以及狀態為 "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  # transient: keep polling
        r.raise_for_status()
        gen = r.json()
    if gen["status"] != "succeeded":
        raise RuntimeError(gen["error"])  # the hold was refunded
    return gen  # gen["output"]["video"]["url"] or gen["output"]["images"][0]["url"]

模式與輸入

• text-to-video 與 text-to-image：接受 prompt 加上選項（resolution、duration、aspect_ratio、size、seed、generate_audio…）。請查閱每個模型的結構以了解列舉。
• 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-based 位置指向它們：@Image1、@Image2、@Video1、@Audio1（不區分大小寫）。提及了沒有對應參考的項目會回傳 400 與 param: "prompt"。範例："@Image1 walks through the market from @Image2, camera moves like @Video1"。
  • 結構中的 reference_rules 會設定檔案的最大數量，以及是否需要至少一張圖片或一個影片（僅音訊對於 Seedance 與 H3 來說是不夠的）。
  • 參考影片與音訊會針對 media_limits / x-media-limits 在伺服器上進行測量（持續時間、大小、解析度、fps）。Seedance 2.0 接受每個長度 2–15 秒且總長度 15 秒的 MP4/MOV 影片；音訊必須是 MP3/WAV。違規會回傳 400 並指出檔案名稱，例如 @Video2 is 16 s long…。
  • 參考影片秒數會與輸出秒數一起計費。參考圖片與音訊則免費。若要報價，請傳遞 reference_video_durations： [6.5]（每個片段的秒數）。
• 媒體輸入必須是公開的 https URL。對於本地檔案，請呼叫 POST /uploads 並傳遞 JSON { "filename", "content_type", "size" }。它會回傳 { upload_url, headers, url }：將位元組 PUT 到 upload_url，並使用完全相同的 headers，然後使用 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> } POST 到 webhook_url，並帶上標頭 CheaperGen-Signature: t=<unix>,v1=<hex>。若要驗證它，請使用帳戶的 webhook 簽章密鑰（whsec_…，在儀表板 → API 金鑰中）計算 hex(HMAC_SHA256(secret, "<t>.<raw body>"))，以常數時間進行比較，並拒絕 t 超過 5 分鐘的請求。使用原始請求主體，而非重新序列化的 JSON。快速回傳 2xx；傳遞失敗會重試（總共 3 次嘗試）。

定價與計費

• 價格按輸出影片的每秒或每張圖片計算。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 中命名的欄位（檢查結構、列舉、限制與提及）。未修改請勿重試。
401	unauthorized	缺少、無效或已撤銷的金鑰。
402	insufficient_balance	使用 add_credits（MCP）取得付款連結，並要求使用者付款，或選擇較便宜的層級。
404	not_found	錯誤的端點或生成 ID。
409	conflict	例如取消已開始的工作。
429	rate_limited	退避並重試。限制約為每次突發 20 個請求，每個金鑰以每秒 10 個的速度補充，加上每個帳戶的並行生成上限（預設 20）。
502	upstream_error	重試一次，然後嘗試其他模型。
503	model_unavailable	稍後重試或切換模型。

結束狀態為 failed 的生成會有 error.code（例如 generation_failed、timeout）並已退款。最多以相同輸入重試一次。

更多資訊

• 文件：https://cheapergen.com/docs，MCP 設定：https://cheapergen.com/docs/mcp
• 此技能與 Claude Code 外掛的原始碼：https://github.com/CheaperGen/skills
• 各模型 API 頁面：https://cheapergen.com/models/{vendor}/{model}/api
• 機器可讀摘要：https://cheapergen.com/llms.txt