通过 Comfy Router 使用混元3D智能拓扑

通过 Comfy Router 调用 tencent/hunyuan-3d-smart-topology：端点、请求形状以及 Router 返回的响应。

tencent/hunyuan-3d-smart-topology 的 API 参考，由 Comfy Router 提供，模型来源为 Tencent。

输入： 3D · 输出： 3D

快速开始

在你的 Comfy 工作区中创建一个密钥，并将其导出为 COMFY_API_KEY。Python 和 TypeScript 代码片段使用 Comfy SDK（pip install comfy-sdk 和 npm install @comfyorg/sdk）；cURL 代码片段是通过原始 HTTP 进行的同一调用。

模型 ID： tencent/hunyuan-3d-smart-topology

端点： POST https://api.comfy.org/v2/models/tencent/hunyuan-3d-smart-topology

[tab] 等待结果 ``python Python theme={null} from comfy_sdk import Comfy # 从环境变量中读取 COMFY_API_KEY。 # SDK 会自动创建幂等键，并在自动重试时复用它。 with Comfy() as client: result = client.models.run( "tencent/hunyuan-3d-smart-topology", { "File3D": { "Type": "GLB", "Url": "https://vcg-test-1258344699.cos.ap-guangzhou.myqcloud.com/test/3d/test.glb", }, }, ) print(result) ` `typescript TypeScript theme={null} import { comfy } from "@comfyorg/sdk"; // 从环境变量中读取 COMFY_API_KEY。 // SDK 会自动创建幂等键，并在自动重试时复用它。 const { data } = await comfy.models.run("tencent/hunyuan-3d-smart-topology", { File3D: { Type: "GLB", Url: "https://vcg-test-1258344699.cos.ap-guangzhou.myqcloud.com/test/3d/test.glb", }, }); console.log(data); ` `bash cURL theme={null} curl https://api.comfy.org/v2/models/tencent/hunyuan-3d-smart-topology \ -H "X-API-Key: $COMFY_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d "{\"File3D\": {\"Type\":\"GLB\",\"Url\":\"https://vcg-test-1258344699.cos.ap-guangzhou.myqcloud.com/test/3d/test.glb\"}}" ``

[tab] 排队并稍后收集 将相同的请求体发送到 POST https://api.comfy.org/v2/models/tencent/hunyuan-3d-smart-topology/requests。运行被受理后，Router 会立即返回 201 和 request_id；结果就绪后，可以从本进程或其他进程收集。状态、取消与收集的细节见 队列投递。 ``python Python theme={null} import asyncio from comfy_sdk import AsyncComfy # 从环境变量中读取 COMFY_API_KEY。 # 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。 async def main(): async with AsyncComfy() as client: handle = await client.models.submit( "tencent/hunyuan-3d-smart-topology", { "File3D": { "Type": "GLB", "Url": "https://vcg-test-1258344699.cos.ap-guangzhou.myqcloud.com/test/3d/test.glb", }, }, ) print("request_id:", handle.request_id) # 配合模型 ID，这就是另一个进程所需的全部信息 # 轮询直到请求完成，按服务器指定的 Retry-After 等待。 async for update in handle.iter_events(): print(update.status, update.queue_position) # 提供商自己的载荷，与 models.run() 返回的值相同。 # 失败或已取消的请求会在此处抛出类型化的 Router 错误。 result = await handle.get() print(result) asyncio.run(main()) ` `typescript TypeScript theme={null} import { comfy } from "@comfyorg/sdk"; // 从环境变量中读取 COMFY_API_KEY。 // 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。 const handle = await comfy.models.submit("tencent/hunyuan-3d-smart-topology", { File3D: { Type: "GLB", Url: "https://vcg-test-1258344699.cos.ap-guangzhou.myqcloud.com/test/3d/test.glb", }, }); console.log("requestId:", handle.requestId); // 配合模型 ID，这就是另一个进程所需的全部信息 // 轮询直到请求完成，按服务器指定的 Retry-After 等待。 for await (const update of handle.events()) { console.log(update.status, update.queuePosition); } // 与 models.run() 返回的结果相同。失败或已取消的请求会在此处被拒绝。 const result = await handle.get(); console.log(result.data); ` `bash cURL theme={null} # 1. 提交。Router 返回 201，以及 request_id、status_url、response_url 和 cancel_url。 curl https://api.comfy.org/v2/models/tencent/hunyuan-3d-smart-topology/requests \ -H "X-API-Key: $COMFY_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d "{\"File3D\": {\"Type\":\"GLB\",\"Url\":\"https://vcg-test-1258344699.cos.ap-guangzhou.myqcloud.com/test/3d/test.glb\"}}" # 2. 轮询直到状态为 COMPLETED，每次响应都按其中指定的 Retry-After 秒数等待。 REQUEST_ID="<request_id from the 201 body>" curl -i https://api.comfy.org/v2/models/tencent/hunyuan-3d-smart-topology/requests/$REQUEST_ID/status \ -H "X-API-Key: $COMFY_API_KEY" # 3. 收集。返回 200 时包含模型的原生输出；仍在运行时返回 202 及状态响应体。 curl https://api.comfy.org/v2/models/tencent/hunyuan-3d-smart-topology/requests/$REQUEST_ID \ -H "X-API-Key: $COMFY_API_KEY" ``

Schema

输入

FaceLevel string

多边形减面级别。

可选值：high、medium、low

File3D object required

用于智能拓扑的 3D 文件输入

File3D.Type string required

3D 文件格式类型

可选值：OBJ、GLB

File3D.Url string (uri) required

需要重新拓扑的 3D 文件网址

格式：uri

PolygonType string

输出网格的多边形类型。默认为三角形。

可选值：triangle、quadrilateral

该内容由 Router 在 GET /v2/models/tencent/hunyuan-3d-smart-topology/openapi.json 提供的 schema 生成，也是请求到达提供商之前用于校验调用的同一份文档。

输出

Response object required

Response.ErrorCode string

腾讯的错误码，文档说明在无错误时为空字符串。一旦存在 Status，Router 便不再读取该字段。

Response.ErrorMessage string

腾讯的报错信息，文档说明在无错误时为空字符串。一旦存在 Status，Router 便不再读取该字段。

Response.RequestId string

腾讯自己的请求标识符，用于向腾讯排查问题。它既不是任务ID，也不是资产。

Response.ResultFile3Ds object[] required

已完成任务生成的 3D 文件。在 Router 返回的文档中该字段存在且非空；至少一个条目带有可获取的 Url。这些链接由腾讯提供，文档说明有效期为 24 小时。

Response.ResultFile3Ds\[].PreviewImageUrl string (uri)

预览图像网址

格式：uri

Response.ResultFile3Ds\[].Type string

文件格式。已完成的任务可能返回多个条目，顺序不固定，而且并非每个条目都是网格：已观察到 UV 和智能拓扑操作在返回 OBJ、GLB 和 FBX 网格的同时还会返回一个 IMAGE（PNG 纹理）。请按 Type 而不是按位置选择条目。此处有意不将其设为枚举：上述取值只是已观察到的取值，该组件还与输出从未被观察过的操作（part、texture-edit）共用，而且输出 schema 是描述性的，因此腾讯返回的未列出取值不得把一个正常结果变成 schema 违规。

Response.ResultFile3Ds\[].Url string (uri)

文件网址（有效期 24 小时）

格式：uri

Response.Status string required

可选值：DONE

示例

输入

{
  "File3D": {
    "Type": "GLB",
    "Url": "https://vcg-test-1258344699.cos.ap-guangzhou.myqcloud.com/test/3d/test.glb"
  }
}

输出

{
  "Response": {
    "ErrorCode": "",
    "ErrorMessage": "",
    "RequestId": "9a1c0d4e-77b2-4e0c-8f2e-2f9a1c0d4e77",
    "ResultFile3Ds": [
      {
        "PreviewImageUrl": "https://example.invalid/tencent/hunyuan-3d-smart-topology/preview.png",
        "Type": "GLB",
        "Url": "https://example.invalid/tencent/hunyuan-3d-smart-topology/retopologised.glb"
      }
    ],
    "Status": "DONE"
  }
}

发布前须知

SDK 会生成 Idempotency-Key 并在自动重试中复用它。手动重试时，请复用原始 key。Router 最长可保持连接 10 分钟。

请求失败时，Router 会发送 X-Comfy-Error-Type 响应头说明原因。422 表示 Router 在调用提供商之前就拒绝了输入，413 表示请求体超出了 Router 可接受的大小。已生成的资源请及时下载，因为结果 URL 会过期。

上文任何字段描述中提到的尺寸限制，都是提供商对该字段自身的限定，引自提供商的规范。Router 会对整个请求体另行设置上限，base64 编码的媒体内容也计入其中：参见请求体大小。

本页记录的是通过 Comfy Router 调用的某一个合作伙伴模型。同一个 comfy-sdk / @comfyorg/sdk 包还提供第二个客户端，用于在 Comfy Cloud 上运行完整的 ComfyUI 工作流图：Comfy(api_key=...) / new Comfy({ apiKey })，并带有 client.workflows、client.assets 和 client.jobs。请参阅 Comfy SDKs。

[card] 请求头 身份验证、幂等性、请求 ID、错误分类、重试节奏、消费限额。

[card] 使用 Router API 模型发现、验证错误、重试与计费。

[card] 限制 Router 目前不支持的功能，以及替代方案。