2026年万相-视频换人 视频生成API接入教程：请求参数配置与调用示例
2026年万相-视频换人 视频生成API接入教程：请求参数配置与调用示例
视频换人类接口表面看只是“传两段素材、拿一段成片”，真正卡住工程进度的，往往是异步任务、参数命名和素材合规。下面按接入顺序，把万相-视频换人 视频生成API 的关键配置拆开讲。
示例中的字段按通用 REST 风格给出，实际参数名、取值范围和返回结构，请以你所使用控制台文档的实时说明为准。
一、先搞清楚视频换人接口在做什么
视频换人（face swap / 角色替换）的目标，是把源视频中的人物形象替换成目标人物，同时尽量保留原有的动作、镜头节奏与光影关系。和纯文生视频不同，它对输入素材的依赖更高：源视频的分辨率、人物在画面中的占比、遮挡与侧脸比例、目标人物的正脸清晰度，都会直接影响最终观感。
接入万相-视频换人 视频生成API 之前，建议先把三件事确认清楚：第一，任务是同步返回结果还是异步返回任务 ID；第二，输入素材是直接传公网 URL，还是需要先上传拿到文件标识；第三，输出视频的时长、分辨率与码率上限。这三点不同，请求体的写法和轮询逻辑差别很大。
如果你的项目里不止一种生成能力——换人、图生视频、文生视频、语音配音都要用——可以先用一个统一入口把 API Key 和 Base URL 管理起来。通联AI中转站 这类 AI 聚合平台，把多家厂商模型收敛到兼容接口方向，适合需要在一个控制台里对比模型、统一管理密钥与余额的团队。具体可用模型与接入方式，以控制台模型广场和文档页面显示的信息为准。
二、接入准备：四样东西先备齐
- 可用的 API Key：在控制台的密钥管理里创建，不要直接写进前端代码或提交到代码仓库。
- Base URL：决定请求打到哪个网关，注意结尾是否带
/v1，两种写法的拼接结果完全不同。 - 模型名称：从模型广场复制完整标识，不要凭记忆拼写，大小写和连字符都可能影响路由。
- 可访问的素材地址：源视频与目标人脸图需要能被服务端拉取，临时链接要确认有效期。
配置项与检查方法对照
| 配置项 | 作用 | 检查方法 |
|---|---|---|
| API Key | 身份鉴权 | 放在请求头 Authorization 中，确认没有多余空格与换行 |
| Base URL | 决定请求进入哪个网关 | 与文档示例逐字比对，尤其注意结尾斜杠 |
| 模型名称 | 决定任务调度到哪个模型 | 从控制台模型广场复制，避免手写 |
| 任务 ID | 异步任务查询凭据 | 提交成功后立即入库，轮询与重试都复用它 |
三、请求参数配置：换人任务通常包含哪些字段
不同厂商的字段命名不完全一致，但结构大体分为“输入素材”和“输出控制”两组。理解这两组的分工，比死记字段名更重要。
输入素材类参数
- 源视频：需要被替换的那段视频，建议使用常见封装格式与编码，时长越短越容易排查问题。
- 目标人脸或人物图：尽量用正脸、无遮挡、光照均匀的图片，分辨率不宜过低。
- 遮罩或区域标记：部分模型支持指定替换范围，用于避免误换背景人物。
输出控制类参数
- 时长与分辨率：直接影响生成耗时与消耗，先用最短时长做联调。
- 帧率与码率：与播放端保持一致，避免二次转码。
- 随机种子：便于复现同一效果，也方便团队内部对比多个版本。
- 音频处理：确认是保留原声、静音还是后续单独配音。
请求体结构示意
{
"model": "控制台显示的模型名称",
"input": {
"source_video": "https://cdn.example.com/source.mp4",
"target_face": "https://cdn.example.com/face.jpg"
},
"parameters": {
"duration": 5,
"resolution": "720p",
"keep_audio": true
}
}不要靠猜参数名上线。先用最小请求体跑通一次，再根据返回的错误码逐项补齐字段。参数是否必填、是否被兼容层改写，都以控制台文档和接口实际返回为准。
四、调用流程：从提交任务到拿到成片
完整链路通常由四步构成，少了任何一步都容易出现“任务显示成功、却拿不到文件”的情况。
- 提交任务：携带 API Key、模型名称与输入素材，拿到
task_id。 - 获取结果：按文档给出的间隔轮询查询接口，或等待回调通知；间隔太短容易触发限流。
- 下载并转存：结果地址通常有有效期，建议拿到后立即转存到自己的对象存储。
- 抽样复核：人工检查人物一致性、边缘处理和口型是否自然，再进入业务链路。
轮询逻辑示意（仅说明结构，字段名以文档为准）：
# 伪代码
job = submit(model=MODEL_NAME, input=SOURCE)
while not job.finished:
sleep(3)
job = query(job.id)
store(job.result_url)把万相-视频换人 视频生成API 接进生产环境时，建议给轮询加最大重试次数，并把每次请求的响应体按任务 ID 归档。换人任务一旦失败，日志里往往只有一行笼统的错误信息，能定位到具体素材的，通常是提交时自己留下的记录。
五、常见问题与排查顺序
- 401 / 403：先查 API Key 是否失效、鉴权头格式是否写错，再看请求是否被中间代理改写。
- 模型不存在：多为模型名称拼写不一致，或该模型并未出现在当前账号的可用列表中，需要回模型广场核对。
- 任务执行失败：优先检查素材可访问性与格式，其次看人物占比、遮挡比例是否超出模型适用范围。
- 长时间排队：换人类任务算力消耗较高，高峰期排队属正常现象，业务侧要有超时与降级策略。
需要对照实时模型列表、接口地址与消耗说明时，可以直接到 通联官网 的控制台与文档页面查看，那里的信息通常是更新最及时的来源。
六、上线前建议做的三件事
第一，把 Key、Base URL、模型名称收进配置中心，避免散落在多份代码里。第二，为异步任务建立失败重试与素材清理机制，防止无效文件堆积。第三，用同一批素材对比两到三个候选模型，从人物一致性、边缘自然度和单次耗时三个维度打分，再决定线上使用哪一个。
视频换人是一个对素材和参数都敏感的环节。稳妥的做法不是一次调到最好，而是先把最小可用链路跑通，再用版本化对比逐步优化。
链路跑通之后，下一步就是把 Key、Base URL 与模型名称落到真实项目里。可以到通联AI中转站注册账号，在控制台查看可用模型、获取 API Key，并用最小请求体完成一次换人任务测试。