如何使用 3D 生成 API：开发者指南

TL;DR：

• 3D 生成 API 可将文本提示词或图像转换为可通过 HTTP 获取的 3D 模型，无需建模。
• 大多数 API 都是异步的：提交任务后获得任务 ID，再轮询状态端点；仅当服务商明确提供文档时才使用 webhook。
• 使用 API key（保留在服务端）进行身份验证，发送 JSON 请求，并处理 GLB/OBJ/FBX 输出。
• 真正的工作在后续环节：将网格导入 Unity、Blender 或 Web 应用。
• 概念设计适合使用文本生成 3D；需要忠实还原参考图时选择图像生成 3D，并注意 credits 和速率限制。

3D 生成 API 只需一次 HTTP 请求，即可让应用将文本提示词或单张图像转换为可直接使用的 3D 模型，无需手动建模。本指南将讲解完整流程：获取 API key、发送第一个文本生成 3D 或图像生成 3D 请求、获取结果，以及将模型导入引擎。我们将以 Tripo API 为例进行说明。

3D 生成 API 实际能做什么

3D 生成 API 让开发者能够通过简单的 API 调用，将文本提示词或参考图像转换为可用的 3D 资产。应用无需花数小时手工建模，也不必在庞大的资产库中检索，而是可以按需请求新模型，并获得 GLB、OBJ 或 FBX 等格式的可直接使用网格。这正是现代开发团队对如何使用 3D 生成 API 的兴趣迅速增长的原因。随着全球 3D 内容创作和实时可视化市场持续扩大，API 正从实验性的 AI 功能变成实用的基础构建模块。

可以将 3D 生成 API 视为人类输入与可投入生产的几何体之间的转换层。输入可以是一句简短描述，例如 “低多边形中世纪木制手推车”，也可以是一张上传的产品照片；输出则是一个结构化的 3D 网格，包含几何信息，并且根据服务的不同，还可能包含材质和纹理。开发者随后可将生成的资产直接导入游戏引擎、DCC 工具、AR 体验或 3D 打印工作流。

这为构建 3D 内容提供了第三种方式。传统上，团队要么在 Blender 或 Maya 等软件中手工建模资产，要么从在线市场购买现有模型。AI 驱动的生成增加了另一种选择：在应用需要时自动创建自定义资产。对于许多团队而言，这种 3D 资产生成 API 工作流可显著缩短制作时间，同时仍允许艺术家在发布前审核、编辑或优化最终网格。

如今，游戏工作室使用这些 API 来制作环境和道具原型，AR/VR 开发者按需生成交互式物体，电商平台将产品图片转换为 3D 预览，创作者则从草图或照片创建可打印模型。无论你是在遵循面向 AI 生成游戏资产的文本生成 3D API 指南，还是面向产品可视化的图像生成 3D API 指南，核心工作流都相同：提供输入、接收标准化 3D 文件，并将其集成到现有流程中。

3D 生成 API 的工作原理

这些 API 如何工作：异步任务模型

大多数开发者期望 API 请求能够立即返回结果。3D 生成 API 的工作方式不同，因为创建网格是计算密集型的 AI 任务；根据模型复杂度和队列长度，可能需要数秒到数分钟。现代文本生成 3D API 指南和图像生成 3D API 指南几乎都采用 异步任务模型，而非让 HTTP 请求持续等待。应用提交生成请求、收到任务标识符，并在稍后检查已完成的资产。理解这一模式远比记住某一个端点更重要，因为几乎所有 3D 资产生成 API 工作流都围绕它构建。

提交 → 任务 ID → 获取

首次请求通常包含输入，即文本提示词或上传的图像，以及质量、网格格式、纹理设置或多边形数量等可选参数。API 不会立即返回 GLB 或 FBX 文件，而是响应一个唯一的 任务 ID 和 queued 或 running 等初始状态。

该任务 ID 会成为后续每次请求的引用。应用使用它查询任务状态、获取进度信息，并在处理完成后下载生成的模型。这种设计可避免长时间运行的 HTTP 连接超时，并让生成服务在高负载下高效扩展。

轮询与服务商支持的 Webhook

有两种常见方式可获知任务何时完成。

轮询是指应用定期发送请求，例如每三到五秒一次，以检查任务状态是否发生变化。它易于实现，适合原型、内部工具和生成请求相对较少的应用。其代价是重复的状态检查会增加 API 流量，尤其是生成耗时比预期更长时。

部分服务商支持 webhook，以减少重复的状态请求。当 API 文档公开了回调 URL 参数、负载 schema、安全机制和重试行为时，应用可接收完成通知，而不必持续轮询。Webhook 适用于后台处理和高吞吐系统，但不能假定所有服务商都提供它们。如果没有文档说明 webhook，请使用受支持的任务状态端点，并采用有上限的轮询和退避策略。

“success”、“running”和“failed”分别表示什么

任务通常会经过一个简单的状态机：

• Queued - 请求已被接受，正在等待处理。
• Running - AI 正在生成网格和纹理。
• Success - 模型已完成，可下载为所请求的格式，例如 GLB、OBJ 或 FBX。
• Failed - 因输入无效、不支持的参数、服务器错误或超时条件，生成未能完成。

应用在尝试下载模型前应始终检查任务状态。一个稳健的 3D 生成 API 实现还应包括重试逻辑、超时处理和清晰的错误信息，以便用户了解任务仍在处理中，还是确实需要重新提交。这个异步工作流起初可能并不熟悉，但它是现代 AI 生成平台的标准架构，因为它可靠、可扩展，并且易于集成到现有开发流程中。

异步 3D 生成 API 工作流

第 1 步：获取 API Key 并进行身份验证

应用要生成任何 3D 资产，首先需要获得访问 API 的权限。这意味着要创建账户并获取 API key。大多数服务商会在账户启用 API 访问权限后，于 Account 或 API Settings 页面提供该功能。例如，Tripo 用户在订阅包含 API 访问权限后，可通过 Account Settings → API 生成 API key。该 key 能唯一标识应用，并授权你发送的每一个请求。

身份验证通常通过 HTTP 请求头中的 Bearer token 完成。常见请求会包含 Authorization: Bearer YOUR_API_KEY 请求头以及适当的 Content-Type。请求到达服务器后，API 会先验证该 key，再接受任何生成任务。无论你遵循的是 3D 生成 API 教程、文本生成 3D API 指南还是图像生成 3D API 指南，这个身份验证步骤都相同。

最重要的最佳实践是绝不要在客户端代码中暴露 API key。不要把它硬编码到 Web 应用、移动应用、Unity 项目或公开的 GitHub 仓库中。应将 key 保留在后端，存储于环境变量或 secrets manager 中，并由服务器代表客户端发出 API 请求。如果 key 泄露，任何人都可能消耗你的 API 配额或产生意外的使用成本。

许多团队还会区分开发和生产凭据。测试 key 用于本地开发和集成测试，生产 key 则保留给具有更严格监控和轮换策略的线上应用。将这些环境分开，可以更安全地进行实验，避免风险波及生产配额或泄露敏感凭据。以安全的身份验证开始，可为后续的 3D 资产生成 API 工作流奠定坚实基础。

开始使用 API 身份验证

第 2 步：发送第一个生成请求

完成身份验证设置后，即可发送第一个生成请求。此时，应用会告知 API 要创建什么、提供的是哪种输入，以及希望使用哪种输出格式。不同服务商的具体端点和参数名称有所不同，因此适合在此处引导读者查看 Tripo API 文档，获取最新 API 参考。

文本生成 3D 请求

文本生成 3D 请求以 POST 请求开始，其中包含描述性提示词和可选的生成参数。除提示词本身外，大多数 API 还允许指定输出格式（GLB、OBJ 或 FBX）、纹理生成、网格质量、多边形数量或其他生成选项。提示词越具体，结果就越可预测。例如，描述物体的风格、目标平台和细节程度，通常比仅使用几个泛泛词语产生更好的资产。

图像生成 3D 请求

图像生成 3D 请求遵循相同模式，但使用参考图像，而非完全依赖文本。根据 API 的不同，图像可通过公开 URL、上传文件标识符或 base64 编码图像提供。还可以加入简短的文本提示词，引导 AI 生成特定风格或几何体。该工作流常用于产品可视化、概念艺术、扫描物体，以及将 2D 参考转化为可编辑的 3D 模型。

无论选择文本还是图像输入，每个生成请求都遵循相同结构：发送经过身份验证的 POST 请求，在请求体中包含必需的生成参数，并指定所需输出格式。API 会验证请求，并立即返回 任务 ID，而不是完成的模型。该任务 ID 是 3D 资产生成 API 工作流其余部分的关键，因为它允许应用监控进度，并在生成结束后获取完成的资产。

发送第一个 3D 生成请求

第 3 步：获取生成的模型

提交生成请求后，最后一步是获取完成的 3D 资产。由于过程是异步的，应用应等待任务状态变为成功后再下载模型。

继续轮询文档所述的任务状态端点，直至生成完成。如果所选服务商明确支持 webhook，应用可等待经过验证的回调，然后确认最终任务状态。任务成功后，响应应会以可用输出格式提供生成的资产或下载 URL。应用随后可下载文件，并将其传递给目标引擎、DCC 工具或生产流程。

集成还应妥善处理失败情况。任务可能因输入无效、不支持的参数或暂时性服务问题而失败。添加重试逻辑、超时处理和清晰的错误信息，让用户了解任务仍在处理中，还是需要重新提交。如果任务异常长时间卡住，请停止轮询、记录任务 ID，并核实平台是否已自动退还任何生成 credits。构建这些保护措施可使 3D 资产生成 API 工作流更可靠、更适合生产环境。

第 4 步：处理 3D 文件（GLB、OBJ、FBX 等）

模型生成后，下一步是为应用选择合适的文件格式。大多数 3D 生成 API 支持多种导出选项，因为不同工作流需要不同格式。例如，Tripo 支持导出 GLB、USD、FBX、OBJ、STL 和 3MF。

不同目标应选择哪种格式

存储和交付资产

下载模型后，请将其存储在 Amazon S3、Google Cloud Storage 或 Azure Blob Storage 等对象存储中，而不是保留在应用服务器上。随后可通过 CDN 分发存储的文件，使全球用户能够以更低的延迟下载或预览资产。随着生成模型数量的增长，分离生成、存储和交付环节，也能让 3D 资产生成 API 工作流更易于扩展。

选择正确的 3D 文件格式

第 5 步：将模型引入应用或引擎

下载生成的资产后，最后一步是将其集成到生产工作流中。大多数 API 只负责生成模型，其余工作取决于你计划在何处使用它。无论是在构建游戏、在 DCC 应用中编辑资产，还是在 Web 上渲染模型，集成过程通常都很直接。

游戏引擎（Unity、Unreal、Godot）

游戏引擎通常可直接导入 GLB 或 FBX 文件。导入后，可以分配材质、添加碰撞体、生成 LOD、附加动画，或将资产放入场景中。如果工作流涉及频繁的 AI 生成，Tripo 官方 Bridge plugins 可将模型直接从浏览器发送到 Unity、Unreal Engine、Godot 和 Cocos，免去手动下载和导入文件的步骤。

3D 和 DCC 工具（Blender、Maya、3ds Max）

艺术家通常会在生产前优化 AI 生成的资产。可将模型导入 Blender、Maya 或 3ds Max，以编辑几何体、调整 UV、烘焙纹理、重新拓扑网格或准备动画。Tripo 还为这些 DCC 工具提供官方 plugins，可用更少的手动步骤将模型直接传输到软件中。

Web 和 three.js

对于 Web 应用，GLB 通常是最佳选择，因为它将几何体、材质和纹理打包到一个文件中。three.js 等库可使用 GLTF loader 直接加载 GLB 资产，从而轻松在浏览器中展示交互式 3D 内容。结合对象存储和 CDN，这种方法能在桌面和移动设备上提供快速加载和流畅的浏览体验。

至此，3D 资产生成 API 工作流已完成：从发送提示词到在应用、引擎或 Web 体验中交付可投入生产的模型。

3D 生成 API 工作流：从提示词到应用

成本、速率限制和配额

在大规模部署集成前，请确保了解 API 如何对生成收费，以及如何限制请求量。大多数 3D 生成 API 使用 credits 或按请求计费，复杂生成比简单生成消耗更多资源。

例如，Tripo 使用基于 credits 的系统。标准生成起价为 25 credits，而 Ultra Generation（+15 credits）或 Texture Generation（+10 credits）等可选功能会消耗额外 credits。免费套餐每月包含 200 credits，因此可以在升级前轻松构建并测试原型。

除成本外，还要关注速率限制和并发任务限制。一次发送过多请求可能导致速率限制响应或任务排队。应用在重试失败请求时应实施指数退避，而非立即发送另一个请求，这有助于减少不必要的流量并提升可靠性。

一种良好做法是先使用免费配额验证工作流，衡量平均生成时间和 credits 使用量，然后在扩展到生产环境前估算成本。监控 credits 消耗、重试率和失败任务，有助于随着使用量增长保持 3D 资产生成 API 工作流的可预测性。

文本生成 3D 与图像生成 3D：应该调用哪一种？

两种 API 都能生成 3D 模型，但它们为不同任务而设计。最佳选择取决于你是要创造全新的事物，还是重建现有物体。

如果应用需要从零开始生成新资产，文本生成 3D 通常是最佳选择。它适合游戏道具、环境和早期设计概念，在这些场景中，速度与创意比匹配某一特定物体更重要。结果质量在很大程度上取决于提示词的编写质量。

当保留现有物体的外观更重要时，请选择图像生成 3D。这一工作流很适合产品目录、零售、收藏品，以及将概念艺术转化为可编辑 3D 模型，因为 AI 会遵循参考图像，而不只是解读文本描述。

当你能提供同一物体在不同角度拍摄的两到四张一致图像时，请选择多视角生成 3D。额外视角能为 API 提供更多空间信息，与单张图像相比，可提高形状精度、保留比例，并减少缺失或变形的几何体。对于复杂产品、细节丰富的物体，以及要求匹配参考对象的工作流，这是一种很好的选择。

不应使用 3D 生成 API 的情况（限制）

3D 生成 API 可以节省大量时间，但并非每个项目都适用。

对于需要精确尺寸和公差的工程或制造零件，传统 CAD 软件仍是更好的选择。AI 生成的网格旨在用于视觉内容，而非精密工程。

如果需要具有完全可控拓扑、UV 或适合动画的网格的 AAA 级资产，手工建模仍不可或缺。AI 最适合概念创作和快速原型，而艺术家则负责最终优化。

云端 API 也可能不适用于离线环境或有严格隐私要求的项目，因为提示词和参考图像会被上传进行处理。

最后，生成模型前务必检查版权。只能使用你有权使用的提示词和参考图像。Tripo 表示，当输入材料不侵犯第三方权利时，生成的模型可用于商业用途，且版权归你所有。

常见问题

如何获取 3D 生成工具的 API key？

在服务商处创建账户，然后打开其开发者或 API 设置。对于 Tripo，当前产品指引说明 API 访问可通过 Pro 或 Business 套餐获得，key 可从 Account Settings → API 获取。将 key 存储在服务端 secrets manager 或环境变量中，绝不要放入浏览器代码、移动应用或公开仓库。将其接入生产工作流前，先用一个小型测试请求验证凭据。

如何在 Python 中调用 3D 生成 API？

使用 requests 等 Python HTTP 客户端发送经过身份验证的 POST 请求，其中包含服务商所需的提示词或图像参数。解析返回的任务 ID，然后轮询文档规定的状态端点，直至任务报告成功或失败；两次检查之间应设置超时和退避。仅在状态成功后下载模型，并记录任务 ID，以便调查失败任务。有关确切的端点名称和响应字段，请使用服务商当前的 API 参考。

如何处理 API 返回的 GLTF/GLB 和 OBJ 文件？

GLB 将几何体、材质和纹理打包到一个二进制文件中，便于用于 Web 查看器和许多实时流程。OBJ 得到广泛的 3D 编辑工具支持，但其材质和纹理通常作为独立文件存储，必须保存在一起。验证下载的文件，保留服务商的缩放和坐标轴约定，并将生产资产存储在具有受控访问权限的对象存储中。向用户发布前，请在目标引擎或 DCC 工具中测试最终导入效果。

文本生成 3D API 和图像生成 3D API 有什么区别？

文本生成 3D 根据书面描述创建新资产，因此适合概念生成和制作大量变体。图像生成 3D 在模型需要与特定物体、角色或设计相似时使用视觉参考。由于单张图像无法展示每个表面，隐藏的几何体仍可能需要推断；如果服务商支持且形状精度很重要，多视角输入更合适。应根据优先目标是开放式创意构思，还是忠实还原现有参考，来选择输入方法。

每次请求 3D 生成 API 的成本是多少？

成本取决于服务商、生成模式和可选处理步骤，因此没有通用的单次请求价格。Tripo 当前的 credits 表显示，标准生成需要 25 credits，Ultra generation 和纹理生成等选项会消耗额外 credits。运行有代表性的测试任务，衡量应用所需质量设置的实际成本，包括重试和后处理。估算生产能力时，还应考虑并发和速率限制，而不仅是名义上的生成费用。

我可以将 API 生成的 3D 模型用于商业用途吗？

商业用途取决于服务商当前的许可条款，以及你是否有权使用输入提示词、图像、品牌或角色。在发布前，请检查所有权、转售、市场分发和用户生成内容相关条款。不要认为技术上成功生成模型就能消除版权、商标、隐私或公开权风险。对于高价值或法律敏感的产品，请保留适用的条款版本，并获得合格的法律审查。

结语

使用 3D 生成 API 比最初看起来更简单：进行身份验证、提交文本生成 3D 或图像生成 3D 请求、获取完成的模型，然后将其引入应用或引擎。理解异步工作流后，将 AI 生成资产集成到流程中会变得十分直接。

准备好构建自己的工作流了吗？获取 API key，探索 Tripo Studio，并在几分钟内生成第一个 3D 资产。