2026年 SD 2.5 满血版 按秒 API调用 接入实操：请求参数、返回结构与调用示例
2026年 SD 2.5 满血版 按秒 API调用 接入实操：请求参数、返回结构与调用示例
按秒计费的模型接口，真正容易出错的地方往往不是请求发不出去，而是没弄清计费口径和任务生命周期：从哪一刻开始计时、排队算不算、返回字段到底代表什么。先把这些对齐，再写代码会省下大量返工。
下面按「理解计费 → 准备配置 → 构造请求 → 解析返回 → 排查问题」的顺序展开。文中出现的参数名与字段名只作为结构示意，实际请以你在通联AI中转站控制台与文档中看到的模型名称、接口地址和计费规则为准。
一、按秒计费，先分清「两种秒」
很多团队在对接前会默认一个前提：按秒就是按生成内容的时长收费。实际并不一定。常见的按秒口径至少有两种：
- 任务耗时秒数：从任务开始执行到产出结果所占用的计算时间。排队、重试、失败前的耗时是否计入，各家规则并不相同。
- 产出内容时长：生成结果本身的时长，例如一段 5 秒的视频按 5 秒计价，与服务器实际跑了多久无关。
这两种口径对成本估算的影响完全不同。前者更依赖并发和任务排队情况，后者更容易按业务量线性推算。所以在正式批量调用之前，建议先做三件事：跑一次最小任务，对照用量明细确认扣费口径；确认失败任务是否计费、有没有重试补偿；确认是否设定了最小计费单位，比如不足 1 秒按 1 秒计算。
SD 2.5 满血版按秒 API 调用这类场景，单位成本与时长强相关，任何一次参数改动都可能带来成本变化。在聚合平台上，不同模型、不同能力可能采用不同的计费方式，所以不要用 A 模型的计费习惯去推断 B 模型，以控制台展示的说明和真实用量记录为准最稳妥。
二、接入前要准备好的四件事
- API Key 与权限范围：确认这把 Key 属于哪个项目、是否限定了可用模型、有没有独立额度上限。团队协作时尽量一个项目一把 Key，便于按业务核算用量。
- Base URL 与协议：按秒接口可能是原生协议，也可能是 OpenAI 兼容风格。路径前缀差一个字符就会 404，所以直接从控制台复制，不要手写。
- 模型名称：模型标识必须逐字一致，包含版本后缀、大小写和连字符。控制台模型列表里显示的名称，就是要写进 model 字段的那个。
- 回调地址或轮询方案：异步任务需要回调或轮询。回调要求公网可达并做签名校验；轮询要设定间隔与最大次数，避免把查询接口打成压测。
三、请求参数：把一次任务描述清楚
按秒计费的生成任务，请求参数大致可分成四组：任务身份、输入内容、输出规格、控制与回调。参数命名在不同供应商之间差异很大，但作用基本对应。下面是接入时最值得逐项核对的几个配置。
| 配置项 | 作用 | 检查方法 |
|---|---|---|
| model | 决定能力范围、并发限制与计费口径 | 与控制台模型列表逐字比对，注意版本后缀 |
| seconds / duration | 直接决定按秒计费的总量 | 先用最小时长跑通，确认口径后再放大 |
| resolution / ratio | 影响生成耗时与输出质量 | 核对文档给出的可选值，不要传未声明的比例 |
| callback_url | 异步任务完成后的通知入口 | 确认公网可达、可验签、能容忍重复通知 |
另外两个容易被忽略的字段是幂等键与随机种子。幂等键能让重试不产生第二份扣费；种子影响结果可复现性，做效果对比时很有用。是否支持这两个参数，同样以文档为准。
四、返回结构：同步与异步必须分开处理
按秒计费的生成类接口绝大多数是异步的。第一次请求只负责「下单」，返回一个任务标识和初始状态；真正的结果要通过查询接口或回调拿到。这两类响应的字段结构经常不一样，如果按同一套模型去解析，就会出现「状态拿到了，结果地址永远为空」的情况。
不要用创建接口的字段名去解析查询接口的结果。更稳妥的做法是：先用真实请求各抓一份完整响应体，把状态机、结果字段和错误字段逐一映射清楚，再写解析代码。
轮询频率与超时上限
轮询间隔建议从 2 到 5 秒起步，并对总时长设置上限。多数任务在几十秒内完成，如果超过边界仍未结束，更可能是排队或任务异常，此时继续高频轮询只会徒增压力。配合指数退避，能把查询请求量压低一个量级。
状态机要覆盖失败分支
一个完整的任务状态至少包含：已提交、处理中、已完成、失败、已取消。业务侧必须显式处理失败与取消，否则失败记录会永远停在「处理中」，对账时你无法判断它是没跑完，还是已经产生了消耗。
五、调用示例（结构示意）
import requests
BASE = 'https://你的BaseURL'
HEADERS = {'Authorization': 'Bearer 你的API_KEY'}
# 1. 创建任务
resp = requests.post(
BASE + '/v1/generations',
headers=HEADERS,
json={
'model': 'sd-2.5-full',
'prompt': '海边日落，镜头缓慢推进',
'seconds': 5,
'size': '1280x720',
'callback_url': 'https://your.domain/callback'
},
timeout=30
)
task_id = resp.json().get('id')
# 2. 查询任务状态
state = requests.get(BASE + '/v1/generations/' + task_id, headers=HEADERS).json()
print(state.get('status'), state.get('progress'))示例中的路径、字段名与参数取值都只是结构示意。真正接入时，建议先从通联AI中转站的文档中复制一份可直接运行的请求，替换成自己的 Key 后再改参数，这样能避免因为拼写差异导致的 404 或参数报错。
六、联调阶段最常见的五类问题
- 401 / 403：Key 写错、带了多余空格，或者这把 Key 本身没有该模型权限。
- 404 找不到模型：model 名称与平台登记的不一致，多一个空格或版本后缀都会失败。
- 参数越界：时长或分辨率超出文档允许范围，这类报错有时在执行阶段才返回，而不是创建阶段。
- 结果地址取不到：只解析了创建响应，没在查询响应里取结果字段；或者结果链接有有效期，缓存太久已失效。
- 重复提交：网络超时后盲目重试创建请求，又没有使用幂等键，最终产生两份任务。
七、上线前的自检清单
灰度环境里先用小批量跑通，确认计费口径、失败补偿与超时重试策略，再逐步扩量。建议把时长、分辨率这类关键参数纳入配置管理，而不是散落在代码各处，这样调整成本模型和排查线上问题时都会轻松很多。
如果你希望在同一套代码里管理多个模型的调用，SD 2.5 满血版按秒 API 调用也可以放在统一的接入入口下处理。通联提供统一的 Base URL 与 API Key 管理，兼容多种协议方向，模型名称、接口地址与计费说明都能在控制台和文档中查到。切换模型时，通常只需要替换 model 与少量参数，而不必重写整套调用链路。
接口能不能跑通，往往取决于第一次请求有没有配对参数。如果你准备开始按秒调用验证，建议先注册账号拿到 API Key，再到控制台核对 Base URL、模型名称与计费说明，用一个小任务完成首轮联调。