Muapi 的角色一致性 API 可以将一张或多张参考图转化为可重复使用的图像或视频主体。你可以比较轻量的单参考图模型、更大的参考图集合，以及多模态参考图转视频端点，而无需分别接入每个供应商。
Seedance 2.5 Omni Reference
高容量参考端点，适合复杂角色集合和多场景视频连续性。
什么是角色一致性 API？
角色一致性 API 使用一张或多张参考图，在新的场景、姿势、服装和镜头角度中复现同一个主体。图像参考模型适合角色设定图和静帧；参考图转视频模型则可以让该身份进入动态镜头。
Muapi 通过同一套 REST 提交与轮询流程提供这两类能力。你可以按参考图数量、输入模态、价格，以及最终需要图像还是视频来选择模型。
核心能力
图像参考生成
将角色源图转换为新的静帧，同时尽量保留面部特征、服装和视觉身份。
参考图转视频
使用支持视频输出、动作和场景指导的模型，让参考主体进入新的镜头。
已验证的参考图数量限制
目录会展示每个模型的实际参考图上限，从 1 张到最多 30 张不等。
多模态参考
当身份还包含动作、声音或时间信息时，使用同时接受图像、视频或音频的端点。
任务类型提示
明确传入模型要求的任务类型和参考图字段，减少异步任务失败并便于重试。
按次生成付费
先用免费或低成本图像参考迭代，只有在镜头确实需要时再切换到高级视频模型。
代表性角色一致性模型对比
| 模型 | 供应商 | 价格 | 适合场景 |
|---|---|---|---|
| MiniMax Subject Reference | MiniMax | $0.01/次生成 | 最低成本的单图参考 |
| Ideogram Character | Ideogram | $0.15/次生成 | 一致的插画或写实静帧 |
| Seedance 2 Character | ByteDance | $0.18/次生成 | 一到三张参考图 |
| Gemini Omni Character | 免费 | 免费的多模态图像参考 | |
| Vidu Q2 Reference | Vidu | $0.065/次生成 | 最多七张参考图转视频 |
| Wan 3.0 Reference to Video | Alibaba | $0.50/次生成 | 视频的大规模参考图集合 |
| Veo 3.1 Reference to Video | $0.60/次生成 | 高级电影感参考镜头 | |
| Seedance 2.5 Omni Reference | ByteDance | $1.70/次生成（720p） | 复杂多模态集合和连续性 |
参考图数量、支持的模态和价格因模型而异。提交生产请求前，请先查看各模型的 Playground Schema。
如何调用角色一致性 API
- 选择图像或视频模型。 根据输出类型、参考图数量、输入模态和预算选择模型。
- 托管参考文件。 通过 POST /api/v1/upload_file 上传源图，或使用所选端点接受的公开可访问 URL。
- 发送任务类型字段。 调用 POST /api/v1/{model-slug}，传入 images_list、提示词以及模型要求的参考图或任务类型字段。
- 轮询并保存结果。 持续检查 GET /api/v1/predictions/{request_id}/result，直到任务完成，然后保存返回的图像或视频。
curl -X POST https://api.muapi.ai/api/v1/seedance-2.5-omni-reference \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"images_list": [
"https://example.com/character-front.jpg",
"https://example.com/character-side.jpg"
],
"prompt": "the character walking through a neon-lit city street at night",
"omni_reference_task_type": "reference",
"duration": 5,
"aspect_ratio": "16:9"
}'import requests
response = requests.post(
"https://api.muapi.ai/api/v1/seedance-2.5-omni-reference",
headers={"x-api-key": "YOUR_API_KEY"},
json={
"images_list": [
"https://example.com/character-front.jpg",
"https://example.com/character-side.jpg",
],
"prompt": "the character walking through a neon-lit city street at night",
"omni_reference_task_type": "reference",
"duration": 5,
"aspect_ratio": "16:9",
},
)
request_id = response.json()["request_id"]
result = requests.get(
f"https://api.muapi.ai/api/v1/predictions/{request_id}/result",
headers={"x-api-key": "YOUR_API_KEY"},
)
print(result.json())常见问题
应该发送多少张参考图？
使用能够说明主体特征的最小参考集合。单参考图模型需要 1 张，而视频模型可能根据 Schema 接受 3、7、10 或 30 张。
角色一致性模型可以生成视频吗？
可以。Vidu Q2、Wan 3.0、Veo 3.1、Kling O1、MiniMax H3 和 Seedance Omni 都提供参考图转视频选项。
可以使用视频或音频作为参考吗？
部分多模态端点除了图像外还接受视频或音频。发送这些字段前，请先查看所选模型的输入 Schema。
为什么我的异步参考任务失败了？
常见原因包括参考图数量不支持、字段名称错误、URL 无法访问或缺少模型要求的任务类型。请检查 Playground Schema，并尝试减少参考图数量后重试。
角色一致性生成需要多少钱？
代表性价格从免费和每次 $0.01 的图像参考，到 $1.70 的高容量 720p 视频参考请求不等。最终费用由模型和参数决定。
所有参考模型都能使用同一个 API 密钥吗？
可以。Muapi 的图像和视频参考目录使用同一个 API 密钥，以及相同的提交与轮询模式。