企业官网建设流程全解析

• AI 应用
• 媒体生成
• 后端
• 前端

导读

本文基于 Pollinations 官方文档 3d-generation.md，系统讲解 gen.pollinations.ai 平台的 3D 生成接口：如何通过一次 GET 请求从文本提示或参考图片生成 3D 模型，默认输出 glTF Binary（GLB）格式；并深入源码，剖析microsoft/trellis-2、nvidia/asset-harvester、hyper3d/rodin-2.5三大模型族的输入规则、分辨率与定价差异，以及 InferencePort 与 fal.ai 两套底层生成管道的实现细节。读完本文，你将掌握 3D 生成 API 的完整调用方式、参数语义、缓存计费机制与错误处理策略，可直接落地到自己的应用或 Agent 中。

一、核心能力概览：一次 GET 请求生成 3D 模型

Pollinations 的 3D 生成能力遵循与文本、图像、音频一致的极简设计：一条 HTTP GET 请求即可触发 3D 模型生成，服务端返回二进制模型文件，无需 WebSocket、无需轮询接口（轮询由服务端内部完成）。

• 默认输出格式：glTF Binary（.glb），这是 glTF 2.0 的二进制容器，可被 Three.js、Babylon.js、Blender 等主流 3D 工具直接加载。
• 输入方式：既支持文本提示（text-to-3D），也支持参考图片（image-to-3D），具体取决于所选模型。
• 特殊规则：Trellis 2 / Asset Harvester 家族是纯图片驱动模型——任何传入的文本提示都会被忽略，只有image参数指定的图片 URL 才会被真正使用。

官方文档给出了一个可直接访问的示例 URL：

https://gen.pollinations.ai/3d/no_prompt_for_trellis_needed?model=microsoft%2Ftrellis-2&resolution=low&key=YOUR_KEY_HERE&image=IMAGE_URL_HERE

可以看到，路径中的no_prompt_for_trellis_needed只是满足路由对prompt段的占位文本（Trellis 模型会忽略它）；真正起作用的是查询参数model、resolution、key和image。model值中的/需要编码为%2F。

该路由在源码中的定义位于 generation-executor.ts 与 proxy.ts：

// generation-executor.ts generationExecutorRoutes.get( "/3d/:prompt{[\\s\\S]+}", validator("param", z.object({ prompt: z.string().min(1) })), validator("query", Generate3dRequestQueryParamsSchema), ...model3dHandlers, );

prompt段使用[\s\S]+正则匹配任意非空内容，因此占位文本可以是任何非空字符串，比如官方示例中的no_prompt_for_trellis_needed。

二、快速开始：发送你的第一个 3D 生成请求

2.1 使用 cURL

参考官方 quick-start.md 中的 3D 示例，用 cURL 下载一个 GLB 模型：

curl "https://gen.pollinations.ai/3d/no_prompt_for_trellis_needed?image=https://inferenceport.ai/img/trellis.jpg&model=microsoft%2Ftrellis-2&resolution=low" \ -H "Authorization: Bearer YOUR_API_KEY" -o model.glb

两点提醒：

1. 认证：3D 生成与文本、图像一样，所有生成请求都需要 API Key。两种认证方式任选其一（详见 authentication.md）：
   • 请求头：Authorization: Bearer YOUR_API_KEY；
   • 查询参数：?key=YOUR_API_KEY（也就是官方示例 URL 中的写法）。
2. URL 编码：image参数值本身是 URL，若图片 URL 中带有&等字符，必须整体编码（或将其放在查询串末尾）。若图片 URL 非法（非http:///https://开头），服务端会返回 400，错误信息形如Invalid image URL. Put image= param last in your URL, or URL-encode it.（见 model3d.ts schema）。

2.2 响应保存

响应体就是模型二进制文件，默认以inline; filename="<prompt 派生名>.glb"的Content-Disposition返回，文件名由路径 prompt 清洗（保留字母数字与连字符、截断至 100 字符）后生成，空 prompt 时回退为generated-model（见 handler.ts）：

Content-Type: model/gltf-binary Content-Disposition: inline; filename="no-prompt-for-trellis-needed.glb" Cache-Control: public, max-age=..., immutable

响应头中还包含x-model-used、x-generation-id、x-usage-*等计费与追踪信息（见 handler.ts 与 media-cache.ts）。

三、请求参数详解

3D 端点支持的全部参数由两处 schema 定义：GET 查询参数 Generate3dRequestQueryParamsSchema 与运行期校验 Model3dParamsSchema。合并整理如下：

3.1 image 参数的多图语义

image支持两种分隔符：逗号或竖线。源码中通过字符串拆分实现（params.ts）：

return value.includes("|") ? value.split("|") : value.split(",");

不过当前 3D 模型族（Trellis 2、Asset Harvester、Rodin）在注册表中均声明maxReferenceImages: 1（见 model3d.ts），实际使用时每个模型只消费第一张图（见下文模型实现）。

3.2 seed 的缓存键语义（容易被忽略）

seed参数的行为值得特别说明：并不是所有模型都原生支持 seed。从 params.ts 的注释可知，seed之所以被接受，是为了让它进入 media 缓存键——对同一 prompt + 图片的请求，只要改seed就能强制触发一次新的生成，从而获得不同结果。测试 trellis2Model.test.ts 明确验证了：Trellis 2 走 InferencePort 时不会把 seed 转发给上游（inferenceport 侧支持性未确认）；而 Rodin 走 fal 时会透传 seed（见 rodinModel.ts 与集成测试 post.test.ts）。

四、可用模型族：输入规则与适用场景

官方文档中的{{3D_MODELS}}是模板变量，在构建文档页时由 docs.ts 从实时模型注册表动态填充。当前注册表（model3d.ts）包含三个基础模型与一个 fal 回退变体：

模型分发逻辑集中在 createAndReturnModel3d.ts：按model字段 switch 到对应实现，未知模型直接抛错。

4.1 纯图片模型：忽略文本提示

Trellis 2 与 Asset Harvester 是 image-to-3D 模型，文本 prompt 不会进入上游请求。以 Trellis 2 的 InferencePort 实现为例（trellis2Model.ts）：

requireImages(params, "microsoft/trellis-2"); // 无图片直接 400 const result = await runInferenceport({ model: TRELLIS2_INFERENCEPORT_MODEL_ID, // "trellis2" imageUrls: [params.image[0]], // 仅取第一张图 resolution: params.resolution, });

requireImages（modelUtils.ts）会在image为空时抛出 400：microsoft/trellis-2 requires at least one reference image (image= param)。这也是为什么官方示例的 URL 路径里写着no_prompt_for_trellis_needed——这段文本真的不会被用到。

4.2 文本 + 图片混合模型：Hyper3D Rodin 2.5

hyper3d/rodin-2.5是三者中唯一的"全能"模型：既有文本也有图片时走 image-to-3D 端点，仅文本时走 text-to-3D 端点（rodinModel.ts）：

export const RODIN_IMAGE_ENDPOINT = "fal-ai/hyper3d/rodin/v2.5/fast"; export const RODIN_TEXT_ENDPOINT = "fal-ai/hyper3d/rodin/v2.5/text-to-3d/fast";

代码注释说明：fal 的 image-to-3D 端点要求image_urls必填，纯文本请求会 422，因此必须分流到专用 text-to-3D 端点；反之，纯文本请求也不得携带图片参数。

五、分辨率三档与计费规则

resolution参数只在microsoft/trellis-2上生效，支持low/medium/high三档：

• fal 回退路径（trellis2FalModel.ts）明确把三档映射为体素网格分辨率：low → 512、medium → 1024、high → 1536；
• InferencePort 路径则把resolution原样透传给上游（见 inferenceportClient.ts 的buildBody）。

计费上，注册表为 Trellis 2 定义了与分辨率挂钩的成本变体（model3d.ts），按completionImageTokens这一复用字段计费（实际为"每次生成"的扁平费用，见文件头注释）：

其余模型为固定费率：nvidia/asset-harvester0.07 / 次，hyper3d/rodin-2.50.10 / 次。

付费门槛差异（官方文档明确提示）：

hyper3d/rodin-2.5和nvidia/asset-harvester需要 Paid Pollen；microsoft/trellis-2（默认）支持low、medium、high三档分辨率，并且可以配合 Quest Pollen 使用。

注册表中对应paidOnly字段：Trellis 2 为false，Asset Harvester 与 Rodin 为true（fal 托管的模型限制为付费余额，见 model3d.ts）。集成测试也验证了计费链路：分辨率low计 0.24、high计 0.35，账单余额同步扣减（post.test.ts）。

六、NVIDIA Asset Harvester：PLY 高斯泼溅输出

官方文档专门为nvidia/asset-harvester开辟了一节，本文完整继承并展开：

nvidia/asset-harvester生成的是3D Gaussian Splat（3D 高斯泼溅）模型，输出格式为 PLY。这与其余模型的 GLB 输出有本质区别：

• GLB 是传统的网格（mesh）表示，适合游戏引擎与渲染管线的常规加载；
• PLY 在这里承载的是高斯泼溅点云，适合实时渲染场景，可直接在 SuperSplat、Three.js（配合 Gaussian PLY loader）等高斯泼溅查看器中打开浏览。

源码层面，该实现位于 assetHarvesterModel.ts：通过 InferencePort 提交asset-harvester作业，从完成结果中取model_ply_b64_bytes字段解码为 Buffer，并固定声明contentType: "model/ply"。响应侧也会据此调整Content-Disposition的文件后缀（handler.ts）：

if (contentType === "model/ply") { return `inline; filename="${filename}.ply"`; } return `inline; filename="${filename}.glb"`;

InferencePort 客户端还确认该作业会附带orbit_video_b64_bytes（环绕视频）字段，服务端当前只取 PLY 主体返回（见 inferenceportClient.ts）。

七、底层实现：两套提供商管道的调用链

从源码结构看，3D 模块（src/model3d）围绕两个异步作业型提供商客户端组织，公共入口是generate3dResponse（handler.ts），并经由withModelFallbackResponse支持失败回退。

7.1 InferencePort 管道（Trellis 2、Asset Harvester）

inferenceportClient.ts 实现了标准的异步作业模式：

1. POST https://api.inferenceport.ai/v1/3d/generations提交作业，body 含model、image_urls，可选prompt、resolution；
2. 拿到job_id后轮询GET /v1/3d/jobs/{job_id}；
3. 每 5 秒轮询一次，直到status === "completed"（从data[0]读取model_glb_b64_bytes或model_ply_b64_bytes）或failed；
4. 整体作业超时上限 300 秒，超时抛 504。

值得注意的实现细节：轮询期间的 GET 遇到 5xx 会重试而非放弃（注释明确"失败的状态查询不代表生成失败，绝不重复提交作业"）。HTTP 状态码归类：400/422视为请求校验失败、429限流、402余额不足，其余视为上游故障（inferenceportClient.ts）。

7.2 fal.ai 队列管道（Rodin 2.5、Trellis 2 fal 回退）

falClient.ts 封装了 fal 的队列式 API：

1. POST https://queue.fal.run/{endpoint}，认证头Authorization: Key $FAL_KEY；
2. 从提交响应中取status_url与response_url；
3. 每 5 秒轮询status_url，直到status === "COMPLETED"；
4. 取response_url结果，并从model_mesh或model_glb字段提取网格下载地址（fal 不同模型输出字段不一致，代码兼容两种命名，见 falClient.ts），最后下载网格文件转为 Buffer。

环境变量：两条管道分别依赖INFERENCEPORT_API_KEY与FAL_KEY，由 env.ts 在请求开始时从 Cloudflare Bindings 同步到模块级 Map（缺 Key 时直接抛错提示）。

7.3 回退机制

microsoft/trellis-2:fal是注册表中的显式回退变体（model3d-fallbacks.ts，2026-09-01 加入，费率 0.25/0.30/0.35）。它通过 fal 的fal-ai/trellis-2端点实现同款 image-to-3D 能力，并在trackingData中标记actualModel: "microsoft/trellis-2:fal"（trellis2FalModel.ts），供计费追踪区分实际使用路径。

八、缓存与计费：同样的请求只生成一次

3D 结果使用与图像/音频相同的 media 缓存框架（media-cache.ts），配置项mediaTypes: ["model/"]，即所有model/*内容类型的结果都会写入 R2（MEDIA桶）：

• 命中缓存时返回X-Cache: HIT，并统一打上 immutable 的Cache-Control；
• 缓存键是对完整请求 URL（含按序排列的全部查询参数）做 SHA-256 哈希，nofeed、no-cache、key三个参数被排除在键之外（见 media-cache.ts）——因此key不影响缓存复用，同一参数组合的重复请求不会重复计费；
• 集成测试 post.test.ts 验证了"不同 resolution + seed 组合产生不同缓存键、命中 HIT、上游只收到两笔作业"的行为。

这引出一个实用技巧：若想强制重新生成，改变seed是最简单的办法（见 3.2 节）。

九、错误处理与超时重试

3D 端点遵循平台统一的错误格式（见 errors.md）：

{ "status": 400, "success": false, "error": { "code": "BAD_REQUEST", "message": "Description of what went wrong" } }

与 3D 场景直接相关的状态码：

集成测试对非法参数做了穷举验证：safe: true（POST body 不接受）、format: "glb"、resolution: "ultra"、image: "ftp://..."、seed: "42"（body 中必须为整数）均返回 400（post.test.ts）。

超时重试语义（官方文档明确）：若客户端或代理超时，只需原样重发完全相同的请求（端点、body、查询参数、seed 均不变）。服务端生成会继续在后台完成，重试会命中缓存或在途去重（deduplication），不会触发二次生成、二次计费。该规则适用于 3D 在内的所有缓存型非流式端点。

十、POST 变体与 OpenAI 兼容入口

除 GET 外，平台还提供两套补充入口：

10.1 POST /3d/:prompt（JSON body）

POST /3d/{prompt}支持把参数放进 JSON body（proxy.ts），body schema 见 Generate3dRequestBodySchema：model、image（字符串或数组，字符串视为一个完整 URL）、resolution（默认low）、seed（整数）。image数组可传递带&等字符的复杂 URL 而无需编码，这是相对 GET 的主要优势。测试覆盖了 body 传hyper3d-rodin+image+seed被原样转发到 fal 的场景。

10.2 OpenAI 兼容的文本转 3D

/v1/responses与/v1/chat/completions端点同样能驱动 3D 生成：当请求中指定hyper3d/rodin-2.5这类文本模型时，会走 Rodin 的 text-to-3D fal 端点，响应以[3D model](https://link.gitcode.com/i/f82444c753dd986d446a9ea3b880b2ae) 验证了两种协议行为一致、只计费一次）。这意味着你可以用标准的 OpenAI SDK（base_url="https://gen.pollinations.ai/v1"`）以聊天方式生成 3D 模型。

十一、模型清单查询：/3d/models

想确认当前可用模型与最新状态，无需翻阅文档：GET https://gen.pollinations.ai/3d/models会返回全部 3D 模型（含定价、能力、元数据与健康状态），已认证时按 API Key 权限过滤（paid_only模型在无付费余额时隐藏）。该端点由 proxy.ts 定义，实现上从MODEL3D_SERVICES注册表动态读取模型列表（与文档页{{3D_MODELS}}变量同源）。

十二、测试与验证参考

3D 模块测试完整覆盖了参数校验、上游调用契约、缓存与计费链路，可作为理解实现的补充材料：

• trellis2Model.test.ts：验证 async 作业 API、trellis2模型名、三档分辨率透传、GLB 内容类型、缺图报错、seed 不转发；
• post.test.ts：端到端验证 POST/GET /3d、缓存命中、计费金额、认证（401）、参数校验（400）、Rodin 的 fal 请求体、OpenAI 兼容文本转 3D；
• assetHarvesterModel.test.ts、rodinModel.test.ts、trellis2FalModel.test.ts：分别覆盖 PLY 输出、双端点分流、分辨率映射。

结语

Pollinations 的 3D 生成接口保持了平台"一条 URL 出结果"的极简体验，但背后是注册表驱动的模型编排、InferencePort 与 fal 两套异步作业管道、R2 media 缓存与统一计费框架的协同。无论你要做游戏资产批量生产、高斯泼溅实时场景构建，还是让 Agent 通过 OpenAI 兼容接口直接产出 3D 模型，掌握本文的参数语义与缓存规则（尤其是seed与重试的用法），都能帮助你写出正确、省钱的调用代码。

• AI 应用
• 媒体生成
• 后端
• 前端