如何使用 角色替换 – 视频生成 API：character swap接入指南（2026）
角色替换 – 视频生成 API 接入教程：参数说明、价格与可直接运行的调用代码，先在 Playground 试玩再一行代码接入。
角色替换 – 视频生成 是一款character swap模型（由 NamiFusion 提供）：用 Wan2.2-Animate 将视频中选定人物替换为参考图人物，保留原始音轨。在 NamiFusion 上可以在 Playground 直接试玩（提交前显示准确报价），再通过统一 REST API 一行代码接入，典型一次调用约 $0.750。
TL;DR
· 任务类型：character swap，由 NamiFusion 提供
· 价格：典型一次调用约 $0.750（$1 = 100 积分），按量计费无订阅
· 上手路径：Playground 试玩（提交前显示报价）→ API Keys 建密钥 → 一个 POST 接入
· 可调参数：4 个（见下方参数表）
· 无平台水印，商用可用（遵守服务条款）
用 角色替换 – 视频生成 能做什么？
内容生产自动化：把该模型接入你的工作流，用统一 API 按量调用。
怎么调用这个 API？
- 在 NamiFusion 注册并在 API Keys 页面创建密钥（注册赠送积分仅可用于指定模型）。
- 用下面的 cURL 示例提交任务，Header 带上 Bearer 密钥。
- 用返回的 task_uuid 轮询任务状态，完成后取输出 URL。
# 1) Submit — returns { "task_uuid": "..." }
curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/character-swap/generate" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"track_manifest_url": "ANALYZE_OUTPUT.track_manifest_url",
"mappings": [
{
"obj_id": 0,
"img_urls": [
"https://assets-public.namifusion.com/marketplace/images/2026-06-12/638e1ee18ac7.jpeg"
]
}
],
"resolution": "720p"
}
}'
# 2) Poll until status is "completed", then read the output URLs
curl "https://www.namifusion.com/api/v1/marketplace/run/tasks/TASK_UUID" \
-H "Authorization: Bearer YOUR_API_KEY"有哪些参数？
track_manifest_url（Track manifest URL）：必填
mappings（人物映射）：必填
resolution（分辨率）：可选，默认 "720p"
seed（随机种子）：可选
价格是多少？
按次积分计价，典型一次调用约 $0.750（$1 = 100 积分），实际价格随参数（分辨率/时长等）变化，Playground 里提交前会显示准确报价。
角色替换 – 视频生成
将分析后视频中的指定人物替换为参考角色，并保留原始音轨。
Character Swap Generate 是两阶段工作流的第二步。它使用 Analyze 返回的 track_manifest_url 和 obj_id，再通过 mappings 为每个选定人物分配 1 至 3 张参考图片。video_url 必须与分析阶段使用的视频完全相同，并且两个阶段的分辨率必须保持一致。
核心特性
- 按人物精确替换：使用 Analyze 返回的
obj_id明确选择每个替换目标。 - 支持多人物映射：在
mappings中添加多个项目，分别配置视频中的不同人物。 - 每人 1 至 3 张参考图：可提供多个外观参考，补充不同角度和人物细节。
- 保留原始音频：生成结果会维持输入视频的原始音轨。
- 480p / 720p 输出：可按目标质量和现有价格档位选择分辨率。
技术规格
| 项目 | 说明 |
|---|---|
| 工作流 | Character Swap 第 2 步 |
| 必填输入 | video_url、track_manifest_url、mappings |
mappings 格式 | {obj_id, img_urls} 对象数组 |
| 参考图片 | 每个人物 1 至 3 个 URL |
| 分辨率 | 480p、720p（默认） |
| 视频上限 | 30 秒 |
| 可选输入 | seed |
| 输出 | 保留原始音频的视频 URL |
基本流程
- 使用 Character Swap Analyze 处理源视频。
- 从返回的
objects中选择需要替换的obj_id。 - 在
mappings中为每个 ID 配置对应的参考图片 URL。 - 提交同一视频和 Analyze 返回的清单，并轮询到生成完成。
常见问题
可以先免费试用吗？+
注册赠送积分仅可用于指定模型，适用范围会持续更新；Playground 提交前会显示准确报价。
生成内容可以商用吗？有水印吗？+
可以商用，NamiFusion 不给生成结果加平台水印；使用须遵守服务条款与适用法律。
内容政策是什么？+
色情内容、涉及未成年人的性化内容、未经授权使用真人、欺骗性冒充、诈骗与虚假代言均禁止。合法、自愿且非露骨的成年人主题可能被允许，详见服务条款。
角色替换 – 视频生成 的任务要跑多久？+
取决于参数，图像通常数秒到数十秒，视频通常数十秒到几分钟；API 返回 task_uuid 供轮询。
分辨率/时长上限是多少？+
以模型参数表为准：每个模型的可选分辨率、时长档位都在上方参数说明与 Playground 中列出。