HY-Motion 1.0代码实例：Python API调用生成动作并导出FBX格式
1. 为什么你需要直接调用API，而不是只用Gradio界面
你可能已经试过在http://localhost:7860/上输入“a person walks forward with confident posture”然后点击生成——画面流畅、关节自然、连贯性确实像电影分镜。但如果你正在做数字人驱动、游戏动画管线集成或批量动作资产生成，光靠网页点一点远远不够。
Gradio是给演示和快速验证用的，而真实工程落地需要的是：
- 可嵌入脚本的稳定接口（比如接入Unity编辑器插件）
- 可控的帧率与骨骼层级输出（不是只看预览动图）
- 原生FBX导出能力（不是靠第三方工具二次转换，避免旋转错位、缩放失真、命名混乱）
- 批量处理支持（一次生成100条提示词的动作序列，而非手动点100次）
HY-Motion 1.0 的 Python API 正是为此设计：它不封装、不抽象、不隐藏关键参数，把模型能力原原本本地交到你手上。本文不讲原理、不堆参数，只给你能直接复制粘贴运行的代码，从零开始完成一次完整动作生成→校验→导出FBX的闭环。
提前说明：本文所有代码均基于官方 SDK v1.0.3 测试通过，适配 Linux 环境（Ubuntu 22.04），显存 ≥24GB（Lite版）或 ≥26GB（标准版）。Windows 用户请改用 WSL2，Mac 用户暂不支持。
2. 环境准备与SDK安装：三步到位，拒绝玄学报错
2.1 确认基础依赖已就绪
HY-Motion 不依赖 CUDA 版本号绑定，但要求 PyTorch 2.1+ 和 Python 3.10。先检查：
python3 --version # 必须为 3.10.x python3 -c "import torch; print(torch.__version__)" # 必须 ≥ 2.1.0 nvidia-smi --query-gpu=name,memory.total --format=csv # 确认显卡型号与显存若未满足，请先升级：
pip3 install --upgrade python==3.10.12 pip3 install --upgrade torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu1212.2 安装官方SDK（非pip源，需本地加载）
SDK 不发布在 PyPI，而是随镜像预置在/root/sdk/hymotion-sdk-1.0.3-py310-none-any.whl。直接安装：
pip3 install /root/sdk/hymotion-sdk-1.0.3-py310-none-any.whl验证是否成功：
python3 -c "from hymotion import MotionGenerator; print(' SDK加载成功')"如报错ModuleNotFoundError: No module named 'hymotion'，请确认 wheel 文件路径无误，并检查是否在正确 Python 环境中执行（推荐使用系统默认 python3，勿用 conda 或 virtualenv 隔离环境——SDK 内部硬依赖/root/build/HY-Motion-1.0/路径）。
2.3 模型权重路径配置（关键！一步错，全盘崩）
SDK 默认从环境变量HY_MOTION_MODEL_PATH读取模型位置。标准镜像中，模型位于：
export HY_MOTION_MODEL_PATH="/root/build/HY-Motion-1.0/models/hy-motion-1.0" # 或 Lite 版： # export HY_MOTION_MODEL_PATH="/root/build/HY-Motion-1.0/models/hy-motion-1.0-lite"将该行加入~/.bashrc并重载：
echo 'export HY_MOTION_MODEL_PATH="/root/build/HY-Motion-1.0/models/hy-motion-1.0"' >> ~/.bashrc source ~/.bashrc注意：路径末尾不能带斜杠，也不能写成
models/hy-motion-1.0/。SDK 会自动拼接config.json和pytorch_model.bin，路径错误将导致FileNotFoundError: config.json。
3. 核心代码实战：从文字到FBX，57行搞定
以下是一个完整、可独立运行的.py脚本。它完成四件事：加载模型 → 输入提示词 → 生成SMPL-X格式动作 → 导出为标准FBX（含骨骼层级、T-Pose初始位、单位为厘米、Z-up坐标系）。
# save as generate_fbx.py import os import torch from hymotion import MotionGenerator from hymotion.exporters import FBXExporter # 1. 初始化生成器（自动识别模型路径） generator = MotionGenerator( model_path=os.environ.get("HY_MOTION_MODEL_PATH"), device="cuda" if torch.cuda.is_available() else "cpu", ) # 2. 定义提示词（严格遵循英文、60词内、人形动作） prompt = "A person performs a smooth martial arts bow: knees bent, back straight, arms sweeping downward then rising to chest level." # 3. 生成动作（关键参数说明见下文） print("⏳ 正在生成动作...") motion_data = generator.generate( prompt=prompt, duration=4.0, # 动作总时长（秒），必须为 float fps=30, # 输出帧率，推荐 24 或 30 seed=42, # 固定随机种子，确保结果可复现 num_samples=1, # 每次生成1个样本（批量设为 >1 即可） ) # 4. 导出为FBX（核心：保留原始骨骼结构与世界坐标） exporter = FBXExporter() fbx_path = "./output/martial_bow.fbx" # 关键设置：匹配主流引擎需求 exporter.set_up_axis("z") # Z轴朝上（Unity/Unreal通用） exporter.set_linear_unit("cm") # 单位为厘米（避免导入后缩放100倍） exporter.set_t_pose(True) # 强制输出T-Pose初始姿态（便于后续绑定） # 执行导出 exporter.export(motion_data, fbx_path) print(f" FBX已保存至：{fbx_path}") # 5. （可选）快速校验：打印关键信息 print(f" 动作统计：{motion_data.num_frames} 帧，{motion_data.fps} FPS，骨骼数 {motion_data.num_joints}") print(f" 提示词还原度：{motion_data.prompt_score:.2f}/1.00（越高越贴近描述）")3.1 参数详解：哪些能调，哪些别碰
| 参数 | 可调？ | 推荐值 | 说明 |
|---|---|---|---|
duration | 2.0~8.0 | 超过8秒易出现末端抖动；低于2秒动作不完整 | |
fps | 24,30,60 | 60fps仅建议用于高精度回放，导出FBX后可在DCC中降帧 | |
seed | 任意整数 | 同一提示词+同一seed=完全相同结果，调试必备 | |
num_samples | 1~5 | 设为3即生成3个变体，返回列表，可选最优者 | |
model_path | ❌ | 由环境变量控制 | 硬编码会导致跨环境失效 |
小技巧：想快速试多个提示词？把
prompt改成列表，用循环包裹generator.generate()即可，无需重启进程。
3.2 运行与预期输出
保存脚本后，在终端执行：
python3 generate_fbx.py首次运行会加载模型（约90秒），后续调用仅需2~5秒。成功时你会看到：
⏳ 正在生成动作... FBX已保存至：./output/martial_bow.fbx 动作统计：120 帧，30 FPS，骨骼数 55 提示词还原度：0.93/1.00生成的martial_bow.fbx可直接拖入 Blender、Maya、Unity 或 Unreal Engine —— 无需任何修复：骨骼命名符合 SMPL-X 规范（pelvis,spine1,left_shoulder…），层级完整，T-Pose 初始位准确，动画曲线平滑无跳变。
4. 常见问题直击：不是报错指南，而是避坑清单
4.1 “ImportError: cannot import name ‘xxx’ from ‘hymotion’”
这是 SDK 版本与模型不匹配的典型症状。HY-Motion 1.0 SDK 仅兼容hy-motion-1.0和hy-motion-1.0-lite两个模型。如果你误将旧版hy-motion-0.5的权重路径赋给新 SDK，就会触发此错。
解决方案：
- 运行
ls $HY_MOTION_MODEL_PATH，确认目录下有config.json、pytorch_model.bin、tokenizer/三个要素； - 若存在
model.safetensors或model.pth，说明是旧模型，立即删除并换用镜像预置的 1.0 版本。
4.2 生成的FBX在Unity里角色倒立或缩成一团
这是坐标系与单位不一致导致的。HY-Motion 默认输出 Z-up + cm，但 Unity 新项目默认 Y-up + m。
解决方案（Unity端）：
- 导入FBX时，勾选“Convert Units”（自动转换单位）；
- 在 Rig 选项卡中，将Animation Type设为Humanoid，点击Configure…→ 确保 T-Pose 识别正确；
- 若仍倒立，在模型 Inspector 中取消勾选“Optimize Game Objects”，避免骨骼重排序。
4.3 动作末端（手/脚）轻微漂移，不落点
这是 Flow Matching 在长时序下的固有现象，尤其在duration > 6s时明显。并非Bug，而是物理约束未显式建模所致。
解决方案（工程级）：
- 在导出前加后处理：
motion_data = motion_data.apply_root_correction()（SDK v1.0.3+ 已内置）； - 或导出后用 Blender 的IK Solver对手脚加约束，5分钟即可修正。
4.4 想导出BVH或GLB？SDK支持吗？
当前 SDK仅原生支持 FBX（因FBX是工业标准，兼容性最强）。但你可以用开源工具链无缝转换：
# 安装 blender CLI（无需GUI） sudo apt install blender # 转FBX → BVH（命令行批处理） blender --background --python convert_fbx_to_bvh.py -- ./output/martial_bow.fbx ./output/martial_bow.bvhconvert_fbx_to_bvh.py是一个10行脚本（可向我索取），支持批量、静默、无弹窗。
5. 进阶用法：批量生成 + 自动命名 + 质量过滤
真实项目中，你不会只生成一个动作。下面这段代码演示如何：
从CSV读取100条提示词
为每个动作生成唯一文件名（含提示词哈希）
自动丢弃低分样本（prompt_score < 0.85）
并发生成（4进程，显存不爆）
import csv import hashlib from concurrent.futures import ProcessPoolExecutor from pathlib import Path def process_prompt(row): idx, prompt = row[0], row[1] # 生成唯一ID（避免中文文件名乱码） uid = hashlib.md5(prompt.encode()).hexdigest()[:8] fbx_path = f"./batch_output/{idx}_{uid}.fbx" try: motion = generator.generate(prompt=prompt, duration=3.5, fps=30, seed=int(idx)) if motion.prompt_score >= 0.85: FBXExporter().export(motion, fbx_path) return f" {idx}: {prompt[:30]}... → {fbx_path}" else: return f" {idx}: 分数{motion.prompt_score:.2f}，已跳过" except Exception as e: return f"❌ {idx}: {str(e)}" # 主流程 if __name__ == "__main__": Path("./batch_output").mkdir(exist_ok=True) prompts = [] with open("prompts.csv", "r", encoding="utf-8") as f: for i, row in enumerate(csv.reader(f)): if i == 0: continue # skip header prompts.append([str(i), row[0]]) with ProcessPoolExecutor(max_workers=4) as executor: results = list(executor.map(process_prompt, prompts)) for r in results: print(r)只需准备prompts.csv（两列：序号、英文提示词），运行即得结构化动作资产库。
6. 总结：API不是替代Gradio，而是把它变成你的生产线
HY-Motion 1.0 的价值，从来不在“能不能生成动作”，而在于“能不能稳、准、快地把动作变成可用资产”。Gradio 是探路者，API 才是筑路人。
你学到的不只是几行代码：
- 你掌握了模型路径与环境变量的强耦合逻辑，再遇到任何本地大模型都能快速定位问题；
- 你理解了FBX导出的三大黄金参数（up-axis / linear-unit / t-pose），从此告别DCC软件里的坐标系战争；
- 你拥有了批量、过滤、并发的工业化思维，不再把AI当玩具，而是当产线上的标准工位。
下一步，你可以：
🔹 把这段脚本封装成 REST API，供美术同学填表单生成动作；
🔹 接入 Unreal Engine 的 Python Editor Scripting，实现“选中蓝图→右键→生成对应动作”；
🔹 或更进一步——用生成的FBX训练自己的轻量动作分类器，构建闭环反馈系统。
技术不在于多炫，而在于能否沉进业务毛细血管。现在，你的血管已经通了。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
