首尾帧视频生成看着只是“给两张图”，真正卡人的往往是密钥放错位置、任务 ID 没存住、轮询写成了死循环。

这篇教程围绕海螺 H3 Max 首尾帧 API 的接入流程展开，按“准备工作 — 密钥配置 — 任务提交 — 结果获取 — 排错上线”的顺序讲，每一步都说明该核对什么、以什么为准，帮助你把一次性的调通变成可以放进项目的稳定调用。

一、先搞清楚：海螺 H3 Max 首尾帧接口在做什么

首尾帧（First & Last Frame）是一种视频生成方式：你提供一段视频的起始画面和结束画面，再配上一段文字描述，模型负责补全中间的过渡过程。它适合产品演示、镜头转场、角色动作衔接、广告分镜这类“起点和终点已经确定，只缺中间过程”的场景。

和对话类接口最大的区别是：它属于异步长任务。提交请求通常很快就返回，但视频生成需要时间，所以接口不会在响应体里直接给你视频文件，而是返回一个任务标识。真正的接入工作，一半在提交，一半在任务生命周期管理。

接入前需要准备的 4 样东西

• API Key：用于身份鉴权，通常在控制台的密钥管理页面创建，注意创建后只显示一次。
• Base URL：请求的根地址，必须使用服务方控制台或文档中给出的地址，不要凭经验拼。
• 模型名称：视频模型的准确字符串，报“模型不存在”时，九成是名字写错或大小写不一致。
• 图片素材：首帧和尾帧文件。多数实现要求是可通过公网访问的图片地址，本地上传的文件需要先传到对象存储。

如果你希望用同一个 Base URL 管理多个模型、集中维护 API Key 和余额，可以先到 通联AI中转站 的控制台查看模型广场与接入文档，确认视频类模型的准确名称和协议说明，再回来配环境变量。

二、密钥配置：把密钥放对环境，而不是放进代码

大部分视频生成接口采用 HTTP Header 鉴权，形式类似 Authorization: Bearer <你的_API_KEY>。最容易犯的错误是把 Key 直接写在源码里提交到仓库，或者在一个文件里同时写死了测试环境和生产环境的地址。

推荐的环境变量写法

export HAILUO_API_KEY="控制台创建的密钥" export HAILUO_BASE_URL="控制台显示的接口地址"

配置完成之后，先用一个最小请求验证鉴权是否通过，再开始写业务逻辑。下面这张表把接入阶段必须核对的配置项列出来，建议逐项打勾。

需要提醒的是：字段名、图片格式限制、时长与分辨率上限，都以你所用平台的控制台和文档说明为准，不同服务方的命名习惯并不一致。

三、任务提交：一次请求要带哪些信息

提交阶段的请求体通常包含三部分：模型标识、首尾帧图片、生成控制参数（提示词、时长、分辨率、随机种子等）。下面是一段结构示意，用于说明字段关系，实际字段名请对照文档修改。

POST {BASE_URL}/video/generations Authorization: Bearer $HAILUO_API_KEY Content-Type: application/json { "model": "控制台显示的模型名称", "first_frame_image": "https://cdn.example.com/first.jpg", "last_frame_image": "https://cdn.example.com/last.jpg", "prompt": "镜头缓慢推进，人物从微笑到转身离开", "duration": 5 }

提交成功后必须留住的三样东西

1. 任务标识：接口返回的任务 ID，是后续查询结果的唯一凭据，建议落库而不是只打印日志。
2. 参数快照：把本次提交的完整参数存一份，方便出现画面对不上时回溯，也便于复现问题。
3. 原始响应：包括状态码与完整响应体，排错时比“我这边报错了”有用得多。

提示：提交接口遇到超时或连接中断时，不要立刻重新发起新任务。视频任务可能已经创建成功，盲目重试会造成重复扣费和重复生成。更稳妥的做法是在客户端生成一个请求追踪标识，并在提交前做去重判断。

四、结果获取：轮询和回调怎么选

拿到任务 ID 之后，有两种取结果的方式。轮询实现简单、不依赖外部服务，适合调试和低频调用；回调更适合生产环境，能减少无效查询，但需要你提供一个可被公网访问的接口，并做好签名校验和重复通知的处理。

轮询的写法建议

• 首次查询不要立刻发起，等待几秒再查，避免刚提交就产生一堆无意义请求。
• 采用退避策略，例如从 3 秒开始逐步拉长到 10 秒、20 秒，而不是固定 1 秒一次。
• 设置总超时时间，超过阈值就标记为待人工确认，不要让进程无限挂着。
• 把状态分类处理：排队中、生成中、已完成、已失败，前两种继续等，后两种分别走成功和失败分支。

拿到结果之后还要做什么

成功返回的通常是视频文件的临时地址，这类地址往往有有效期。生产环境应当在拿到地址后立刻下载并转存到自己的对象存储，同时把任务 ID、参数摘要、文件路径记录在数据库里，方便后续复用和计费核对。

五、常见报错与排查顺序

六、把接口放进项目：统一入口更省事

首尾帧只是视频能力的一种。实际项目里往往还要同时用到对话、图像、语音等模型，如果每个能力都对接一套密钥和地址，维护成本会迅速上升。这也是不少团队选择 AI 中转站的原因：用一个 Base URL 接入多模型，集中管理 API Key、余额和调用记录，减少在多个控制台之间来回切换。

通联AI中转站的页面展示了多种协议兼容方向和模型聚合能力，适合需要统一管理多模型调用、按任务切换模型的场景。需要接入海螺 H3 Max 首尾帧能力时，建议先登录 通联AI中转站官网，在模型广场核对可用的模型名称、接口地址与兼容协议，再按前面的步骤做密钥配置和任务提交，不要凭记忆替换配置。

七、上线前的检查清单

• 密钥通过环境变量注入，仓库中不存在明文 Key。
• Base URL 与模型名称来自控制台，已做最小请求验证。
• 任务 ID 与参数快照已落库，支持按任务查询。
• 轮询有退避和总超时，异常任务有明确的状态标记。
• 结果文件已转存，不依赖临时链接长期可用。
• 有基础的用量与成本观察方式，能定位异常消耗。

完成以上步骤，海螺 H3 Max 首尾帧 API 的接入基本就闭环了。剩下的工作是通过小批量样本观察生成效果，逐步调整提示词写法、时长和素材质量，让输出更贴近你的业务预期。