媒体指南
3D 生成
用文字或图片生成可下载的 3D 模型
3D 生成是异步的。POST /v1/3d/generations 会创建 TokenLab 任务;任务完成后,状态响应会返回可下载的模型文件,例如 model_url,以及可用时的各格式专用 URL。
可下载的 3D 模型文件会自动保存 30 天副本,其 URL 是 TokenLab 媒体结果 URL。任务记录和另行保存的文件各自遵循自己的生命周期。参见数据保留。
选择输入类型
| 输入 | 必填 | 可选字段 | 说明 |
|---|---|---|---|
| 文生 3D | model、prompt | format、quality、style、seed | 用文字描述新模型 |
| 图生 3D | model、image_url 或 image;模型列出 prompt 时还需 prompt | format、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 |