2026年SD 2.5 文生 按秒 首尾帧视频API 接入指南：从首尾帧上传到视频结果回调
2026年SD 2.5 文生 按秒 首尾帧视频API 接入指南：从首尾帧上传到视频结果回调
首尾帧视频生成听起来很简单：给两张图，等一段视频。真正动手接入时，难点集中在三处——图片怎么上传、任务怎么提交、结果什么时候以什么形式回来。
这篇文章按接入顺序把 SD 2.5 文生 按秒 首尾帧视频API 的完整链路拆开讲：从首帧尾帧的准备，到任务提交、按秒参数的理解，再到结果回调与幂等处理。
很多人卡住的地方并不是看不懂文档，而是拼参数时漏了字段、回调时没做校验，导致任务明明已经成功，业务侧却始终拿不到可用的视频地址。
一、一次首尾帧生成要经过的四个环节
先把链路画清楚，后面每一步才知道该验证什么。整条流程可以拆成素材准备、任务提交、任务执行和结果回调四段，每一段的输入输出和复核点都不一样。
| 环节 | 输入 | 输出 | 复核点 |
|---|---|---|---|
| 素材准备 | 首帧图、尾帧图、文本提示 | 可被服务端访问的图片地址 | 格式、尺寸、宽高比是否一致 |
| 任务提交 | 模型名、提示词、时长、回调地址 | 任务 ID | 字段名与文档一致，时长在允许档位内 |
| 任务执行 | 图片与提示词 | 视频文件或临时下载地址 | 轮询间隔是否合理，失败状态是否被处理 |
| 结果回调 | 任务 ID 与完成状态 | 可播放、可下载的视频 | 验签、幂等、地址有效期 |
二、首帧与尾帧的准备
两张图的格式与尺寸要统一
首帧和尾帧最好保持相同的宽高比，否则模型需要在两帧之间做形变补偿，画面容易出现拉伸或抖动。常见做法是先统一裁剪到同一分辨率，再上传。格式上优先使用文档列出的常见图片格式，压缩时避免过度有损，以免关键细节丢失，反而影响生成稳定性。
图片必须能被服务端直接访问
如果接口接收的是图片地址，那么这张图必须能被服务端直接取到。本地路径、内网地址、需要登录才能打开的链接都会导致取图失败。比较稳妥的流程是：先调用图片上传接口拿到返回的 URL，再把这个 URL 填进视频生成请求。若接口支持 Base64 上传，要注意整体请求体的大小限制，过大时优先改用 URL 方式。
三、提交生成任务：参数怎么写
提交前请先在控制台或文档里确认该模型对应的请求路径、字段名和必填项。不同平台对同一能力的参数命名可能不同，照抄别处的示例很容易漏字段。
POST /v1/video/generations
{
"model": "以控制台显示的模型名称为准",
"prompt": "镜头缓慢推进，人物由静止转为转身走向门口",
"first_frame_url": "https://your-cdn.com/first.jpg",
"last_frame_url": "https://your-cdn.com/last.jpg",
"duration": 5,
"callback_url": "https://your-domain.com/video/callback"
}提交后接口一般会立刻返回一个任务 ID，这个 ID 是后续查询状态、处理回调的唯一凭据，建议直接落库并带上业务侧的唯一标识，方便对账和重试。
按秒计费意味着生成时长会直接进入用量计算。提交前请以官网或控制台展示的实时计费规则和可用时长档位为准，不要沿用其他平台的经验值。建议先用一个较短的视频任务验证效果，确认画面与节奏符合预期后，再扩大到批量提交。
四、结果回调：Webhook 与轮询怎么选
回调接口要处理好的三件事
- 验签与来源校验：确认请求确实来自平台，而不是被伪造的回调，避免无效写入。
- 幂等处理：同一任务 ID 可能因为重试被推送多次，业务侧应保证重复回调不会产生多条记录。
- 地址转存：回调里的视频地址往往有有效期，收到后应尽快转存到自己的存储，再对外提供访问。
@app.route('/video/callback', methods=['POST'])
def callback():
data = request.get_json()
task_id = data.get('task_id')
if data.get('status') == 'succeeded':
video_url = data.get('video_url')
save_result(task_id, video_url) # 转存到自有存储
elif data.get('status') == 'failed':
mark_failed(task_id, data.get('error'))
return {'code': 0}如果暂时不方便开放公网回调地址，也可以改用轮询：按固定间隔查询任务状态，直到返回成功或失败。轮询要注意两点，一是间隔不要过短，否则容易触发限流；二是设置最大轮询次数，避免任务长时间挂起却无人处理。
五、几个容易踩的失败原因
- 取图失败：首帧或尾帧地址无法被公网访问，或链接已过期。
- 参数名写错：字段拼写与文档不一致，接口通常直接返回参数校验错误。
- 时长越界：请求的时长不在平台允许的档位内，需要按文档调整。
- 回调地址不可达：域名未备案、端口未放开、路由路径写错，都会导致回调丢失。
- 重复处理：没有做幂等，同一任务被多次写入，最终视频记录混乱。
六、接进正式业务前的检查清单
把 Key 放进环境变量而不是代码里；给提交、查询、回调三处都加上日志，至少记录任务 ID、耗时和最终状态；对失败任务设计重试策略并设置上限；对生成的视频做人工抽检，确认首尾帧过渡自然、没有明显崩坏，再决定是否批量生产。视频生成属于结果带有一定随机性的任务，人工复核环节不建议整体省略。
当团队同时要调用视频、图像、对话等不同类型的模型时，把入口集中在一处会更容易管理 Key 和用量。像 通联AI中转站 这类聚合平台把多种能力放在同一个控制台里，方便按任务切换；实际支持哪些视频模型、参数怎么写、按什么规则计费，请以 通联官网 上展示的实时信息为准。
想尽快跑通首尾帧视频的完整链路，可以到通联注册账号，在控制台获取 API Key、确认 Base URL 与当前可用的视频模型，先用一个短时长任务完成从提交到回调的验证，再接入正式业务。