跳转到主要内容
3D生成是异步的。 POST /v1/3d/generations 创建一个TokenLab任务；完成状态响应返回可下载的模型资产，如 model_url，并在可用时返回特定格式的URL。

​
选择输入类型

工作流必需输入可选字段备注
文本到3Dmodel, promptformat, quality, style, seed最适合从描述生成新资产
图像到3Dmodel, prompt, image 或 image_urlformat, quality, style, seed仅在所选模型支持图像输入时使用
在决定要公开哪些选项之前，请查询模型目录： 
curl "https://api.tokenlab.sh/v1/models?recommended_for=3d" \
  -H "Authorization: Bearer sk-your-api-key"
不要假设每个3D模型都支持两种输入类型或每种输出格式。在发送 image, image_url, format, quality, style 或 seed 之前，请检查所选模型契约。

​
创建3D任务

curl https://api.tokenlab.sh/v1/3d/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tripo3d-v2.5",
    "prompt": "一个风格化的低多边形机器人吉祥物，具有干净的拓扑结构",
    "format": "glb",
    "quality": "standard"
  }'
对于图像到3D，尽可能使用公共 image_url。仅在您的客户端故意发送私有媒体且您的后端准备好处理更大的请求体时，才使用内联/base64 image。

​
输出格式选择

  • glb 通常是网页预览的最安全默认值。
  • fbx 和 obj 在所选模型支持时对DCC管道很有用。
  • usdz 在模型公开时对Apple AR工作流很有用。
  • 较高的 quality 值可能会增加延迟和成本。将其作为明确的用户选择公开，而不是隐藏的默认值。
  • seed 仅在模型尊重它时对可重复性有用。

​
轮询和存储资产

首先使用返回的 poll_url。如果您的客户端需要固定路由，请使用 GET /v1/tasks/{id}。 
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"
完成的任务返回 model_url，并可能包括 glb_url, fbx_url, obj_url 或 usdz_url。如果用户需要重复访问、版本历史或长期下载，请在您自己的产品中下载或缓存所选资产。

​
生产检查清单

  • 持久化 task_id, poll_url, 模型，请求格式和您自己的资产记录ID。
  • 在页面刷新后恢复轮询，而不是创建重复任务。
  • 在创建任务之前验证源图像的大小和可达性。
  • 除非用户有权限访问资产，否则请将生成的资产URL排除在公共页面之外。
  • 记录 billing_transaction_id（如果存在）以便后续对账。

​
常见错误

症状可能原因修复
创建响应没有资产URL3D生成是异步的轮询直到终端状态
请求的格式缺失模型未返回该格式回退到 model_url 或选择支持该格式的模型
图像到3D被拒绝所选模型仅支持文本或图像URL不可达检查模型契约并验证URL
重复资产重试路径在超时后重新创建了任务在重试之前存储任务身份

​
API参考

主题参考
创建3D创建3D
获取3D状态获取3D状态
获取任务状态获取任务状态
列出模型列出模型
计费与定价计费与定价