指南Seedance 2.5 API 教程：4 次调用生成第一条 AI 视频
MakerNice 团队 · ·
在 MakerNice 上用 Seedance 2.5 API 生成视频，只需一个 API Key 和四次 REST 调用：获取报价、创建任务、轮询状态、下载文件。本文以字节跳动的视频模型 Seedance 2.5 的文生视频模式为例，同一套流程适用于站内所有视频模型。接口是普通 REST，不兼容 OpenAI 格式，也没有官方 SDK，所以示例全部使用 curl。
调用 Seedance 2.5 API 之前需要准备什么？
需要一个有预付余额的 MakerNice 账户和一个 API Key。在控制台「开发者」下的「API Keys」里创建 Key；如果要写进脚本，建议同时设置花费上限和有效期。每个请求都用 Bearer 令牌带上 Key，只有 GET /v1/models 和 GET /v1/pricing 不需要。
第 1 步：怎样获取价格报价？
调用 POST /v1/generations/quote，请求体与你打算生成的输入完全一致。报价会在钱包冻结任何金额之前告诉你这次生成的确切费用。model、mode、prompt 必填；duration、resolution 可选，不填时使用模型默认值（Seedance 2.5 为 5 秒、720p）；aspect_ratio 也可选，不填就不发送。
curl https://api.makernice.com/v1/generations/quote \
-H "Authorization: Bearer $MAKERNICE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5",
"mode": "t2v",
"prompt": "A paper boat drifts down a rain-soaked street at dusk, slow dolly-in, warm shop lights reflecting on the water",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9"
}'返回内容包括以 qt_ 开头的 id、以 micro-USD 字符串表示的 amount（1,000,000 micro-USD 等于 1 美元）、price_version、expires_at 时间戳，以及回显计价内容的 facts 对象。这个价格锁定 12 分钟。
第 2 步：怎样创建任务又不会被重复扣费？
把报价 id 和同样的输入一起提交到 POST /v1/generations，并加上 Idempotency-Key 请求头：1 到 200 个可打印 ASCII 字符、不含空格，UUID 或你自己的订单号都合适。接口返回 202，带有以 gen_ 开头的 id、status 为 queued、billing 为 held。网络中断后用同一个键重试，会收到 200 和原来的任务，而不是第二笔扣费。
curl https://api.makernice.com/v1/generations \
-H "Authorization: Bearer $MAKERNICE_API_KEY" \
-H "Idempotency-Key: demo-order-1842-attempt-1" \
-H "Content-Type: application/json" \
-d '{
"quote_id": "qt_...",
"input": {
"model": "seedance-2.5",
"mode": "t2v",
"prompt": "A paper boat drifts down a rain-soaked street at dusk, slow dolly-in, warm shop lights reflecting on the water",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9"
}
}'
第 3 步：怎样查询状态并下载视频？
每隔几秒请求一次 GET /v1/generations/{id}。status 从 queued 变为 generating，最终落在 succeeded、failed 或 canceled；我们核对结果期间可能短暂出现 checking。成功后 outputs[0].url 指向结果文件，带上 Key 请求会得到 302 跳转，用 curl 的 -L 跟随即可。
# Check the status until it is succeeded, failed or canceled
curl https://api.makernice.com/v1/generations/gen_... \
-H "Authorization: Bearer $MAKERNICE_API_KEY"
# Download the file once succeeded
curl -L -o video.mp4 https://api.makernice.com/v1/generations/gen_.../outputs/0 \
-H "Authorization: Bearer $MAKERNICE_API_KEY"第一次调用最容易遇到哪些错误？
| 状态码 | 错误码 | 含义 | 怎么处理 |
|---|---|---|---|
| 400 | invalid_request | 发送了该模式用不到的字段，或未知字段 | 删掉该字段；用 GET /v1/models 核对模式 |
| 422 | price_unavailable | 该模型、模式、分辨率组合没有价格 | 改用列表中的分辨率 |
| 422 | quote_mismatch | 报价后改动了 model、mode、resolution 或 duration | 按最终输入重新报价 |
| 410 | quote_expired | 超过了 12 分钟的报价有效期 | 重新获取报价 |
| 409 | quote_already_used | 该报价已经用于一次生成 | 重新获取报价 |
| 402 | insufficient_balance | 钱包余额不足以冻结这笔费用 | 到控制台充值 |
跑通之后，建议接着读「API 接入最佳实践」一文，把幂等、轮询和限流的好习惯从第一天就用起来。
