跳转到主要内容

端点

3D 生成是异步的。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)

string
必填
上表中的 3D 模型 ID。传入其他模态的模型会返回 400。
string
仅文生 3D,且为必填。描述要生成的物体,最长 1024 字符。
string
仅文生 3D。不希望出现在模型中的内容,最长 255 字符。
string[]
仅图生 3D,且为必填。仅含一个元素的数组,为参考图:公开的 HTTPS URL,也可以是内联的 base64 data: URI(例如 data:image/png;base64,...),提交任务前会先替你托管。支持 JPEG、PNG、WebP。无法访问的 URL 会在预留任何费用之前返回 400。
boolean
默认值:"true"
生成贴图。将它与 pbr 都设为 false 可得到无贴图白模。
boolean
默认值:"true"
生成 PBR 材质。pbr: true 会同时开启贴图。
"fast" | "standard" | "detailed" | "extreme"
默认值:"\"standard\""
detailed 为 HD 贴图,extreme 为 8K 贴图。fast 以贴图细节换取速度,按标准价计费;它运行在贴图模型 v3.5-20260815 上,未传 texture_version 时会自动使用该版本。
"standard" | "detailed"
默认值:"\"standard\""
仅 H3.1。detailed 为超精细几何模式。
boolean
默认值:"false"
H3.1 与 P2。输出四边面网格;此时模型文件为 .fbx 而不是 .glb。
boolean
默认值:"false"
仅 H3.1。生成拓扑干净、接近手工布线的低模网格。
boolean
默认值:"false"
仅 H3.1。将模型拆分为可单独编辑的部件。需要同时设置 texture: false 与 pbr: false。
integer
输出网格的最大面数。范围取决于模型系列(见下文)。不传则由模型自行决定。
boolean
默认值:"false"
按真实世界尺寸缩放模型,单位为米。
integer
几何随机种子,0 到 2147483647。
integer
贴图随机种子,0 到 2147483647。
integer
仅文生 3D。提示词处理阶段的随机种子,0 到 2147483647。
boolean
默认值:"false"
仅图生 3D。让 Tripo 在生成前先优化输入图片。
"original_image" | "geometry"
默认值:"\"original_image\""
仅图生 3D。让贴图忠实于原图,或对齐生成的网格。
"default" | "align_image"
默认值:"\"default\""
仅图生 3D。align_image 会旋转模型,使其与图中物体的朝向一致。
"v3.5-20260815" | "v3.0-20250812"
独立于几何模型指定贴图模型。不传时使用模型默认值(v3.0-20250812;texture_quality: "fast" 时为 v3.5-20260815)。
boolean
默认值:"true"
贴图前去除参考图中烘焙的光照。仅贴图模型 v3.5-20260815 读取此项。
boolean
默认值:"true"
生成时展开 UV。设为 false 生成更快、文件更小。
"+x" | "-x" | "-y" | "+y"
默认值:"\"+x\""
导出模型的前向轴。
"geometry"
仅 H3.1。压缩网格(meshopt),得到更小的文件。
string
可选的幂等 id,等同于请求头 Idempotency-Key 的请求体写法。见幂等性。
string
可选。任务完成时,VibeToken 会将最终结果 POST 到此 URL。见回调。

各系列支持的选项

文生 3D 模型接收 prompt(以及 negative_prompt 和 image_seed);图生 3D 模型接收 image_urls(以及 enable_image_autofix、texture_alignment 和 orientation),不接收提示词。 某个系列未列出的选项请不要传入。未传入的选项取上文所示的默认值,价格也按默认值计算。 各系列的选项详见其文档页。

提交任务

图生 3D 请改为发送 image_urls,不传 prompt:

响应(POST)

轮询状态(GET)

每 5 秒左右轮询一次,直到 status 为 success 或 failed。

响应(GET)

运行中:
完成后:
失败时:

3d.generation 对象

输出文件

  • data[0].url —— 3D 模型:内嵌材质的二进制 glTF(.glb)文件;请求设置了 quad: true 时为 .fbx。
  • data[1].url —— 模型的 PNG 渲染预览图(Tripo 返回时提供)。
文件托管在 VibeToken 媒体 CDN 上,每个 URL 都以文件的真实扩展名结尾(.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,且不收费。错误响应体见 错误码。

计费

按次计费。价格取决于模型版本、任务类型、是否生成贴图,以及你开启的附加选项(HD 或 8K 贴图、超精细几何、 四边面网格、智能低模、部件拆分)。提交时会按你发送的选项从余额中预留相应金额;成功后按该次生成的实际消耗 扣费,且不会超过预留金额。失败的生成不收费,预留金额会被释放。当前费率请见定价页。