生成任务

视频和图像模型的处理时间从几秒到几分钟不等，因此每个请求都是 异步。提交请求后会立即返回一个 生成任务；之后你可以轮询任务状态，或在任务进入最终状态时接收 Webhook。一个生成任务对象会记录整个任务，包括输入、状态、输出、错误和费用。

任务生命周期#

succeeded、failed 和 canceled 均为最终状态：生成任务进入其中一个状态后就不会再变化。请将其他任何状态视为“仍在处理中”，这样即使我们增加中间状态，你的代码也能正常工作。

1. 提交#

提交任务时，将模型输入作为 JSON 正文传入 POST /api/v1/run/{endpoint}。端点 ID 由模型和任务组成，例如 bytedance/seedance-2.0-fast/text-to-video。所有端点及字段请见 模型 页面。

我们会验证输入、计算价格、从余额中冻结金额并将任务加入队列。响应会返回 202 Accepted 和生成任务，并附上 urls.get 与 urls.cancel，方便快速使用：

{
  "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"
  }
}

参考图像、视频和音频#

reference-to-video 模式最多接受三类参考素材，每类素材都以 HTTPS URL 列表形式提供（公开链接或来自 uploads 的 URL）：reference_image_urls 用于角色、产品和场景，reference_video_urls 用于动作、镜头运动和特效，reference_audio_urls 用于人声、音乐和音效。

在提示词中按位置引用素材：@Image1 对应 reference_image_urls 中的第一个 URL，@Video1 对应 reference_video_urls 中的第一个 URL，@Audio2 对应第二段音频，后续依此类推。引用不区分大小写，并会规范化为 @Image1。如果引用没有匹配的参考素材（例如只附带一段视频，却写了 @Video2），请求会在扣款前被拒绝并返回 400 invalid_request（param: "prompt"）。

{
  "prompt": "@Image1 dances on a rooftop, copying the choreography and camera move of @Video1, in sync with @Audio1",
  "reference_image_urls": [
    "https://example.com/dancer.jpg"
  ],
  "reference_video_urls": [
    "https://example.com/choreo.mp4"
  ],
  "reference_audio_urls": [
    "https://example.com/beat.mp3"
  ],
  "resolution": "720p",
  "duration": 8
}

提交时，我们会下载每段参考视频和音频文件的开头部分，并检查实际时长、大小、分辨率和帧率是否符合模型限制。若文件超出任一限制——例如片段长达 20 秒、模型只支持 720p 却提供 1080p 视频、模型要求 MP3 或 WAV 却传入 M4A，或 URL 无法访问——会在扣款前返回 400 invalid_request，将 param 设置为出错字段（例如 reference_video_urls），并在错误消息中指出具体片段。参考视频会增加计费时长，详情见 计费。

视频必须为 H.264 或 H.265 编码的 MP4/MOV 文件。限制取决于模型所用算力的最严格条件，因此通过此处验证的请求会被上游接受。参考图像和音频不会影响价格。

2. 轮询结果#

GET /api/v1/generations/{id} 会返回当前状态。读取生成任务也会推动任务处理：如果到了状态检查时间，我们会先检查再响应，因此轮询返回的数据最多只会延迟几秒。

const API = "https://cheapergen.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.CHEAPERGEN_API_KEY}` };
const FINAL = new Set(["succeeded", "failed", "canceled"]);

export async function wait(id, timeoutMs = 15 * 60_000) {
  let delay = 2000;
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const gen = await fetch(`${API}/generations/${id}`, { headers }).then((r) => r.json());
    if (FINAL.has(gen.status)) return gen;
    await new Promise((r) => setTimeout(r, delay));
    delay = Math.min(delay * 1.5, 10_000); // back off to every 10 s
  }
  // Giving up: cancel it first, or it still runs and is charged when it finishes (once running it can't be: 409).
  await fetch(`${API}/generations/${id}/cancel`, { method: "POST", headers }).catch(() => {});
  throw new Error(`Timed out waiting for ${id}`);
}

import os, time, requests

API = "https://cheapergen.com/api/v1"
headers = {"Authorization": f"Bearer {os.environ['CHEAPERGEN_API_KEY']}"}

def wait(gen_id, timeout=900):
    delay, waited = 2, 0
    while waited < timeout:
        gen = requests.get(f"{API}/generations/{gen_id}", headers=headers).json()
        if gen["status"] in ("succeeded", "failed", "canceled"):
            return gen
        time.sleep(delay)
        waited += delay
        delay = min(delay * 1.5, 10)  # back off to every 10 s
    # Giving up: cancel it first, or it still runs and is charged when it finishes (once running it can't be: 409).
    requests.post(f"{API}/generations/{gen_id}/cancel", headers=headers)
    raise TimeoutError(gen_id)

建议的轮询间隔#

• 图像： 每隔 1–2 秒查询一次。大多数任务会在 30 秒内完成。
• 视频： 一开始每 3–5 秒查询一次，之后逐渐延长到 10 秒。5 秒视频通常需要 1–3 分钟；分辨率较高时会更久。
• 轮询会计入你的 速率限制。如果同时运行多个任务，建议使用 webhooks。

3. 获取输出#

生成成功后，output 会包含生成媒体的 HTTPS URL。视频模型会返回一个文件：

{
  "output": {
    "video": {
      "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.mp4",
      "content_type": "video/mp4"
    }
  }
}

图像模型会返回一个列表，每项对应一张生成的图像：

{
  "output": {
    "images": [
      {
        "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.png",
        "content_type": "image/png"
      }
    ]
  }
}

失败与退款#

生成失败时， status 是 failed，error 会说明失败原因及处理方法， cost.amount_usd 会变为 0——已冻结的额度会全额退回余额。服务商中断或出错时，系统会自动尝试所有其他符合条件的路由，然后才将任务标记为失败。安全过滤器拒绝的请求或模型无法接受的输入不会重试，因为再次提交也会得到相同结果。服务商无法下载输入文件时，我们通常会自行下载并用副本重试，价格不变；input_unreachable 通常表示文件根本无法下载。

{
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "message": "ByteDance's safety review for Seedance 2.0 Fast rejected this request (the prompt or an input file).",
    "reason": "content_blocked",
    "hint": "Describe the character's look instead of naming a copyrighted character or real person, keep it non-explicit, or try another model.",
    "retryable": false,
    "refunded": true,
    "detail": "你的请求未通过内容安全检查。请调整提示词后重试。"
  },
  "cost": {
    "amount_usd": 0,
    "currency": "usd",
    "estimated": false
  }
}

• code 是通用错误类别，自产品上线以来保持不变：generation_failed（输入被拒绝或无法完成）、upstream_error、timeout 或 model_unavailable。
• reason 会准确说明原因，见下表。新接入时请根据此字段编写分支逻辑；未来可能会增加新的原因。
• message 会提供可以直接展示给用户的易读说明。如果请求被安全过滤器拦截，这里会指出拒绝请求的是哪一方的过滤器（即模型服务提供商的过滤器）。
• hint 会说明建议修改或执行的操作。
• retryable — 如果使用相同请求重试可能成功，则为 true；如果重试仍会以相同方式失败，则为 false。
• refunded — true 表示冻结金额已退回。生成失败不会产生费用。
• param — 如果能判断，会指出需要修改的输入字段，例如 image_url、duration。
• detail — 如果模型服务提供商提供了补充说明，则会保留其原始措辞。

在 reason 字段推出前就已失败的生成任务，仍保留原有 code；现在也会补全 reason 和 hint 字段。

应急价格#

当请求所需的常规算力不可用时，可以改用价格更高的算力，并按 应急价格计费，但价格绝不会高于模型的官方价格。 allow_fallback_price 决定是否启用，默认值为 true 决定。在 REST API 和 MCP 中，默认情况下 max_cost_usd 会同时限制两种价格。传入 allow_fallback_price: false 确保支付金额不高于报价（使用 Pro 或 Max 套餐，已接受的任务在其他情况下也可能切换到更高价格，但最高不超过标准价格）：此时新请求的报价为 503 fallback_price_declined；如果已按常规价格接受的任务中途遇到算力故障，则任务会失败并退款。Studio 任务在你点击后绝不会切换到更高价格。应急价格适用时，生成任务的 pricing.fallback （Webhook 中也会包含）会注明这一点，并列出两种价格。

安全检查器#

enable_safety_checker 默认设置为 true。你可以通过 API 传入 false；Studio 和模型页面中始终会启用该选项。具体作用取决于模型：

• 闭源模型 （Seedance、Kling、Veo、MiniMax H3、Wan 3.0 等）使用各自实验室提供的内容审核，任何人都无法关闭。它们接受 true 和 false，两种情况都不会改变任何内容，因此 schema 中不会列出该选项。MiniMax H3 Max 是例外：它支持关闭过滤器，因此会列出该选项。关闭过滤器的请求会使用专属安全配置 ——可能按应急价格计费，但绝不会高于官方价格。
• Seedream 4.5 and Seedream 5.0 Lite 也列出了该选项。关闭后，请求会使用 ByteDance 自己面向海外的模型配置运行，不会额外应用过滤器；开启后则会应用常规过滤器。我们的检查器仍会拦截任何涉及未成年人的色情内容。关闭该选项的请求有单独的较高价格：Seedream 4.5 $0.04 per image · Seedream 5.0 Lite $0.035 per image。发送 enable_safety_checker: false （包含 fallback.reason "safety_checker_off" 时，/quote 会将其返回。此类请求计为 应急价格：如果使用 allow_fallback_price: false，请求会被拒绝。当前无法运行时，请求会以 503 model_unavailable（param: "enable_safety_checker"）拒绝；发送 true 即可使用标准过滤器运行。
• 开放权重模型 会列出该选项。如果生成任务使用的算力没有自带过滤器，我们的审核器会先检查提示词和输入图片：开启该选项时，会拦截色情、露骨暴力和自残内容；关闭时，仍会拦截任何涉及未成年人的色情内容。如果算力自带可切换的过滤器，我们会按你传入的值将此开关传给它；关闭时，我们的审核器仍会拦截任何涉及未成年人的色情内容。

false 若用于未列出此选项（且无法关闭审核器）的模式，会返回 400 invalid_request。关闭该选项不会放行任何被我们的 可接受使用政策 禁止的内容。

数据保留#

API 生成任务 默认保留 1 天，从任务完成时开始计算。之后，系统会自动删除提示词、输入媒体、输出及相关文件。生成任务记录本身仍会保留模型、决定价格的参数、费用和时间戳，确保用量历史和发票准确无误：output 会变为 null，purged_at 会设置，content_expired 会说明删除原因。请在 expires_at 前下载想要保留的输出。

在请求正文中传入 retention，为每个生成任务单独选择保留期限。所有账户都可以缩短保留时间（或申请最长 1d）；7d 和 30d 需要在账户级设置数据保留期限——请联系销售。如果请求的保留时长超过账户允许的上限，则返回 400 invalid_request 和 param: "retention"。

{
  "prompt": "A paper boat drifting down a rain-soaked street",
  "resolution": "720p",
  "duration": 5,
  "retention": "immediate",
  "webhook_url": "https://example.com/hooks/cheapergen"
}

Studio 和 Playground 生成任务 会一直保留到你将其删除。文件上传 只要有未删除的生成任务在使用，就会一直保留；未被任何生成任务使用的文件会在 1 天后删除。删除账户会同时删除所有生成任务和文件。在模型服务提供商允许的情况下，我们也会要求对方尽可能缩短数据保留时间。

删除生成任务#

你可以使用 DELETE /api/v1/generations/{id} 删除任何已完成的生成任务，也可以在控制面板的生成任务列表或 Studio 查看器中删除；通过 API 还可以删除仍可取消的排队中任务（会先取消并全额退还冻结的费用）。相关文件、提示词和输入会立即移除，任务也会从列表中消失；费用仍会保留在账单记录中。参见 API 参考文档。

取消任务#

POST /api/v1/generations/{id}/cancel 会取消仍处于 queued 状态的生成任务，并退还冻结金额。任务进入 running 状态后，模型已经开始处理，取消请求会返回 409 conflict，任务仍将正常完成并计费。部分模型不支持取消排队中的任务，此时也会返回 409。

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

列出生成任务#

GET /api/v1/generations 会按时间倒序列出你的生成任务，并支持游标分页。可按 status、model 或 source（playground、api、mcp）筛选；将返回的 next_cursor 作为 cursor 传入即可获取下一页。详情请参阅 API 参考文档。

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

Studio 和模型页面 Playground 中的生成任务也会显示在这里，并标记为 source: "playground"；API 请求则会标记为 source: "api"。