API 参考 — 端点与对象

API 参考文档

REST API 参考：提交、轮询和取消生成任务；列出模型和价格、查询报价、读取余额，以及上传图像、视频和音频，并附带示例。

API 围绕几种资源构建：generations（你提交的任务）、models（可运行的模型及其价格）、quotes、你的 account 和 uploads。所有请求和响应均通过 HTTPS 以 JSON 格式传输。

基础 URLhttps://cheapergen.com/api/v1

使用 Authorization: Bearer cg_live_… 进行身份验证（参见身份验证）。错误格式请参阅错误。所有端点都会发送 CORS 标头；但切勿在浏览器中暴露密钥，只有公开端点适合从客户端调用。

API 端点
端点	说明
POST/run/{endpoint}	提交生成任务
GET/generations/{id}	获取生成任务
GET/generations	列出生成任务
POST/generations/{id}/cancel	取消排队中的生成任务
DELETE/generations/{id}	删除生成任务及其媒体文件
GET/models	列出模型和价格
GET/models/{vendor}/{model}	获取模型及输入结构
POST/quote/{endpoint}	查询输入价格
GET/account	余额、图片额度和自动充值
GET/account/pricing	你的套餐与专属价格
POST/uploads	上传输入图像、视频或音频文件
GET/webhooks/secret	你的 Webhook 签名密钥

提交生成任务#

POST/api/v1/run/{endpoint}需要 API 密钥

启动异步生成并返回 202 Accepted，其中包含状态为 queued 的生成任务对象。此时会从余额中冻结对应金额（参见计费）。

路径参数

endpointstring必填: 模型端点 ID 为 {vendor}/{model}/{task}，例如 bytedance/seedance-2.0-fast/text-to-video。所有 ID 均列在模型页面上。

请求正文

…model inputsobject必填: 端点的输入字段，例如 prompt、resolution 或 image_url。每个模型的字段、类型、默认值和允许值均记录在对应 API 页面上，并由获取模型以 JSON Schema 格式返回。未知字段会被拒绝。
webhook_urlstring (https URL): 可选。生成完成后，我们会将结果 POST 到此 URL。参见 Webhooks。
retentionstring: 可选。提示词、输入和输出保留期限：immediate、1h、1d、7d 或 30d。默认使用账户设置（1d）。所有账户都可以缩短期限；7d 和 30d 需要企业级数据保留设置。参见数据保留。
allow_fallback_priceboolean: 可选，默认为 true。当此请求通常使用的容量不可用时，可改用价格更高的容量，并按 应急价格 价格计费——最高不超过该模型的官方价格，也绝不高于 max_cost_usd。请求提交时此规则即适用（价格会显示在响应和 /quote 中）；如果任务已被接受、之后容量才发生故障，后续切换也适用（届时会暂时冻结额外金额；pricing.fallback 和 Webhook 会说明这一点）。将 false 设为相应值，可确保支付金额不超过已报价价格（在 Pro 或 Max 套餐下，已接受的任务否则也可能切换，最高按标准价格计费）：此时你会收到 503 fallback_price_declined，而不是支付更高价格；或者任务会失败并退款。
max_cost_usdnumber: 可选。你同意为此生成任务支付的最高金额，包括应急价格。若价格超出上限，将返回 400 max_cost_exceeded，且不会扣款；任务之后也不会以高于此上限的价格切换算力。

const resp = await fetch("https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/text-to-video", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CHEAPERGEN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "prompt": "黄金时刻，陶艺家缓缓将陶土塑成花瓶，光线中尘埃浮动，浅景深，镜头缓慢推进",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5
  }),
});
const generation = await resp.json();

import os, requests

resp = requests.post(
    "https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/text-to-video",
    headers={"Authorization": f"Bearer {os.environ['CHEAPERGEN_API_KEY']}"},
    json={
        "prompt": "黄金时刻，陶艺家缓缓将陶土塑成花瓶，光线中尘埃浮动，浅景深，镜头缓慢推进",
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "duration": 5
    },
)
generation = resp.json()

curl -X POST 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": "黄金时刻，陶艺家缓缓将陶土塑成花瓶，光线中尘埃浮动，浅景深，镜头缓慢推进",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}'

响应 · 202 Accepted

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "object": "generation",
  "model": "bytedance/seedance-2.0-fast",
  "endpoint": "bytedance/seedance-2.0-fast/text-to-video",
  "mode": "text-to-video",
  "status": "queued",
  "input": {
    "prompt": "黄金时刻，陶艺家缓缓将陶土塑成花瓶，光线中尘埃浮动，浅景深，镜头缓慢推进",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
  },
  "output": null,
  "error": null,
  "cost": {
    "amount_usd": 0.4494,
    "currency": "usd",
    "estimated": true
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04.512Z",
  "started_at": null,
  "completed_at": null,
  "retention": "1d",
  "expires_at": null,
  "purged_at": null,
  "urls": {
    "get": "https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z",
    "cancel": "https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z/cancel"
  }
}

错误：400 invalid_request（验证错误）、401 unauthorized、402 insufficient_balance、404 not_found（未知端点）、429 rate_limited（请求速率，或等待中的生成队列已满）、503 model_unavailable、503 pricing_unavailable（请几秒后重试；未收费）、503 fallback_price_declined（仅有应急价格可用，而你提交了 allow_fallback_price: false）、400 max_cost_exceeded。

获取生成任务#

GET/api/v1/generations/{id}需要 API 密钥

按 ID 返回生成任务。如果到了状态检查时间，系统会在响应前先进行检查，因此持续轮询此端点即可跟踪任务直至完成。未知 ID 或属于其他账户的生成任务会返回 404 not_found。

请求

curl https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

响应 · 200 OK

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "object": "generation",
  "model": "bytedance/seedance-2.0-fast",
  "endpoint": "bytedance/seedance-2.0-fast/text-to-video",
  "mode": "text-to-video",
  "status": "succeeded",
  "input": {
    "prompt": "黄金时刻，陶艺家缓缓将陶土塑成花瓶，光线中尘埃浮动，浅景深，镜头缓慢推进",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
  },
  "output": {
    "video": {
      "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.mp4",
      "content_type": "video/mp4"
    }
  },
  "error": null,
  "cost": {
    "amount_usd": 0.4494,
    "currency": "usd",
    "estimated": false
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04.512Z",
  "started_at": "2026-10-15T09:21:09.031Z",
  "completed_at": "2026-10-15T09:22:31.870Z",
  "retention": "1d",
  "expires_at": "2026-10-16T09:22:31.870Z",
  "purged_at": null
}

列出生成任务#

GET/api/v1/generations需要 API 密钥

按时间倒序列出你的生成任务，包括从 Studio 和 Playground 提交的任务。

查询参数

limitinteger: 每页数量，范围为 1–100。默认值为 20。
cursorstring: 上一页的 next_cursor。
statusstring: 仅返回状态为 queued、running、succeeded、failed 或 canceled 的生成任务。
modelstring: 仅返回此模型 ID 对应的生成任务，例如 bytedance/seedance-2.0-fast。
sourcestring: 仅返回由 playground（Studio 和模型页面）、api 或 mcp（AI 智能体）发起的生成任务。

请求

curl "https://cheapergen.com/api/v1/generations?limit=2&status=succeeded" \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

响应 · 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "gen_8c2QmX1nq0k4Lw7Z",
      "object": "generation",
      "model": "bytedance/seedance-2.0-fast",
      "endpoint": "bytedance/seedance-2.0-fast/text-to-video",
      "mode": "text-to-video",
      "status": "succeeded",
      "input": {
        "prompt": "黄金时刻，陶艺家缓缓将陶土塑成花瓶，光线中尘埃浮动，浅景深，镜头缓慢推进",
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "duration": 5,
        "generate_audio": true
      },
      "output": {
        "video": {
          "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.mp4",
          "content_type": "video/mp4"
        }
      },
      "error": null,
      "cost": {
        "amount_usd": 0.4494,
        "currency": "usd",
        "estimated": false
      },
      "source": "api",
      "created_at": "2026-10-15T09:21:04.512Z",
      "started_at": "2026-10-15T09:21:09.031Z",
      "completed_at": "2026-10-15T09:22:31.870Z",
      "retention": "1d",
      "expires_at": "2026-10-16T09:22:31.870Z",
      "purged_at": null
    },
    {
      "id": "gen_3vYk2PqL9sTn0bWd",
      "object": "generation",
      "model": "bytedance/seedream-5.0-pro",
      "endpoint": "bytedance/seedream-5.0-pro/text-to-image",
      "mode": "text-to-image",
      "status": "succeeded",
      "input": {
        "prompt": "产品摄影：洞石台面上的哑光黑色意式咖啡机，柔和窗光，85 毫米镜头",
        "aspect_ratio": "1:1",
        "size": "2K"
      },
      "output": {
        "images": [
          {
            "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.png",
            "content_type": "image/png"
          }
        ]
      },
      "error": null,
      "cost": {
        "amount_usd": 0.0665,
        "currency": "usd",
        "estimated": false
      },
      "source": "api",
      "created_at": "2026-10-15T09:21:04.512Z",
      "started_at": "2026-10-15T09:21:09.031Z",
      "completed_at": "2026-10-15T09:22:31.870Z",
      "retention": "1d",
      "expires_at": "2026-10-16T09:22:31.870Z",
      "purged_at": null
    }
  ],
  "next_cursor": "gen_3vYk2PqL9sTn0bWd"
}

next_cursor 为 null，当前已到最后一页。

取消生成任务#

POST/api/v1/generations/{id}/cancel需要 API 密钥

取消仍处于 queued 状态的生成任务，并全额退还冻结金额。返回更新后的生成任务，其中包含 status: "canceled"。如果任务已开始运行或完成，或者模型不支持取消排队中的任务，则返回 409 conflict。

请求

curl -X POST https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z/cancel \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

响应 · 200 OK

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "object": "generation",
  "model": "bytedance/seedance-2.0-fast",
  "endpoint": "bytedance/seedance-2.0-fast/text-to-video",
  "mode": "text-to-video",
  "status": "canceled",
  "input": {
    "prompt": "黄金时刻，陶艺家缓缓将陶土塑成花瓶，光线中尘埃浮动，浅景深，镜头缓慢推进",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
  },
  "output": null,
  "error": null,
  "cost": {
    "amount_usd": 0,
    "currency": "usd",
    "estimated": false
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04.512Z",
  "started_at": null,
  "completed_at": "2026-10-15T09:21:06.200Z",
  "retention": "1d",
  "expires_at": "2026-10-16T09:21:06.200Z",
  "purged_at": null
}

删除生成任务#

DELETE/api/v1/generations/{id}需要 API 密钥

删除生成任务：立即移除输出文件、其他生成任务未使用的已上传输入、提示词和输入内容；该任务也不会再出现在列表中；GET 返回 404。计费记录（账本中的扣款和用量统计）会保留。仍处于 queued 状态的任务会先被取消，冻结的费用全额退还；如果已经无法取消（正在运行，或该模型不支持取消排队中的任务），返回 409 conflict——请等待其完成后再删除。

请求

curl -X DELETE https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

响应 · 200 OK

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "object": "generation",
  "deleted": true
}

生成任务对象#

idstring: 唯一 ID，前缀为 gen_。
objectstring: 始终为 "generation"。
modelstring: 模型 ID，例如 bytedance/seedance-2.0-fast。
endpointstring: 提交任务时使用的端点 ID，例如 bytedance/seedance-2.0-fast/text-to-video。
modestring: 任务类型：text-to-video、image-to-video、reference-to-video、text-to-image 或 image-edit。
statusstring: queued → running → succeeded | failed 或 canceled。参见生成任务。
inputobject: The validated input, with defaults filled in.
outputobject | null: 成功时设置。视频：{ "video": { "url", "content_type" } }。图片：{ "images": [{ "url", "content_type" }] }。被安全检查器替换的图片（返回结果为空白）也会标记为 "safety_filtered": true；它与其他输出一样计费。
errorobject | null: 失败时设置：{ "code", "message", "reason", "hint", "retryable", "refunded" }，以及 param（需要更改的字段）和 detail（已知时提供上游错误描述）。reason 会说明原因，例如 content_blocked、invalid_input、upstream_unavailable。参见失败原因。
costobject: amount_usd、currency（"usd"）和 estimated——冻结期间显示 true，最终结算后显示 false。生成失败或取消不会产生费用：0。
pricingobject: custom_price（你的专属价格：合同价或你的 Pro 或 Max 套餐），volume_level（若套餐设定该价格，1 = Pro、2 = Max；否则为 null），standard_usd（此请求的常规费用）和 fallback：null；若按应急价格运行，则为 { "active", "reason", "message", "standard_usd", "amount_usd" }——最高不超过官方价格，由 allow_fallback_price 设定，并受 max_cost_usd 限制。
sourcestring: "api" 或 "playground"（Studio 和模型页面）。
created_atstring: ISO 8601 timestamp of submission.
started_atstring | null: When the model started generating.
completed_atstring | null: When the generation reached a final state.
retentionstring | null: API 生成任务：immediate、1h、1d、7d 或 30d。null 用于 Studio 生成任务；此类任务会一直保留，直到你将其删除。
expires_atstring | null: 内容（提示词、输入、输出和媒体）被删除的时间。生成任务完成时设置。使用 immediate 时，会将删除时间延后至结果首次交付后的 10 分钟。
purged_atstring | null: 内容删除后设置。output 随后为 null；input 只保留决定价格的参数；content_expired 会说明原因。费用和时间戳会保留。
urlsobject: 仅在提交响应中返回：此生成任务的 get 和 cancel URL。

列出模型#

GET/api/v1/models公开 · 无需身份验证

返回所有可用模型、对应端点和实时价格。计价单位为 unit（视频按 second 计算，图像按 image 计算）；list_price_usd 是用于比较的标价，discount_pct 是节省百分比。list_price_source 会注明价格类型：official（开发者自己的标价）或 reference（由 list_price_label 标明的其他参考价格——例如，某个模型的开发者没有面向国际市场销售 API 时使用 fal API）。

请求

curl https://cheapergen.com/api/v1/models

响应 · 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "bytedance/seedance-2.0-fast",
      "object": "model",
      "name": "Seedance 2.0 Fast",
      "vendor": "ByteDance",
      "category": "video",
      "available": true,
      "url": "https://cheapergen.com/models/bytedance/seedance-2.0-fast",
      "endpoints": [
        {
          "id": "bytedance/seedance-2.0-fast/text-to-video",
          "mode": "text-to-video",
          "output": "video"
        },
        {
          "id": "bytedance/seedance-2.0-fast/image-to-video",
          "mode": "image-to-video",
          "output": "video"
        },
        {
          "id": "bytedance/seedance-2.0-fast/reference-to-video",
          "mode": "reference-to-video",
          "output": "video"
        }
      ],
      "pricing": {
        "unit": "second",
        "list_price_source": "official",
        "list_price_label": "Official",
        "tiers": [
          {
            "tier": "480p",
            "price_usd": 0.050086,
            "list_price_usd": 0.056246,
            "discount_pct": 11
          },
          {
            "tier": "720p",
            "price_usd": 0.08988,
            "list_price_usd": 0.12096,
            "discount_pct": 26
          }
        ]
      },
      "deprecation": null,
      "upcoming_price_changes": []
    }
  ]
}

为简洁起见，仅展示一个模型。

获取模型#

GET/api/v1/models/{vendor}/{model}公开 · 无需身份验证

返回单个模型，并为每个端点的输入提供 JSON Schema，便于创建表单或在发送请求前验证输入。未知模型会返回 404 not_found。

请求

curl https://cheapergen.com/api/v1/models/bytedance/seedream-5.0-pro

响应 · 200 OK

{
  "id": "bytedance/seedream-5.0-pro",
  "object": "model",
  "name": "Seedream 5.0 Pro",
  "vendor": "ByteDance",
  "category": "image",
  "available": true,
  "description": "ByteDance Seedream 5.0 Pro 可生成和编辑最高 2K 的照片级品牌图像，支持精准多图编辑和文字渲染。",
  "url": "https://cheapergen.com/models/bytedance/seedream-5.0-pro",
  "endpoints": [
    {
      "id": "bytedance/seedream-5.0-pro/text-to-image",
      "mode": "text-to-image",
      "label": "文生图",
      "output": "image",
      "input_schema": {
        "type": "object",
        "required": [
          "prompt"
        ],
        "properties": {
          "prompt": {
            "title": "提示词",
            "description": "描述镜头，包括主体、动作、镜头运动、光线和风格。",
            "type": "string",
            "maxLength": 5000
          },
          "aspect_ratio": {
            "title": "宽高比",
            "description": "输出图像比例。",
            "type": "string",
            "enum": [
              "1:1",
              "4:3",
              "3:4",
              "16:9",
              "9:16",
              "3:2",
              "2:3",
              "21:9"
            ],
            "default": "1:1"
          },
          "size": {
            "title": "尺寸",
            "description": "1K ≈ 1 百万像素，2K ≈ 4 百万像素。",
            "type": "string",
            "enum": [
              "1K",
              "2K"
            ],
            "default": "2K"
          },
          "seed": {
            "title": "Seed",
            "description": "使用相同的 seed 和设置即可复现结果。留空则随机生成。",
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647
          },
          "webhook_url": {
            "type": "string",
            "format": "uri",
            "title": "Webhook URL",
            "description": "Optional. We POST the finished generation here (signed)."
          }
        },
        "additionalProperties": false
      }
    }
  ],
  "pricing": {
    "unit": "image",
    "notes": [],
    "list_price_source": "official",
    "list_price_label": "Official",
    "tiers": [
      {
        "tier": "1K",
        "detail": "≈1 MP",
        "price_usd": 0.03325,
        "list_price_usd": 0.045,
        "discount_pct": 26
      },
      {
        "tier": "2K",
        "detail": "≈4 MP",
        "price_usd": 0.0665,
        "list_price_usd": 0.09,
        "discount_pct": 26
      }
    ]
  },
  "deprecation": null,
  "upcoming_price_changes": []
}

为简洁起见，仅展示一个端点。

模型下线与价格变动#

涨价和模型下线信息会提前公告：涨价至少提前 14 天 通知；如合同约定更长的通知期，则按合同约定执行。模型下线则至少提前 14–30 天通知，并通过邮件告知过去 90 天内使用过该模型的所有客户，同时发布在更新日志（RSS）上。API 也会提供相同信息，方便你的代码和智能体及时响应：

deprecationobject | null: 这些字段会在列出模型和获取模型的响应中返回。模型计划下线时会设置：sunset_at（ISO 8601 时间；从该时间起请求会返回 410 model_delisted，且不收费）、replacement（按优先级排列的推荐模型 ID）、reason、announced_at 和 info_url。其他情况下为 null。
upcoming_price_changesarray: 尚未生效的计划价格档位变更：tier、effective_at、current_price_usd，以及每 unit 的新价格 price_usd。在 effective_at 之前提交的请求按当前价格计费；提交后不会重新计算生成任务价格。无计划变更时为空。
warningsarray: 在提交生成任务和查询报价的响应中，仅在存在相关信息时返回：model_deprecated（包含 sunset_at 和 replacement），或针对请求档位返回 price_change_scheduled（包含 effective_at 和新价格 price_usd）。每项均包含易读的 message 和 info_url。

请求

curl https://cheapergen.com/api/v1/models/bytedance/seedance-2.0-fast

响应 · 200 OK

{
  "id": "bytedance/seedance-2.0-fast",
  "object": "model",
  "…": "…",
  "deprecation": {
    "sunset_at": "2026-11-20T00:00:00.000Z",
    "replacement": [
      "bytedance/seedance-2.0-fast"
    ],
    "reason": "开发者将下架此模型。",
    "announced_at": "2026-10-21T09:30:00.000Z",
    "info_url": "https://cheapergen.com/changelog#cm2x7k9"
  },
  "upcoming_price_changes": [
    {
      "tier": "720p",
      "effective_at": "2026-11-04T00:00:00.000Z",
      "unit": "second",
      "current_price_usd": 0.08,
      "price_usd": 0.092,
      "change_pct": 15,
      "info_url": "https://cheapergen.com/changelog#cm2x8a1"
    }
  ]
}

弃用与 Sunset 标头#

模型下线计划确定后，相关模型的响应（POST /run、POST /quote 和 GET /models/{vendor}/{model}）会携带标准标头，方便 HTTP 客户端和 API 网关记录或触发提醒：

响应标头

Deprecation: @1792575000
Sunset: Fri, 20 Nov 2026 00:00:00 GMT
Link: <https://cheapergen.com/changelog#cm2x7k9>; rel="deprecation"; type="text/html", <https://cheapergen.com/changelog#cm2x7k9>; rel="sunset"; type="text/html"

Deprecation（RFC 9745）表示公告下线的时间，以 Unix 时间戳表示；Sunset（RFC 8594）表示停止处理请求的时间。切换只需修改一行：将同一请求发送到替代模型的端点（查看其输入结构，了解不同的选项）。

在 MCP 中，list_models 和 get_model 会包含相同的 deprecation 和 upcoming_price_changes 字段，以及一行易读的 notice，这样智能体在使用即将下线的模型前就能告知用户。

查询报价#

POST/api/v1/quote/{endpoint}公开 · 无需身份验证

无需实际运行即可查询输入价格。系统只读取与价格相关的字段（分辨率、时长、尺寸、图像数量等）；提示词等内容字段 prompt 和参考 URL 会被忽略，未填写的字段则使用默认值。若模型暂时不接受生成请求，则 available 会返回 false。

参考视频会增加计费时长。要将其计入价格，请传入 reference_video_durations（每段视频对应一个时长，单位为秒）作为预估提示；/run 会测量实际文件并按相应价格冻结余额。参见计费。

请求

curl -X POST https://cheapergen.com/api/v1/quote/bytedance/seedance-2.0-fast/text-to-video \
  -H "Content-Type: application/json" \
  -d '{"aspect_ratio":"16:9","resolution":"720p","duration":5}'

响应 · 200 OK

{
  "amount_usd": 0.4494,
  "list_usd": 0.6048,
  "list_price_source": "official",
  "list_price_label": "Official",
  "discount_pct": 26,
  "available": true,
  "currency": "usd"
}

发送 API 密钥即可获取专属价格。如果你的账户有合同价或 Pro 或 Max 套餐，报价还会包含 custom_price: true 和 standard_amount_usd（常规价格）；如果由 Pro（1）或 Max（2）套餐设定价格，还会包含 volume_level（1 或 2）。

获取账户信息#

GET/api/v1/account需要 API 密钥

返回你的余额和自动充值设置。balance_usd 是当前可用余额；image_credit_usd 是图片专用额度（例如欢迎额度），优先用于图片模型，不可用于视频；reserved_usd 是正在进行的生成任务从余额中冻结的金额。参见计费与余额。

请求

curl https://cheapergen.com/api/v1/account \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

响应 · 200 OK

{
  "object": "account",
  "email": "you@company.com",
  "balance_usd": 42.5,
  "image_credit_usd": 0,
  "reserved_usd": 1.2,
  "auto_topup": {
    "enabled": true,
    "threshold_usd": 10,
    "amount_usd": 50
  },
  "limits": {
    "unlimited": false,
    "concurrent_generations": 20,
    "in_flight": 3,
    "requests_per_second": 10,
    "burst": 20,
    "tier": null
  }
}

limits 是你账户的 API 限额以及当前进行中的生成数量；如果账户不限额，各项限额为 null，并带有 unlimited: true。参见速率限制。

获取你的价格#

GET/api/v1/account/pricing需要 API 密钥

返回你的月度套餐、套餐提供的用量等级，以及每个档位下的专属价格和标准价格。添加 ?model={vendor}/{model} 可查询单个模型。按量付费无需套餐：此时 plan 为 null，custom 为 false。参见月度套餐。

customboolean: true（当 Pro 或 Max 套餐或合同价降低你的任一价格时）。
planobject | null: 你的月度套餐：{ "id", "status" }，例如 pro 和 active（starter、pro 或 max）。没有套餐时为 null。
volumeobject: level：Pro 套餐生效时为 1，Max 套餐生效时为 2，否则为 null。
rulesarray: 你的合同价格（当前和已安排）：scope、status、discount_pct 或 unit_price_usd、starts_at、ends_at，以及易读的 description。
modelsarray: 你的套餐或规则覆盖的所有模型：id、name、unit 和 tiers——每个模型都包含 price_usd（你的价格）、standard_price_usd、custom、volume_level（套餐设定时）和 available。

请求

curl "https://cheapergen.com/api/v1/account/pricing?model=bytedance/seedance-2.0-fast" \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

响应 · 200 OK

{
  "object": "customer_pricing",
  "custom": true,
  "plan": {
    "id": "pro",
    "status": "active"
  },
  "volume": {
    "level": 1
  },
  "rules": [],
  "models": [
    {
      "id": "bytedance/seedance-2.0-fast",
      "name": "Seedance 2.0 Fast",
      "unit": "second",
      "tiers": [
        "…"
      ]
    }
  ]
}

上传文件#

POST/api/v1/uploads需要 API 密钥

上传文件后即可将其作为输入 URL 使用，例如首帧、参考图像、参考视频或参考音频片段。你也可以直接传入任意公开的 HTTPS URL，无需上传。

类型	格式	最大文件大小
图像	PNG、JPEG、WebP、GIF	20 MB
视频	MP4、MOV	50 MB
音频	MP3、WAV、M4A（目前模型仅支持 MP3 或 WAV）	15 MB

直接上传（推荐）#

发送 JSON，并提供文件的 filename、content_type 和 size（字节数）。系统会返回短时有效的 upload_url；将原始文件字节 PUT 发送到该地址，并准确附上返回的 headers，然后将 url 用作输入。文件会直接传到存储服务，因此除上方限制外没有其他请求大小限制。上传 URL 会在 15 分钟后失效。 size 必须是文件的精确字节数：PUT 时恰好发送这么多字节，并带上 Content-Length（不要用 chunked 或流式请求体）。其他情况存储服务都会返回 403。

请求

curl -X POST https://cheapergen.com/api/v1/uploads \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"choreo.mp4","content_type":"video/mp4","size":8421903}'

响应 · 201 Created

{
  "object": "upload",
  "method": "PUT",
  "upload_url": "https://storage.example.com/media/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&…",
  "headers": {
    "Content-Type": "video/mp4"
  },
  "url": "https://cdn.cheapergen.com/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.mp4",
  "kind": "video",
  "content_type": "video/mp4",
  "bytes": 8421903,
  "expires_at": "2026-10-15T09:36:04.000Z"
}

接下来上传文件字节

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @choreo.mp4

multipart 上传#

也可以使用 multipart/form-data 格式发送包含 file 字段的请求，由我们代为存储（返回 201 Created，并包含 url）。此方式会通过我们的 API 转发文件，请求正文大小约限制为 4.5 MB；更大的文件请直接上传。如果当前部署不支持直接上传，JSON 请求会返回 501 direct_upload_unavailable；此时请改用 multipart/form-data 上传。

请求

curl -X POST https://cheapergen.com/api/v1/uploads \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -F "file=@first-frame.png"

响应 · 201 Created

{
  "object": "upload",
  "url": "https://cdn.cheapergen.com/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.png",
  "kind": "image",
  "content_type": "image/png",
  "bytes": 1834221
}

使用已上传的图像#

将返回的 URL 传入图生视频或图像编辑端点的图像字段：

curl -X POST https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/image-to-video \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "镜头缓缓推近，她转身微笑，头发随风飘动",
  "image_url": "https://cdn.cheapergen.com/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.png",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}'

各模型的参考文档

每个模型都有专属 API 页面，其中列出各字段的类型、默认值和允许值，并提供可直接复制的示例。请从模型列表开始浏览。

有不清楚或缺少的内容？发邮件至 support@cheapergen.com——我们会认真阅读每一封邮件。