Hunyuan3D-2 REST API 服务实战api_server.py 的启动参数、请求协议与源码级解析【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2本文基于 Hunyuan3D-2 仓库中 docs/source/started/api.md 的 API 使用说明展开结合 api_server.py 的完整源码讲清如何把 Hunyuan3D-2 的图生 3D / 已有网格上色能力封装为一个本地 FastAPI 服务。读完后你可以独立启动服务、构造合法的生成请求同步与异步两种模式并理解每个请求字段在源码中对应的默认值与处理流程。一、能力定位一个把 3D 生成模型变成 HTTP 端口的服务官方文档对 API 服务的定位是在本地启动一个 API server然后通过 HTTP POST 请求完成三类操作——图片转 3D、文本转 3D、给已有网格上色texturing existing mesh等等。从源码结构看这套服务并不是独立实现了一套推理逻辑而是把仓库中现成的推理管线封装进了 FastAPI形状生成使用Hunyuan3DDiTFlowMatchingPipeline定义于 hy3dgen/shapegen/pipelines.py默认加载tencent/Hunyuan3D-2mini仓库下的hunyuan3d-dit-v2-mini-turbo子文件夹权重并启用 FlashVDM 加速纹理生成使用Hunyuan3DPaintPipeline定义于 hy3dgen/texgen/pipelines.py默认加载tencent/Hunyuan3D-2输入图片会先经过BackgroundRemover基于 rembg做背景去除见 api_server.py 的导入与 api_server.py 的实例化。值得注意的是Blender Addon 依赖的正是这个 API 服务——docs/source/started/blender.md 中明确写道With an API server launched, you could also directly use Hunyuan3D 2.0 in your blender。也就是说本地 Blender 插件本质上是这个 HTTP 服务的一个客户端。二、启动服务命令与完整参数表2.1 基本启动命令与原文档一致最基本的启动方式为python api_server.py --host 0.0.0.0 --port 8080服务由 uvicorn 承载api_server.py 末尾调用uvicorn.run(app, hostargs.host, portargs.port, log_levelinfo)依赖的fastapi、uvicorn已包含在 requirements.txt 的 Demo only 分组中执行pip install -r requirements.txt即可满足 Web 层依赖模型推理本身的依赖torch、diffusers、trimesh 等同样在该文件中。2.2 命令行参数以源码 argparse 定义为准api_server.py 中argparse定义了如下参数。注意两处与直觉不同的默认值参数类型默认值说明--hoststr0.0.0.0监听地址0.0.0.0表示允许局域网内其他机器访问--portint8081监听端口。注意源码默认是 8081而文档示例显式指定 8080两者不一致时以显式传参为准--model_pathstrtencent/Hunyuan3D-2mini形状生成模型仓库支持 Hugging Face 仓库名--tex_model_pathstrtencent/Hunyuan3D-2纹理生成模型仓库--devicestrcuda推理设备--limit-model-concurrencyint5创建了一个asyncio.Semaphoreapi_server.py用于限制模型并发并影响/generate返回的排队信息计算--enable_texflag关传入该标志才会在启动时加载Hunyuan3DPaintPipelineapi_server.py。不加载时请求中传texture会因self.pipeline_tex不存在而报错需要说明的两点适用前提纹理功能除--enable_tex外还需要按 README.md 的 Install Requirements 一节额外编译安装两个本地扩展hy3dgen/texgen/custom_rasterizer与hy3dgen/texgen/differentiable_renderer下的setup.py install否则Hunyuan3DPaintPipeline的加载/推理会缺少 C/CUDA 依赖。源码中ModelWorker.__init__里文生图管线HunyuanDiTPipeline的加载代码目前处于注释状态api_server.py。从源码结构看text输入分支api_server.py引用了未实例化的self.pipeline_t2i因此在当前版本的仓库里文本转 3D 这条路径实际上不会走通建议以图片输入作为主要使用方式。三、请求协议字段、默认值与两种调用模式3.1 同步接口 POST /generate/generate处理器位于 api_server.py接收 JSON生成完成后直接以FileResponse返回二进制模型文件。原文档给出的最简示例图生 3D、不带纹理如下img_b64_str$(base64 -i assets/demo.png) curl -X POST http://localhost:8080/generate \ -H Content-Type: application/json \ -d { image: $img_b64_str, } \ -o test2.glb请求体是一个 JSON 对象image字段为图片的 Base64 字符串服务端用base64.b64decode解码后交给 PIL 打开见 api_server.py。assets/demo.png 是仓库自带的示例输入图。一个可组合的完整请求示例开启纹理、指定随机种子与面数上限img_b64_str$(base64 -i assets/demo.png) curl -X POST http://localhost:8080/generate \ -H Content-Type: application/json \ -d { \image\: \$img_b64_str\, \texture\: true, \seed\: 1234, \octree_resolution\: 128, \num_inference_steps\: 5, \guidance_scale\: 5.0, \face_count\: 40000, \type\: \glb\ } \ -o textured.glb提示文档中的base64 -i是 BSD/macOS 写法在 GNU/Linux 上等价于base64 -w 0 assets/demo.png-w 0表示不换行。/generate支持的请求字段及源码中的处理逻辑api_server.py如下表字段类型默认值说明imagestr无必填或给text图片的 Base64 字符串服务端解码后经BackgroundRemover去背景并作为形状生成或纹理生成的条件输入textstr无文本输入走文生图管线如 2.2 节所述当前源码中该管线加载被注释此路径暂不可用meshstr无已有网格 GLB 文件的 Base64 字符串。提供后跳过形状生成直接加载该网格trimesh.load(..., file_typeglb)api_server.py对应文档所说的 Texturing existing mesh此时应同时提供image作为上色条件textureboolfalse为true时对网格先执行FloaterRemover→DegenerateFaceRemover→FaceReducer默认face_count40000再调用Hunyuan3DPaintPipeline上色api_server.pyseedint1234通过torch.Generator(device).manual_seed(seed)注入保证结果可复现octree_resolutionint128体素/八叉树表面重建分辨率越高细节越多、耗时越长num_inference_stepsint5扩散采样步数guidance_scalefloat5.0无分类器引导强度face_countint40000纹理前FaceReducer的目标面数上限见 hy3dgen/shapegen/postprocessors.pytypestrglb输出文件格式后缀同时决定临时文件后缀与gradio_cache/{uid}.{type}的落盘文件名关于num_inference_steps与octree_resolution的取值值得注意一个双层默认值现象Hunyuan3DDiTFlowMatchingPipeline.__call__在 hy3dgen/shapegen/pipelines.py 中的管线级默认值是num_inference_steps50、octree_resolution384、guidance_scale7.5而 API 服务层把它们改成了5 / 128 / 5.0api_server.py。这是因为 API 默认加载的是 mini turbo 蒸馏权重并强制开启了enable_flashvdm(mc_algomc)api_server.py对应管线中的 hy3dgen/shapegen/pipelines.py面向的是低步数、快响应的在线服务场景如果你改用完整Hunyuan3D-2权重更低的步数/分辨率并不一定合适需要自行在请求中调整。请求处理失败时ValueError、torch.cuda.CudaError或任何未知异常/generate不会返回二进制流而是返回 HTTP 404 与 JSON 错误体形如{text: 错误提示, error_code: 1}api_server.py。客户端判断成功与否应以响应是否为二进制 GLB 文件或 HTTP 状态码为准。3.2 异步接口 POST /send 与 GET /status/{uid}对于耗时较长的生成任务api_server.py 还暴露了一组轮询式异步接口文档正文未提及但属于同一服务的组成部分POST /send请求体字段与/generate完全相同但任务在后台线程中执行threading.Thread(targetworker.generate, ...)接口立即返回{uid: uuid}api_server.pyGET /status/{uid}按 uid 轮询。产物文件gradio_cache/{uid}.glb不存在时返回{status: processing}存在时返回{status: completed, model_base64: GLB 的 Base64}api_server.py。# 1. 提交任务 uid$(curl -s -X POST http://localhost:8080/send \ -H Content-Type: application/json \ -d {\image\: \$img_b64_str\} | python3 -c import sys,json;print(json.load(sys.stdin)[uid])) # 2. 轮询状态 curl -s http://localhost:8080/status/$uid # 未完成{status:processing} # 已完成{status:completed,model_base64:...}异步接口返回的是 Base64 编码的网格适合浏览器或无文件写入权限的前端直接消费同步接口则直接落盘二进制文件适合脚本与 Blender Addon 这类文件型客户端。四、ModelWorker 内部流程一次请求经历了什么把 api_server.py 中ModelWorker的关键代码串起来一次/generate请求的完整处理链路如下输入解析从params读取imageBase64 → PIL或走text生图分支再经self.rembg(image)去除背景api_server.py。若提供了mesh字段则从 Base64 解码为trimesh对象跳过后续形状生成。形状生成仅当未提供mesh将seed、octree_resolution、num_inference_steps、guidance_scale填入params并把mc_algo固定为mcMarching Cubesapi_server.py随后调用self.pipeline(**params)[0]得到 trimesh 网格。管线内部会做 Flow Matching 采样、CFG 组合hy3dgen/shapegen/pipelines.py最后由 VAE 按八叉树体素重建表面并导出为trimesh.Trimeshhy3dgen/shapegen/pipelines.py。纹理生成仅当texturetrue依次执行三个后处理器——FloaterRemover去除悬空碎片、DegenerateFaceRemover去除退化面、FaceReducer把面数压到face_count上限三者均基于 pymeshlab 实现见 hy3dgen/shapegen/postprocessors.py——压面是为了让后续 UV 展开与纹理合成在可控规模上进行然后self.pipeline_tex(mesh, image)用原图作为条件生成纹理。导出与落盘网格先导出到临时文件再读回api_server.py这一步同时完成了按type字段的格式转换最终保存到gradio_cache/{uid}.{type}并torch.cuda.empty_cache()释放显存后返回路径api_server.py。此外build_logger会把 stdout/stderr 一并写入gradio_cache/controller.logapi_server.py服务端日志排查可以直接看这个文件应用层还配置了全开的 CORS 中间件api_server.py意味着任意来源的前端页面都可以直接调用该服务——在公网暴露端口时需要自行在反代层收紧。五、小结与使用建议快速出图按 2.1 节命令启动服务用 3.1 节的curl示例即可在数秒内拿到 mini turbo 权重下的 GLB5 步采样 FlashVDM 128 分辨率是源码内建的服务化默认值。上色/纹理加--enable_tex启动请求中置texture: true若要给自带网格上色则在请求中同时提供meshGLB 的 Base64与image。长任务/前端集成改用/send/status/{uid}轮询模式避免 HTTP 长连接超时。参数调优num_inference_steps、octree_resolution、guidance_scale均可在请求体中逐次覆盖无需改代码切换完整Hunyuan3D-2权重时用--model_path tencent/Hunyuan3D-2并按需调整 subfolder 相关配置同时把步数与分辨率调回更接近管线默认的水平。所有默认值与行为结论均以当前仓库 api_server.py、hy3dgen/shapegen/pipelines.py、hy3dgen/shapegen/postprocessors.py 的实际代码为准若后续版本调整了 argparse 默认端口或注释状态请以最新源码为准。【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Hunyuan3D-2 REST API 服务实战api_server.py 的启动参数、请求协议与源码级解析【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2本文基于 Hunyuan3D-2 仓库中 docs/source/started/api.md 的 API 使用说明展开结合 api_server.py 的完整源码讲清如何把 Hunyuan3D-2 的图生 3D / 已有网格上色能力封装为一个本地 FastAPI 服务。读完后你可以独立启动服务、构造合法的生成请求同步与异步两种模式并理解每个请求字段在源码中对应的默认值与处理流程。一、能力定位一个把 3D 生成模型变成 HTTP 端口的服务官方文档对 API 服务的定位是在本地启动一个 API server然后通过 HTTP POST 请求完成三类操作——图片转 3D、文本转 3D、给已有网格上色texturing existing mesh等等。从源码结构看这套服务并不是独立实现了一套推理逻辑而是把仓库中现成的推理管线封装进了 FastAPI形状生成使用Hunyuan3DDiTFlowMatchingPipeline定义于 hy3dgen/shapegen/pipelines.py默认加载tencent/Hunyuan3D-2mini仓库下的hunyuan3d-dit-v2-mini-turbo子文件夹权重并启用 FlashVDM 加速纹理生成使用Hunyuan3DPaintPipeline定义于 hy3dgen/texgen/pipelines.py默认加载tencent/Hunyuan3D-2输入图片会先经过BackgroundRemover基于 rembg做背景去除见 api_server.py 的导入与 api_server.py 的实例化。值得注意的是Blender Addon 依赖的正是这个 API 服务——docs/source/started/blender.md 中明确写道With an API server launched, you could also directly use Hunyuan3D 2.0 in your blender。也就是说本地 Blender 插件本质上是这个 HTTP 服务的一个客户端。二、启动服务命令与完整参数表2.1 基本启动命令与原文档一致最基本的启动方式为python api_server.py --host 0.0.0.0 --port 8080服务由 uvicorn 承载api_server.py 末尾调用uvicorn.run(app, hostargs.host, portargs.port, log_levelinfo)依赖的fastapi、uvicorn已包含在 requirements.txt 的 Demo only 分组中执行pip install -r requirements.txt即可满足 Web 层依赖模型推理本身的依赖torch、diffusers、trimesh 等同样在该文件中。2.2 命令行参数以源码 argparse 定义为准api_server.py 中argparse定义了如下参数。注意两处与直觉不同的默认值参数类型默认值说明--hoststr0.0.0.0监听地址0.0.0.0表示允许局域网内其他机器访问--portint8081监听端口。注意源码默认是 8081而文档示例显式指定 8080两者不一致时以显式传参为准--model_pathstrtencent/Hunyuan3D-2mini形状生成模型仓库支持 Hugging Face 仓库名--tex_model_pathstrtencent/Hunyuan3D-2纹理生成模型仓库--devicestrcuda推理设备--limit-model-concurrencyint5创建了一个asyncio.Semaphoreapi_server.py用于限制模型并发并影响/generate返回的排队信息计算--enable_texflag关传入该标志才会在启动时加载Hunyuan3DPaintPipelineapi_server.py。不加载时请求中传texture会因self.pipeline_tex不存在而报错需要说明的两点适用前提纹理功能除--enable_tex外还需要按 README.md 的 Install Requirements 一节额外编译安装两个本地扩展hy3dgen/texgen/custom_rasterizer与hy3dgen/texgen/differentiable_renderer下的setup.py install否则Hunyuan3DPaintPipeline的加载/推理会缺少 C/CUDA 依赖。源码中ModelWorker.__init__里文生图管线HunyuanDiTPipeline的加载代码目前处于注释状态api_server.py。从源码结构看text输入分支api_server.py引用了未实例化的self.pipeline_t2i因此在当前版本的仓库里文本转 3D 这条路径实际上不会走通建议以图片输入作为主要使用方式。三、请求协议字段、默认值与两种调用模式3.1 同步接口 POST /generate/generate处理器位于 api_server.py接收 JSON生成完成后直接以FileResponse返回二进制模型文件。原文档给出的最简示例图生 3D、不带纹理如下img_b64_str$(base64 -i assets/demo.png) curl -X POST http://localhost:8080/generate \ -H Content-Type: application/json \ -d { image: $img_b64_str, } \ -o test2.glb请求体是一个 JSON 对象image字段为图片的 Base64 字符串服务端用base64.b64decode解码后交给 PIL 打开见 api_server.py。assets/demo.png 是仓库自带的示例输入图。一个可组合的完整请求示例开启纹理、指定随机种子与面数上限img_b64_str$(base64 -i assets/demo.png) curl -X POST http://localhost:8080/generate \ -H Content-Type: application/json \ -d { \image\: \$img_b64_str\, \texture\: true, \seed\: 1234, \octree_resolution\: 128, \num_inference_steps\: 5, \guidance_scale\: 5.0, \face_count\: 40000, \type\: \glb\ } \ -o textured.glb提示文档中的base64 -i是 BSD/macOS 写法在 GNU/Linux 上等价于base64 -w 0 assets/demo.png-w 0表示不换行。/generate支持的请求字段及源码中的处理逻辑api_server.py如下表字段类型默认值说明imagestr无必填或给text图片的 Base64 字符串服务端解码后经BackgroundRemover去背景并作为形状生成或纹理生成的条件输入textstr无文本输入走文生图管线如 2.2 节所述当前源码中该管线加载被注释此路径暂不可用meshstr无已有网格 GLB 文件的 Base64 字符串。提供后跳过形状生成直接加载该网格trimesh.load(..., file_typeglb)api_server.py对应文档所说的 Texturing existing mesh此时应同时提供image作为上色条件textureboolfalse为true时对网格先执行FloaterRemover→DegenerateFaceRemover→FaceReducer默认face_count40000再调用Hunyuan3DPaintPipeline上色api_server.pyseedint1234通过torch.Generator(device).manual_seed(seed)注入保证结果可复现octree_resolutionint128体素/八叉树表面重建分辨率越高细节越多、耗时越长num_inference_stepsint5扩散采样步数guidance_scalefloat5.0无分类器引导强度face_countint40000纹理前FaceReducer的目标面数上限见 hy3dgen/shapegen/postprocessors.pytypestrglb输出文件格式后缀同时决定临时文件后缀与gradio_cache/{uid}.{type}的落盘文件名关于num_inference_steps与octree_resolution的取值值得注意一个双层默认值现象Hunyuan3DDiTFlowMatchingPipeline.__call__在 hy3dgen/shapegen/pipelines.py 中的管线级默认值是num_inference_steps50、octree_resolution384、guidance_scale7.5而 API 服务层把它们改成了5 / 128 / 5.0api_server.py。这是因为 API 默认加载的是 mini turbo 蒸馏权重并强制开启了enable_flashvdm(mc_algomc)api_server.py对应管线中的 hy3dgen/shapegen/pipelines.py面向的是低步数、快响应的在线服务场景如果你改用完整Hunyuan3D-2权重更低的步数/分辨率并不一定合适需要自行在请求中调整。请求处理失败时ValueError、torch.cuda.CudaError或任何未知异常/generate不会返回二进制流而是返回 HTTP 404 与 JSON 错误体形如{text: 错误提示, error_code: 1}api_server.py。客户端判断成功与否应以响应是否为二进制 GLB 文件或 HTTP 状态码为准。3.2 异步接口 POST /send 与 GET /status/{uid}对于耗时较长的生成任务api_server.py 还暴露了一组轮询式异步接口文档正文未提及但属于同一服务的组成部分POST /send请求体字段与/generate完全相同但任务在后台线程中执行threading.Thread(targetworker.generate, ...)接口立即返回{uid: uuid}api_server.pyGET /status/{uid}按 uid 轮询。产物文件gradio_cache/{uid}.glb不存在时返回{status: processing}存在时返回{status: completed, model_base64: GLB 的 Base64}api_server.py。# 1. 提交任务 uid$(curl -s -X POST http://localhost:8080/send \ -H Content-Type: application/json \ -d {\image\: \$img_b64_str\} | python3 -c import sys,json;print(json.load(sys.stdin)[uid])) # 2. 轮询状态 curl -s http://localhost:8080/status/$uid # 未完成{status:processing} # 已完成{status:completed,model_base64:...}异步接口返回的是 Base64 编码的网格适合浏览器或无文件写入权限的前端直接消费同步接口则直接落盘二进制文件适合脚本与 Blender Addon 这类文件型客户端。四、ModelWorker 内部流程一次请求经历了什么把 api_server.py 中ModelWorker的关键代码串起来一次/generate请求的完整处理链路如下输入解析从params读取imageBase64 → PIL或走text生图分支再经self.rembg(image)去除背景api_server.py。若提供了mesh字段则从 Base64 解码为trimesh对象跳过后续形状生成。形状生成仅当未提供mesh将seed、octree_resolution、num_inference_steps、guidance_scale填入params并把mc_algo固定为mcMarching Cubesapi_server.py随后调用self.pipeline(**params)[0]得到 trimesh 网格。管线内部会做 Flow Matching 采样、CFG 组合hy3dgen/shapegen/pipelines.py最后由 VAE 按八叉树体素重建表面并导出为trimesh.Trimeshhy3dgen/shapegen/pipelines.py。纹理生成仅当texturetrue依次执行三个后处理器——FloaterRemover去除悬空碎片、DegenerateFaceRemover去除退化面、FaceReducer把面数压到face_count上限三者均基于 pymeshlab 实现见 hy3dgen/shapegen/postprocessors.py——压面是为了让后续 UV 展开与纹理合成在可控规模上进行然后self.pipeline_tex(mesh, image)用原图作为条件生成纹理。导出与落盘网格先导出到临时文件再读回api_server.py这一步同时完成了按type字段的格式转换最终保存到gradio_cache/{uid}.{type}并torch.cuda.empty_cache()释放显存后返回路径api_server.py。此外build_logger会把 stdout/stderr 一并写入gradio_cache/controller.logapi_server.py服务端日志排查可以直接看这个文件应用层还配置了全开的 CORS 中间件api_server.py意味着任意来源的前端页面都可以直接调用该服务——在公网暴露端口时需要自行在反代层收紧。五、小结与使用建议快速出图按 2.1 节命令启动服务用 3.1 节的curl示例即可在数秒内拿到 mini turbo 权重下的 GLB5 步采样 FlashVDM 128 分辨率是源码内建的服务化默认值。上色/纹理加--enable_tex启动请求中置texture: true若要给自带网格上色则在请求中同时提供meshGLB 的 Base64与image。长任务/前端集成改用/send/status/{uid}轮询模式避免 HTTP 长连接超时。参数调优num_inference_steps、octree_resolution、guidance_scale均可在请求体中逐次覆盖无需改代码切换完整Hunyuan3D-2权重时用--model_path tencent/Hunyuan3D-2并按需调整 subfolder 相关配置同时把步数与分辨率调回更接近管线默认的水平。所有默认值与行为结论均以当前仓库 api_server.py、hy3dgen/shapegen/pipelines.py、hy3dgen/shapegen/postprocessors.py 的实际代码为准若后续版本调整了 argparse 默认端口或注释状态请以最新源码为准。【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
