把 Wan-Dancer 封装成本地 HTTP 服务后，上游业务系统最常遇到的问题不是模型推理本身，而是 JSON 字段名不一致、图片数据格式不匹配、以及请求超时被误判为服务故障。以下按本地接入的实际顺序给出可执行的请求格式整理、字段映射、错误体设计和重试策略，每个环节都附上可直接替换的配置或代码片段。

处理方向：在 Wan-Dancer 前加一个无状态中间层，统一接收上游 JSON，转换成 Wan-Dancer 本地服务要求的参数格式；图片字段统一走 base64 传入；错误响应必须区分 400 与 500；超时和重试只针对网络层，不替代模型推理质量排查。适用条件：上游业务系统不能直接修改字段名，Wan-Dancer 服务本机运行。验证方式：用固定的测试输入调用中间层，观察返回结果和错误码。

先明确 Wan-Dancer 本地接口接收的原始参数

做字段映射前，先把 Wan-Dancer 服务启动起来，用最小请求确认本地服务真正需要的参数。通常 Wan-Dancer 本地接口接收的请求类似：

POST http://127.0.0.1:8000/dance
data: {"source_image": "/tmp/input.png", "pose_video": "/tmp/pose.mp4", "seed": 42}

其中 source_image 为人像图片本地路径，pose_video 为参考动作视频本地路径，seed 为随机种子。实际字段名和取值需要以本地仓库 README 或启动时打印的参数说明为准。这里要做的不是猜字段，而是先用一个最小请求跑通，记录服务实际接受的字段名、类型（字符串路径、整数、浮点数）以及是否可留空。把这些原始字段记录下来，后端的映射表才有依据。

设计中间层字段映射表

上游业务系统传来的 JSON 往往包含自有业务字段，例如 user_id、pic_url、motion_file。中间层负责把这些字段名翻译成 Wan-Dancer 需要的名称，同时做类型转换。建议把映射规则写成一个独立配置，不要硬编码在业务代码里。下面是一份可参考的映射表：

实际实现时，中间层先检查必填字段是否存在，再做类型转换。转换失败时直接返回参数错误，不要继续调用 Wan-Dancer。这样能让调用方更快发现是上游字段问题，而不是模型问题。

处理图片二进制与 base64 编码的转换

上游系统经常把图片以 base64 字符串放在 JSON 里，而 Wan-Dancer 需要的是文件路径。中间层要做两件事：解码、写临时文件。下面这段代码将 base64 字符串解码并写入临时输入文件：

import base64, tempfile, os

def decode_b64_to_temp(b64_str, suffix=".png"):
    try:
        image_bytes = base64.b64decode(b64_str, validate=True)
        if not image_bytes:
            raise ValueError("decode result empty")
        fd, path = tempfile.mkstemp(suffix=suffix, prefix="winput_")
        with os.fdopen(fd, "wb") as f:
            f.write(image_bytes)
        return path
    except (base64.binascii.Error, ValueError) as e:
        raise ValueError(f"base64 decode failed: {e}")

编码失败的判断方法：base64.b64decode 会抛异常，但更隐蔽的情况是解码成功但字节内容不是合法图片。建议解码后加一个最小校验，比如检查 PNG/JPEG 文件头，或仅判断文件大小是否大于 0。如果上游传的是 URL，则先下载再写本地文件，这样 Wan-Dancer 只接触 local path，减少它的输入格式分支。

用统一错误体区分参数错误和运行错误

下游排障时最怕看到“Request failed”这类信息。中间层应该把错误结构统一为以下格式：

{"error": {"code": "VALIDATION_ERROR", "message": "pic_url missing", "details": {}}}

code 用于机器判断，message 用于人工阅读。HTTP 状态码也需要区分：参数缺失、字段类型错误、base64 解码失败等，返回 400；Wan-Dancer 服务本身返回 5xx、模型加载失败、推理过程抛异常，则返回 500。建议在中间层捕获 Wan-Dancer 调用异常时，把底层错误信息放进 details，但不要把全部堆栈直接返回给上游，避免内部路径泄露。

从响应里区分 400 与 500 类错误时，可以直接看 HTTP 状态码，但更可靠的是看 error.code。因为有些网关会把 4xx 包装成 200。建议让中间层强制返回标准状态码，这样上游的监控系统能够准确告警。

增加超时和重试机制适配不稳定环境

视频生成推理耗时长，中间层如果只设置几秒超时，很容易把正常的长时间推理当成失败。建议将读超时设置得比预期推理时间更长，例如设置 300 秒或 600 秒，具体数值需要结合本机 GPU 性能和输入视频长短调整。下面是一个配置示例：

# 中间层配置（JSON 或 YAML）
{
  "timeout": {
    "connect": 5,
    "read": 600
  },
  "retry": {
    "max_retries": 2,
    "retry_on": ["connection_error", "timeout"],
    "backoff": 1.0
  }
}

重试策略要谨慎：当 Wan-Dancer 返回 4xx 时不要重试，因为参数错误重试多少次都没用；只有当连接断开、读超时、或返回 5xx 时才重试。重试间隔建议使用指数退避，比如第一次等 1 秒，第二次等 2 秒。验证重试是否生效，可以给中间层配一个指向不存在端口的测试地址，然后观察日志中是否出现两次重试记录，以及每次时间间隔是否符合预期。不要用 kill 掉 Wan-Dancer 进程这种粗暴方式来测试，因为那样可能掩盖中间层对进程退出和端口连接失败的处理差异。

完成以上五个步骤后，上游只需要面对中间层这一套稳定的请求 / 响应格式，Wan-Dancer 自身字段变化也被隔离在中间层内部。后续 Wan-Dancer 升级时，只需修改映射表和适配代码，不需要上游业务系统跟着改。