3D 生成

3D 模型不会立即生成完成。POST /v1/3d/generations 会返回任务 ID 和 poll_url，完成后可以从 model_url 等地址下载。

选择输入类型Copy Anchor Link

这个 API 不使用 operation。模型标有 text-to-3d 时可以接收提示词，标有 image-to-3d 时可以接收图片。

curl "https://api.tokenlab.sh/v1/models?recommended_for=3d" \
  -H "Authorization: Bearer sk-your-api-key"

不同模型支持的输入和输出格式不同。发送 image、image_url、format、quality、style 或 seed 前，请查看模型详情。

创建 3D 任务Copy Anchor Link

curl https://api.tokenlab.sh/v1/3d/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tripo-h3.1",
    "prompt": "一个风格化的低多边形机器人吉祥物，具有干净的拓扑结构"
  }'

图片可以从互联网访问时，图生 3D 使用 https 地址即可。图片不能公开访问时，可以用内联 base64 image，但服务端必须能接收更大的请求体。

输出格式Copy Anchor Link

• glb 适合网页预览。
• fbx 和 obj 常用于 DCC 工具，前提是模型支持。
• usdz 可用于 Apple AR，前提是模型支持。
• 更高的 quality 可能等待更久、费用更高，应当让用户自己选择。
• 只有模型支持时，seed 才能影响结果的可重复性。

获取生成结果Copy Anchor Link

使用创建响应中的 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。如果产品需要长期下载或版本历史，请把文件保存到自己的存储中。

让结果可以长期访问Copy Anchor Link

• 保存 task_id、poll_url、模型、输出格式和你自己的文件 ID。
• 页面刷新后继续查询原任务，不要重新创建。
• 提交前确认源图片大小合适、URL 可以访问。
• 文件地址不能展示给无权访问的用户。
• 返回 billing_transaction_id 时一并保存，方便核对费用。

常见错误Copy Anchor Link

API 参考Copy Anchor Link