首尾帧视频生成，是把两张图交给模型，让它补齐中间的运动过程。2026 年想把它接进自己的系统，难点通常不在算法，而在接口怎么调通。

很多开发者第一次接触万相3.0 首尾帧 API接口时，卡住的地方往往很具体：鉴权头写错、图片地址模型读不到、提交后拿不到任务 ID、轮询了半天返回的还是处理中。这篇教程按接入顺序讲清楚四件事——鉴权方式、地址与模型名怎么确认、关键参数怎么填、一次完整调用长什么样，最后给一份可对照的报错排查清单。

一、万相3.0 首尾帧能力解决的是什么问题

常规的图生视频，给一张首帧图加一段文字描述，模型自己决定镜头怎么走。首尾帧模式多了一个约束：你同时给出起点和终点，模型负责生成中间那段过渡。这个约束带来的直接好处是「结果可控」——画面的落点是你指定的，而不是模型随机发挥。

因此它更适合这几类任务：

• 分镜预演：广告或短片在正式拍摄前，用首尾两帧快速验证镜头运动和节奏是否成立。
• 电商素材：同一产品的主图与场景图之间做出平滑过渡，用于详情页或信息流投放。
• 漫画与绘本转场：把上一格结尾和下一格开头连起来，形成连贯的动态翻页感。
• 品牌视觉一致性：起止画面都经过设计审核，中间过程由模型补全，降低风格跑偏的概率。

需要说明的是，首尾帧能力对输入图片的要求通常比纯文生视频更高。两张图如果构图差异过大、主体位置完全不重叠，模型需要「脑补」的内容就会变多，输出结果的不确定性也随之上升。

接口的模型名称、参数取值范围、时长与分辨率档位、计费口径都可能随版本迭代调整。任何准备上生产的接入，都应以控制台和官方文档当前展示的信息为准，不要直接套用旧教程里的参数值。

二、接入前的准备：鉴权方式与三个必核对项

鉴权方式：API Key 放进请求头

目前主流的视频生成接口都采用 Bearer Token 鉴权，也就是把 Key 放在请求头里：

Authorization: Bearer YOUR_API_KEY Content-Type: application/json

三点务必注意：第一，API Key 属于服务端凭证，不要写进前端页面或 App 客户端，否则等于公开；第二，建议按环境区分 Key，测试和生产各用一把，出问题好定位也好回收；第三，如果请求是异步任务型接口，创建任务和查询结果用的是同一个 Key，不要中途换。

如果你同时要对接多个厂商的模型，用一把 Key、一个入口统一管理的做法会省很多事。像 通联AI中转站 这类 AI 聚合平台，就是把多模型调用、API Key 与余额收在同一个控制台里，适合需要减少多平台切换的团队。具体有哪些模型、走哪种兼容协议，可以在控制台的模型广场里逐个确认。

Base URL 与模型名称怎么确认

Base URL 决定了请求发到哪个网关，模型名称决定了网关把任务路由到哪个模型。这两项最容易出错，因为它们不是「通用常量」，不同接入渠道给的值可能不一样。正确做法是：登录控制台或查阅接口文档，把当前可用的 Base URL 和模型名称复制出来，而不是凭记忆手敲。

三、参数怎么填：首帧、尾帧与运动描述

图像输入

首帧和尾帧一般通过两个独立字段传入，值可以是可公网访问的图片 URL，也可以是 Base64 编码。用 URL 时要注意：这个地址必须能被服务端直接拉取，带登录态的内网地址、临时签名已过期的链接都会导致取图失败。生产中更稳妥的做法是先把图片上传到对象存储，再传公网可读地址。

运动描述与时长

提示词在这里的角色是「补充说明」，不是「决定一切」。起止画面已经框定了结果，提示词主要用来描述中间的运镜方式、光线变化和节奏。写得越具体越有效，比如「镜头缓慢推进，光线由暖转冷，主体保持居中」就比「让它动起来」有用得多。

时长、分辨率、帧率这类参数要按档位填写，且各档位通常对应不同的资源消耗。填之前建议先查一次文档里的可选值，超出范围的取值会被直接拒绝。

异步任务与结果获取

视频生成耗时远高于文本生成，所以接口基本都是异步的：第一次请求只负责创建任务并返回任务 ID，你再用这个 ID 轮询或等待回调。轮询间隔建议 3 到 5 秒起步，不要写成 200 毫秒死循环，那只会白白消耗配额。

四、一次完整的调用示例

下面是一个最小可用的请求结构，字段名请按你所接入的协议调整：

curl -X POST "$BASE_URL/v1/video/generations" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "控制台显示的模型名称", "first_frame_image": "https://your-cdn.com/first.jpg", "last_frame_image": "https://your-cdn.com/last.jpg", "prompt": "镜头缓慢推进，光线由暖转冷，主体保持居中", "duration": 5, "resolution": "1080p" }'

拿到任务 ID 后，再发一次查询请求：

curl -X GET "$BASE_URL/v1/video/generations/TASK_ID" \ -H "Authorization: Bearer $API_KEY"

返回状态通常分为排队中、处理中、成功和失败四类。成功时结果里会带视频地址；失败时一般会给出错误码和原因描述，按原因去排查比盲目重试高效得多。

五、常见报错与排查顺序

1. 401 / 鉴权失败：检查 Key 是否完整复制、是否带了多余的换行、请求头是否写成 Authorization: Bearer。
2. 404 / 模型不存在：模型名称与控制台展示不一致，或该模型未开通。直接从模型列表复制一次。
3. 取图失败：图片地址不可公网访问，或格式、体积超出限制。换成公开可读的图片再试。
4. 参数校验不通过：时长、分辨率填了不在档位内的值，或字段名与所用协议不匹配。
5. 一直处理中：先降低分辨率与时长验证链路，再逐步加码，避免一上来就压最重的参数。

六、成本与用量控制

视频类接口的计费通常和时长、分辨率直接挂钩，长视频加高分辨率的组合会让单次消耗明显上升。三个可落地的控制手段：先在低档位把流程跑通再提规格；在业务侧做请求排队，避免瞬时并发把额度打空；把每次任务 ID、模型、参数和消耗记录下来，方便回溯是哪一类请求在吃成本。

如果你希望把多个模型的调用收在同一个入口，随时查看余额与用量，可以在 通联AI中转站 的模型广场与控制台里核对当前可用的模型、接入协议与计费说明，再决定用哪条链路承载生产流量。所有价格与额度信息请以页面实时展示为准。

最后回到那句最实用的话：万相3.0 首尾帧 API接口能不能跑通，八成取决于你是否用了对的 Base URL、对的模型名称和能被服务端读到的图片。先把这三件事对齐，剩下的参数微调都只是时间问题。