HY-Motion 1.0代码实例：Python调用API生成FBX格式动作文件

美丽回忆一瞬间

270人浏览 · 2026-02-22 02:05:39

美丽回忆一瞬间 · 2026-02-22 02:05:39 发布

HY-Motion 1.0代码实例：Python调用API生成FBX格式动作文件

1. 开篇：让文字描述变成3D动画

想象一下，你只需要用简单的文字描述，比如"一个人做深蹲然后举重"，就能立即生成一个专业的3D角色动画，而且还是FBX格式——这是游戏开发和动画制作中最常用的格式。这就是HY-Motion 1.0带给我们的神奇能力。

作为一个专注于3D动作生成的AI模型，HY-Motion 1.0基于最先进的Diffusion Transformer和流匹配技术，能够将你的文字描述转化为流畅自然的骨骼动画。无论你是游戏开发者、动画师，还是只是对3D技术感兴趣的爱好者，这个工具都能大大简化你的工作流程。

今天，我将带你一步步学习如何用Python调用HY-Motion 1.0的API，生成可以直接用在各种3D软件中的FBX动作文件。不需要深厚的机器学习背景，只要会写简单的Python代码，你就能掌握这个强大的工具。

2. 环境准备与安装

在开始编写代码之前，我们需要先准备好运行环境。HY-Motion 1.0对硬件有一定要求，但配置过程并不复杂。

2.1 系统要求

首先确保你的设备满足以下最低要求：

操作系统：Ubuntu 20.04或更高版本，Windows 10/11，macOS 12+
GPU：NVIDIA显卡，至少24GB显存（轻量版模型需要20GB）
Python：Python 3.8或更高版本
CUDA：CUDA 11.7或更高版本

如果你显存不够大，可以使用这些技巧来减少资源占用：

设置生成种子数为1（num_seeds=1）
文本描述控制在30个单词以内
生成的动作长度不超过5秒

2.2 安装必要的库

打开你的终端或命令行，用pip安装所需的Python包：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
pip install transformers diffusers huggingface_hub
pip install fbx-sdk-python  # 用于FBX文件处理

这些库分别用于深度学习计算、模型加载、以及FBX文件格式的处理。安装过程可能需要几分钟时间，取决于你的网络速度。

2.3 获取模型访问权限

HY-Motion 1.0的模型存储在HuggingFace平台上，你需要先申请访问权限：

访问HuggingFace HY-Motion页面
点击"Request access"申请权限
登录你的HuggingFace账户
等待权限批准（通常很快）

获得权限后，你需要在代码中配置HuggingFace的token：

from huggingface_hub import login

login(token="你的huggingface_token")  # 替换为你的实际token

3. 编写Python调用代码

现在来到最核心的部分——编写调用HY-Motion 1.0 API的Python代码。我将分步骤讲解每个重要的代码模块。

3.1 基础导入和设置

首先导入所有需要的库，并设置一些基础配置：

import torch
from diffusers import DiffusionPipeline
import numpy as np
from fbx import FbxManager, FbxExporter, FbxNode, FbxSkeleton, FbxAnimCurve, FbxTime
import os

# 设置设备（自动选择GPU或CPU）
device = "cuda" if torch.cuda.is_available() else "cpu"
print(f"使用设备: {device}")

# 创建输出目录
os.makedirs("output_animations", exist_ok=True)

3.2 加载HY-Motion模型

接下来加载HY-Motion 1.0模型。这里我们使用轻量版模型，因为它对显存要求更低：

def load_model(model_name="tencent/HY-Motion-1.0-Lite"):
    """
    加载HY-Motion模型
    model_name: 模型名称，可选标准版或轻量版
    """
    print("正在加载模型...")
    
    # 创建DiffusionPipeline
    pipe = DiffusionPipeline.from_pretrained(
        model_name,
        torch_dtype=torch.float16,  # 使用半精度减少显存占用
        variant="fp16"
    )
    
    # 将模型移动到GPU
    pipe = pipe.to(device)
    
    print("模型加载完成!")
    return pipe

# 加载模型
motion_pipe = load_model()

3.3 生成动作数据

这是最关键的步骤——根据文字描述生成3D动作数据：

def generate_motion(prompt, duration=5.0, num_seeds=1):
    """
    根据文本提示生成动作数据
    prompt: 动作描述文本（英文）
    duration: 动作时长（秒）
    num_seeds: 生成种子数
    """
    # 设置生成参数
    generator = torch.Generator(device=device).manual_seed(42)
    
    print(f"正在生成动作: {prompt}")
    
    # 调用模型生成动作
    with torch.autocast(device_type=device, dtype=torch.float16):
        output = motion_pipe(
            prompt=prompt,
            duration=duration,
            num_inference_steps=20,
            generator=generator,
            num_seeds=num_seeds
        )
    
    # 获取生成的动作数据（骨骼旋转和位置）
    motion_data = output.frames[0]  # 取第一个生成结果
    
    print("动作生成完成!")
    return motion_data

# 示例：生成一个深蹲举重动作
prompt = "A person performs a squat, then pushes a barbell overhead using the power from standing up"
motion_data = generate_motion(prompt, duration=4.5)

3.4 转换为FBX格式

将生成的动作数据转换为FBX文件，这是最实用的部分：

def create_fbx_animation(motion_data, output_path):
    """
    将动作数据转换为FBX动画文件
    motion_data: 生成的动作数据
    output_path: 输出文件路径
    """
    # 初始化FBX管理器
    manager = FbxManager.Create()
    scene = FbxScene.Create(manager, "AnimationScene")
    
    # 创建骨骼节点
    root_node = FbxNode.Create(manager, "Hips")
    scene.GetRootNode().AddChild(root_node)
    
    # 创建骨骼层级（简化的人体骨骼结构）
    bone_hierarchy = [
        "Hips", "Spine", "Spine1", "Spine2", "Neck", "Head",
        "LeftShoulder", "LeftArm", "LeftForeArm", "LeftHand",
        "RightShoulder", "RightArm", "RightForeArm", "RightHand",
        "LeftUpLeg", "LeftLeg", "LeftFoot", "LeftToeBase",
        "RightUpLeg", "RightLeg", "RightFoot", "RightToeBase"
    ]
    
    bones = {}
    for bone_name in bone_hierarchy:
        bone = FbxNode.Create(manager, bone_name)
        bones[bone_name] = bone
        if bone_name != "Hips":
            # 简单的父子关系设置（实际应根据解剖学设置）
            parent_name = "Hips" if "UpLeg" in bone_name or "Spine" in bone_name else "Spine2"
            bones[parent_name].AddChild(bone)
    
    # 创建动画栈和图层
    anim_stack = FbxAnimStack.Create(scene, "Animation")
    anim_layer = FbxAnimLayer.Create(scene, "BaseLayer")
    anim_stack.AddMember(anim_layer)
    
    # 为每个骨骼创建动画曲线
    num_frames = motion_data.shape[0]
    frame_rate = 30  # 假设30fps
    
    for frame_idx in range(num_frames):
        time = FbxTime()
        time.SetFrame(frame_idx, FbxTime.eFrames30)
        
        for bone_idx, bone_name in enumerate(bone_hierarchy):
            if bone_idx < motion_data.shape[1]:  # 确保不越界
                # 获取当前帧的骨骼变换数据
                rotation = motion_data[frame_idx, bone_idx, :3]  # 旋转
                position = motion_data[frame_idx, bone_idx, 3:6]  # 位置
                
                bone_node = bones[bone_name]
                
                # 设置旋转动画曲线
                anim_curve_x = bone_node.LclRotation.GetCurve(anim_layer, "X", True)
                anim_curve_y = bone_node.LclRotation.GetCurve(anim_layer, "Y", True) 
                anim_curve_z = bone_node.LclRotation.GetCurve(anim_layer, "Z", True)
                
                anim_curve_x.KeyModifyBegin()
                anim_curve_y.KeyModifyBegin()
                anim_curve_z.KeyModifyBegin()
                
                key_index = anim_curve_x.KeyAdd(time)
                anim_curve_x.KeySet(key_index, time, rotation[0])
                anim_curve_y.KeySet(key_index, time, rotation[1])
                anim_curve_z.KeySet(key_index, time, rotation[2])
                
                anim_curve_x.KeyModifyEnd()
                anim_curve_y.KeyModifyEnd()
                anim_curve_z.KeyModifyEnd()
    
    # 导出FBX文件
    exporter = FbxExporter.Create(manager, "")
    exporter.Initialize(output_path, -1, manager.GetIOSettings())
    exporter.Export(scene)
    exporter.Destroy()
    
    manager.Destroy()
    print(f"FBX文件已保存: {output_path}")

# 保存为FBX文件
output_path = "output_animations/squat_push.fbx"
create_fbx_animation(motion_data, output_path)

4. 完整代码示例

把上面的代码片段组合起来，就是一个完整的动作生成脚本：

# complete_motion_generation.py
import torch
from diffusers import DiffusionPipeline
from huggingface_hub import login
from fbx import FbxManager, FbxExporter, FbxNode, FbxAnimCurve, FbxTime
import os

# 1. 登录HuggingFace
login(token="你的token")

# 2. 设置设备
device = "cuda" if torch.cuda.is_available() else "cpu"

# 3. 加载模型
def load_model():
    pipe = DiffusionPipeline.from_pretrained(
        "tencent/HY-Motion-1.0-Lite",
        torch_dtype=torch.float16,
        variant="fp16"
    )
    return pipe.to(device)

# 4. 生成动作
def generate_motion(pipe, prompt, duration=5.0):
    generator = torch.Generator(device=device).manual_seed(42)
    output = pipe(
        prompt=prompt,
        duration=duration,
        num_inference_steps=20,
        generator=generator,
        num_seeds=1
    )
    return output.frames[0]

# 5. 主函数
def main():
    # 创建输出目录
    os.makedirs("output", exist_ok=True)
    
    # 加载模型
    print("加载模型中...")
    pipe = load_model()
    
    # 定义要生成的动作描述
    prompts = [
        "A person performs a squat, then pushes a barbell overhead",
        "A person climbs upward, moving up the slope",
        "A person stands up from the chair, then stretches their arms"
    ]
    
    # 为每个描述生成动作
    for i, prompt in enumerate(prompts):
        print(f"生成动作 {i+1}: {prompt}")
        motion_data = generate_motion(pipe, prompt, duration=4.0)
        
        # 保存为FBX（这里简化了FBX导出过程）
        output_path = f"output/motion_{i+1}.npy"
        np.save(output_path, motion_data.cpu().numpy())
        print(f"动作已保存: {output_path}")
    
    print("所有动作生成完成!")

if __name__ == "__main__":
    main()

5. 实际应用技巧

在实际使用HY-Motion 1.0时，有一些技巧可以帮助你获得更好的效果：

5.1 编写有效的动作描述

好的文字描述是生成高质量动作的关键：

保持简洁：尽量在60个单词以内描述清楚动作
使用英文：目前模型对英文的理解最好
具体明确：描述具体的肢体动作，而不是抽象概念
避免不支持的内容：不要描述动物、情绪、外观、场景或多人物

好的例子：

"一个人慢慢走路，然后突然转身"
"一个人做瑜伽的下犬式动作"
"一个人从地上捡起东西然后站起来"

不好的例子：

"一个快乐的人跳舞"（包含了情绪描述）
"一只猫在爬树"（非人形生物）
"两个人在打架"（多人物）

5.2 调整生成参数

通过调整一些参数，你可以控制生成动作的质量和风格：

# 高级生成参数设置
advanced_output = motion_pipe(
    prompt=prompt,
    duration=5.0,
    num_inference_steps=30,  # 更多步骤=更高质量但更慢
    guidance_scale=7.5,      # 控制与文本的贴合程度
    generator=generator,
    num_seeds=3              # 生成多个版本选择最好的
)

5.3 处理常见问题

在使用过程中可能会遇到的一些问题及解决方法：

问题1：显存不足

# 解决方案：使用更小的模型和设置
pipe = DiffusionPipeline.from_pretrained(
    "tencent/HY-Motion-1.0-Lite",  # 使用轻量版
    torch_dtype=torch.float16,      # 使用半精度
    variant="fp16"
)

问题2：生成动作不自然 尝试增加推理步数或调整提示词，使其更加具体明确。

问题3：FBX导入问题 确保你的3D软件支持FBX格式，并且骨骼命名符合软件的要求。