端点
POST 会立即返回一个 id 以及 status: "pending"。可通过轮询 GET /v1/3d/generations/{id} 或设置 callback_url 来获取结果。大多数生成会在 1–3 分钟内完成。
模型
H3.1 是 Tripo 的高精度模型。P2 与 P1 生成面向实时渲染的低模网格,其中 P2 支持原生四边面拓扑、面数更高。
请求头
支持个人 API Key 和组织 API Key。使用组织 API Key 时从组织钱包扣费,见组织 API Key。
请求体(POST)
仅图生 3D,且为必填。仅含一个元素的数组,为参考图:公开的 HTTPS URL,也可以是内联的 base64
data: URI(例如 data:image/png;base64,...),提交任务前会先替你托管。支持 JPEG、PNG、WebP。无法访问的 URL 会在预留任何费用之前返回 400。detailed 为 HD 贴图,extreme 为 8K 贴图。fast 以贴图细节换取速度,按标准价计费;它运行在贴图模型 v3.5-20260815 上,未传 texture_version 时会自动使用该版本。独立于几何模型指定贴图模型。不传时使用模型默认值(
v3.0-20250812;texture_quality: "fast" 时为 v3.5-20260815)。可选的幂等 id,等同于请求头
Idempotency-Key 的请求体写法。见幂等性。可选。任务完成时,VibeToken 会将最终结果
POST 到此 URL。见回调。各系列支持的选项
文生 3D 模型接收
prompt(以及 negative_prompt 和 image_seed);图生 3D 模型接收
image_urls(以及 enable_image_autofix、texture_alignment 和 orientation),不接收提示词。
某个系列未列出的选项请不要传入。未传入的选项取上文所示的默认值,价格也按默认值计算。
各系列的选项详见其文档页。
提交任务
image_urls,不传 prompt:
响应(POST)
轮询状态(GET)
status 为 success 或 failed。
响应(GET)
运行中:3d.generation 对象
输出文件
data[0].url—— 3D 模型:内嵌材质的二进制 glTF(.glb)文件;请求设置了quad: true时为.fbx。data[1].url—— 模型的 PNG 渲染预览图(Tripo 返回时提供)。
.glb、.fbx、.png),
可据此选择加载器。需要长期保留的文件请自行下载保存。
幂等性
发送Idempotency-Key 请求头(或在请求体中加入 client_request_id 字段)即可安全重试:重复的 id
会返回已有的生成任务,而不是新建并再次扣费。如果在拿到 id 之前连接就断开了,可以用该 id 查询任务:
200 返回生成对象;404 表示请求从未到达,请用同一个 id 重试 POST。完整规则见
幂等性。
回调
设置callback_url 后,任务结束时 VibeToken 会把结果 POST 到该 URL。result_urls 与 data
顺序相同:先是模型文件,然后是预览图。
"status": "fail"、空的 result_urls 以及 error_message。usage 与轮询返回的对象相同:usage.cost 为实际扣费金额,失败时为 0。该 URL 必须是公开的
HTTP(S) URL;内部及私有网络地址会返回 400。投递细节见
异步任务 → 回调。
错误
被受理但之后失败的生成,会在 GET 中返回
status: "failed" 及 error_message,且不收费。错误响应体见
错误码。