CheaperGen/skills

Cheaper Gen. API

一个用于官方视频和图像模型的异步 REST API。计费基于预付费美元余额：按视频秒数或图像数量付费，失败的生成会自动退款。

• 基础 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 和一个 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  # 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（要编辑或组合的图像；在提示中引用为“图像 1”、“图像 2”）加上 prompt 中的指令。
• reference-to-video：接受 reference_image_urls、reference_video_urls 和 reference_audio_urls。在提示中，按基于 1 的位置指向它们：@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 秒的 MP4/MOV 视频，总时长为 15 秒；音频必须是 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 需要账户设置）。

Webhooks

当任务完成（成功或失败）时，我们向 webhook_url 发送 POST 请求，内容为 { "type": "generation.succeeded" | "generation.failed", "data": <generation> }，并附带标头 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