使用 Comfy Router 调用混元3D 纹理编辑

通过 Comfy Router 调用 tencent/hunyuan-3d-texture-edit：端点、请求结构以及 Router 返回的响应。

tencent/hunyuan-3d-texture-edit 的 API 参考，由 Comfy Router 从腾讯提供。

输入： 3D, 文本 · 输出： 3D

快速开始

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

模型 ID： tencent/hunyuan-3d-texture-edit

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

[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-texture-edit", { "File3D": { "Type": "FBX", "Url": "https://vcg-test-1258344699.cos.ap-guangzhou.myqcloud.com/test/3d/test.fbx", }, "Prompt": "a kitten", }, ) print(result) ` `typescript TypeScript theme={null} import { comfy } from "@comfyorg/sdk"; // 从环境变量中读取 COMFY_API_KEY。 // SDK 会自动创建幂等键，并在自动重试时复用它。 const { data } = await comfy.models.run("tencent/hunyuan-3d-texture-edit", { File3D: { Type: "FBX", Url: "https://vcg-test-1258344699.cos.ap-guangzhou.myqcloud.com/test/3d/test.fbx", }, Prompt: "a kitten", }); console.log(data); ` `bash cURL theme={null} curl https://api.comfy.org/v2/models/tencent/hunyuan-3d-texture-edit \ -H "X-API-Key: $COMFY_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d "{\"File3D\": {\"Type\":\"FBX\",\"Url\":\"https://vcg-test-1258344699.cos.ap-guangzhou.myqcloud.com/test/3d/test.fbx\"}, \"Prompt\": \"a kitten\"}" ``

[tab] 排队并稍后收集 将相同的请求体发送到 POST https://api.comfy.org/v2/models/tencent/hunyuan-3d-texture-edit/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-texture-edit", { "File3D": { "Type": "FBX", "Url": "https://vcg-test-1258344699.cos.ap-guangzhou.myqcloud.com/test/3d/test.fbx", }, "Prompt": "a kitten", }, ) 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-texture-edit", { File3D: { Type: "FBX", Url: "https://vcg-test-1258344699.cos.ap-guangzhou.myqcloud.com/test/3d/test.fbx", }, Prompt: "a kitten", }); 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-texture-edit/requests \ -H "X-API-Key: $COMFY_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d "{\"File3D\": {\"Type\":\"FBX\",\"Url\":\"https://vcg-test-1258344699.cos.ap-guangzhou.myqcloud.com/test/3d/test.fbx\"}, \"Prompt\": \"a kitten\"}" # 2. 轮询直到状态为 COMPLETED，按每次响应给出的 Retry-After 秒数等待。 REQUEST_ID="<request_id from the 201 body>" curl -i https://api.comfy.org/v2/models/tencent/hunyuan-3d-texture-edit/requests/$REQUEST_ID/status \ -H "X-API-Key: $COMFY_API_KEY" # 3. 收集。200 表示模型的原始输出；仍在运行时返回 202 及状态响应体。 curl https://api.comfy.org/v2/models/tencent/hunyuan-3d-texture-edit/requests/$REQUEST_ID \ -H "X-API-Key: $COMFY_API_KEY" ``

Schema

输入

EnablePBR boolean

是否启用 PBR 纹理参数；仅在使用 Prompt 时支持。

File3D object required

用于纹理编辑的 3D 文件输入

File3D.Type string required

3D 文件格式类型

可选值：FBX

File3D.Url string (uri) required

需要编辑纹理的 3D 文件的 URL

格式：uri

Image object

参考图像：Base64 数据或图片网址

Image.Base64 string

Base64 编码的图像。每边分辨率 128-4096，转换后的 Base64 小于 10MB。格式为 jpg、jpeg、png。

Image.Url string (uri)

图片网址。如果同时提供 Base64 和 Url，以 Url 为准。

格式：uri

Prompt string

描述纹理编辑。Image 或 Prompt 必须提供其一，两者不能同时提供。

由 Router 在 GET /v2/models/tencent/hunyuan-3d-texture-edit/openapi.json 提供的数据结构生成，这也是请求到达提供商之前 Router 用于校验调用的同一份文档。

输出

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": "FBX",
    "Url": "https://vcg-test-1258344699.cos.ap-guangzhou.myqcloud.com/test/3d/test.fbx"
  },
  "Prompt": "a kitten"
}

输出

{
  "Response": {
    "ErrorCode": "",
    "ErrorMessage": "",
    "RequestId": "9a1c0d4e-77b2-4e0c-8f2e-2f9a1c0d4e77",
    "ResultFile3Ds": [
      {
        "PreviewImageUrl": "https://example.invalid/tencent/hunyuan-3d-texture-edit/preview.png",
        "Type": "GLB",
        "Url": "https://example.invalid/tencent/hunyuan-3d-texture-edit/retextured.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 目前不支持的功能，以及替代方案。