媒体指南

3D 生成

用文字或图片生成可下载的 3D 模型

3D 生成是异步的。POST /v1/3d/generations 会创建 TokenLab 任务;任务完成后,状态响应会返回可下载的模型文件,例如 model_url,以及可用时的各格式专用 URL。

可下载的 3D 模型文件会自动保存 30 天副本,其 URL 是 TokenLab 媒体结果 URL。任务记录和另行保存的文件各自遵循自己的生命周期。参见数据保留。

选择输入类型

输入必填可选字段说明
文生 3Dmodel、promptformat、quality、style、seed用文字描述新模型
图生 3Dmodel、image_url 或 image;模型列出 prompt 时还需 promptformat、quality、style、seed所选模型必须支持图片输入

operation 可选,取值为 text-to-3d 或 image-to-3d。省略时,只要传了 image 或 image_url,TokenLab 就按 image-to-3d 处理,否则按 text-to-3d。如果传了 operation,它必须与输入一致。模型标有 text-to-3d 时可以接收提示词,标有 image-to-3d 时可以接收图片。

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": "tripo-h3.1",
    "prompt": "一个风格化的低多边形机器人吉祥物,具有干净的拓扑结构"
  }'

图片可以从互联网访问时,图生 3D 使用 https 地址即可。只有模型详情里列出 image 的模型才能用内联 base64 image;有些模型只接受 image_url。

输出格式

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

获取生成结果

用返回的 id 或 task_id 调用 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 时一并保存,方便核对费用。

常见错误

症状可能原因修复
创建响应没有下载地址3D 生成是异步的轮询到终态
请求的格式缺失模型未返回该格式回退到 model_url 或选择支持该格式的模型
图生 3D 被拒绝所选模型仅支持文本,或图片 URL 无法访问检查模型详情并验证 URL
出现重复模型超时后又创建了一次任务重试前确认是否已经取得任务 ID

API 参考

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

本页内容