AI 3D 生成 API — 多引擎，一个 API
想给产品加上 AI 3D 生成，却要自己搭一套切换引擎、任务排队、导出和资产分发的技术栈，着实费力。这部分就交给 PicoBerry 的一个异步 API 来处理。文生 3D、图生 3D 自不必说，从优化环节到可下载的游戏资产输出都能覆盖。
# 从图像生成 3D 模型
curl -X POST https://api.picoberry.ai/v1/models/from-image \
-H "Authorization: Bearer ***" \
-H "Content-Type: application/json" \
-d '{"imageUrl":"https://.../ref.png","engine":"tripo"}'
如何把 AI 3D 生成接入自己的产品？
在 PicoBerry 控制台创建 API 密钥并保存在服务端，然后把提示词或图片 URL，连同引擎选择和输出选项，POST 到 /v1 端点。响应会返回一个任务标识——用它轮询，或注册 Webhook 让后端在任务完成时收到通知。完成后下载模型，直接交给自己的产品使用。
无需自建管线，也能上线 3D 生成功能
仅有一个模型端点往往不够。要真正接入产品，需要下面这些能力：
- 上传处理
- 引擎选择
- 异步任务追踪
- 结果存储
- 导出格式
- 用量管理
- 资产分发
PicoBerry 把整条管线都封装在一个 API 之后。
# prompt/image → 3D
POST /v1/models/from-image
{ "imageUrl": "ref.png", "engine": "tripo" }文本、图像转 3D
传入一段文本提示词或一张参考图，即可生成一个 3D 候选，然后继续进行重构网格、重新贴图、绑定、导出等后续操作，无需在多家服务商之间来回搬运资产。
# same request, switch engines
{ ..., "engine": "tripo" }
{ ..., "engine": "meshy" }
{ ..., "engine": "hunyuan3d" }多引擎，同一套接口
每个请求都会被路由到最合适的引擎：一个提示词交给 Tripo，另一个交给 Meshy，还有的交给 Hunyuan3D。而在代码里，鉴权、提交任务、获取结果和导出的方式始终不变。
# submit → get a task id
{ "taskId": "job_a1b2", "status": "queued" }
# poll/webhook until succeeded从设计之初就是异步
3D 生成不是即时完成的，因此这套 API 围绕生产环境的队列行为来设计：提交任务，保存 task ID，通过轮询获取状态或接收 Webhook，待结果就绪后让应用继续往下走。
从 API 密钥到下载资产
一次典型的接入可以从小处起步：创建 API 密钥，提交一个生成任务，追踪状态，再把完成的资产接入自己的用户流程、工作区、库存、编辑器或管线。
获取 API 密钥
在 PicoBerry 控制台创建一个密钥，将其权限收敛到本次接入所需的范围，并保存在服务端。需要分开查看用量时，可为不同环境、工具或团队分别使用独立的密钥。
提交任务
向 /v1 端点发送提示词、图像 URL、引擎选择和输出选项。应用会立即收到一个任务或资产标识符，而不会阻塞用户界面。
轮询或接收 Webhook
通过 task ID 追踪任务，或注册一个 Webhook，让后端在完成时通知用户、刷新工作区，或触发自动化内容管线的下一步。
下载资产
获取完成的模型并交给自己的产品：在网页查看器中展示、关联到某个项目、发送到游戏引擎工作流，或存下来以备后续编辑。
以开发者为先的功能
这是为需要可重复生成资产的产品和团队准备的：不是一次性的演示，而是能在下面这些场景里持续运转的能力。
OpenAPI 规范与类型化客户端
以 OpenAPI 规范作为请求和响应的唯一标准。探索阶段可导入 Postman，接入进入生产环境后，再为你的后端语言生成类型化客户端。
Webhook 推送
使用带签名的回调，从轮询转向事件驱动的工作流。一次生成完成后，你的服务可以更新项目状态、通知用户、将审核排入队列，或触发导出处理。
面向 AI 智能体的 MCP 服务器
通过 PicoBerry 的 MCP 服务器，把生成能力接入 AI 编程工具和智能体工作流。在构建更大的应用、游戏或工具的过程中，智能体可以直接请求资产候选。
用量与积分追踪
在控制台查看积分用量，让团队在扩大生成工作流之前，把开发、内部工具、面向客户的功能与实验分开统计。
真实运转的游戏资产工作流
下方的演示说明了这个 API 的价值不止于单个生成结果：资产需要从创建走进真实场景，配合引擎工作流，并在实际游玩情境中接受检验。
演示视频：生成并编辑后的 3D 资产在 Unity 场景中流转，展示了从资产创建到游戏内验证的交接过程。
快速生成候选
用提示词或参考图创建道具、物品、角色或场景元素，再把选中的结果保留为可追踪的资产记录。
让资产融入游戏场景
演示展示了下一个实际步骤：把生成的 3D 资产放进 Unity 工作流，由尺度、剪影、光照、遮罩和场景构图来决定这个资产是否合用。
用试玩闭环收尾
目标不是一个孤立的模型预览，而是更快的生成 → 集成 → 测试闭环，让开发者能在真实的游戏体验中评估资产。
看看实际效果
衡量一个 API，要看它能让你的产品做什么：生成候选、比较结果、保留资产记录，并把可用的文件交给工作流的下一步。
一组生成的 3D 候选，你的产品可以把它们呈现出来，供审核、挑选、优化或后续导出。
Quickstart 路径：完成鉴权、发送第一个请求、检查响应，再把生成能力接入自己的后端流程。
{ "success": true, "data": {
"id": "019f3a39-0db2-…",
"taskStatus": 0,
"type": "model_3d"
} }
# later
{ "modelUrls": { "glb": ".../model.glb" } }异步流程示例：提交任务，持久化返回的标识符，通过轮询或接收完成通知，再获取生成的模型 URL。
常见问题
PicoBerry API 是做什么的？
PicoBerry API 是一套用于 AI 3D 生成的异步 REST API。它让你的后端可以提交生成任务、追踪状态、接收完成事件，并获取生成的模型文件，用于产品或管线。
能否通过一个 API 使用多个生成引擎？
可以。请求会被分发到合适的引擎，但在产品这一侧，你只需对接 PicoBerry 这一个 API。无论使用哪个引擎，鉴权、任务追踪、资产记录和导出流程都保持不变。
这个 API 只面向游戏吗？
不是。之所以突出游戏，是因为游戏工具和 3D 资产管线是 PicoBerry 的核心工作流。同样的 API 模式也可以支撑创作者工具、市场平台、内部自动化、AI 智能体、教育工具，以及其他用到 3D 的产品。
生成的资产可以直接用作成品吗？
建议把生成的资产当作候选来看待。它们很适合原型制作、迭代、审核和交接给下一环节。是否可作为成品取决于具体项目：你可能仍需检查拓扑、材质、尺度、绑定、碰撞、许可，以及各引擎的特定要求。
PicoBerry 支持 Webhook 吗？
支持。这套 API 的工作流是异步的：提交一个生成任务，保存返回的标识符，然后通过轮询获取状态，或在任务完成时接收 Webhook。
开发者该如何上手？
先创建一个 PicoBerry 账号，申请 API 访问权限，再把第一个调用集成到服务端。请不要把 API 密钥放在客户端代码里，必要时为不同环境或产品分别使用独立的密钥。
3D 生成层只需搭建一次。 产品在任何需要资产的地方都能复用。
从一次 API 调用开始，再把生成能力接入你的应用、工具、智能体或游戏资产管线。