Skip to content

The most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. The fastest local inference engine in the world.

[API Nodes] add TencentHunyuan3D nodes (#12026)

Alexander Piskunbc72d7f8d11a
diff --git a/comfy_api_nodes/apis/hunyuan3d.py b/comfy_api_nodes/apis/hunyuan3d.py
new file mode 100644
index 000000000..6421c9bd5
--- /dev/null
+++ b/comfy_api_nodes/apis/hunyuan3d.py
@@ -0,0 +1,66 @@
+from typing import TypedDict
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class InputGenerateType(TypedDict):
+ generate_type: str
+ polygon_type: str
+ pbr: bool
+
+
+class Hunyuan3DViewImage(BaseModel):
+ ViewType: str = Field(..., description="Valid values: back, left, right.")
+ ViewImageUrl: str = Field(...)
+
+
+class To3DProTaskRequest(BaseModel):
+ Model: str = Field(...)
+ Prompt: str | None = Field(None)
+ ImageUrl: str | None = Field(None)
+ MultiViewImages: list[Hunyuan3DViewImage] | None = Field(None)
+ EnablePBR: bool | None = Field(...)
+ FaceCount: int | None = Field(...)
+ GenerateType: str | None = Field(...)
+ PolygonType: str | None = Field(...)
+
+
+class RequestError(BaseModel):
+ Code: str = Field("")
+ Message: str = Field("")
+
+
+class To3DProTaskCreateResponse(BaseModel):
+ JobId: str | None = Field(None)
+ Error: RequestError | None = Field(None)
+
+ @model_validator(mode="before")
+ @classmethod
+ def unwrap_data(cls, values: dict) -> dict:
+ if "Response" in values and isinstance(values["Response"], dict):
+ return values["Response"]
+ return values
+
+
+class ResultFile3D(BaseModel):
+ Type: str = Field(...)
+ Url: str = Field(...)
+ PreviewImageUrl: str = Field("")
+
+
+class To3DProTaskResultResponse(BaseModel):
+ ErrorCode: str = Field("")
+ ErrorMessage: str = Field("")
+ ResultFile3Ds: list[ResultFile3D] = Field([])
+ Status: str = Field(...)
+
+ @model_validator(mode="before")
+ @classmethod
+ def unwrap_data(cls, values: dict) -> dict:
+ if "Response" in values and isinstance(values["Response"], dict):
+ return values["Response"]
+ return values
+
+
+class To3DProTaskQueryRequest(BaseModel):
+ JobId: str = Field(...)
diff --git a/comfy_api_nodes/nodes_hunyuan3d.py b/comfy_api_nodes/nodes_hunyuan3d.py
new file mode 100644
index 000000000..b3a736643
--- /dev/null
+++ b/comfy_api_nodes/nodes_hunyuan3d.py
@@ -0,0 +1,297 @@
+import os
+
+from typing_extensions import override
+
+from comfy_api.latest import IO, ComfyExtension, Input
+from comfy_api_nodes.apis.hunyuan3d import (
+ Hunyuan3DViewImage,
+ InputGenerateType,
+ ResultFile3D,
+ To3DProTaskCreateResponse,
+ To3DProTaskQueryRequest,
+ To3DProTaskRequest,
+ To3DProTaskResultResponse,
+)
+from comfy_api_nodes.util import (
+ ApiEndpoint,
+ download_url_to_bytesio,
+ downscale_image_tensor_by_max_side,
+ poll_op,
+ sync_op,
+ upload_image_to_comfyapi,
+ validate_image_dimensions,
+ validate_string,
+)
+from folder_paths import get_output_directory
+
+
+def get_glb_obj_from_response(response_objs: list[ResultFile3D]) -> ResultFile3D:
+ for i in response_objs:
+ if i.Type.lower() == "glb":
+ return i
+ raise ValueError("No GLB file found in response. Please report this to the developers.")
+
+
+class TencentTextToModelNode(IO.ComfyNode):
+
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="TencentTextToModelNode",
+ display_name="Hunyuan3D: Text to Model (Pro)",
+ category="api node/3d/Tencent",
+ inputs=[
+ IO.Combo.Input(
+ "model",
+ options=["3.0", "3.1"],
+ tooltip="The LowPoly option is unavailable for the `3.1` model.",
+ ),
+ IO.String.Input("prompt", multiline=True, default="", tooltip="Supports up to 1024 characters."),
+ IO.Int.Input("face_count", default=500000, min=40000, max=1500000),
+ IO.DynamicCombo.Input(
+ "generate_type",
+ options=[
+ IO.DynamicCombo.Option("Normal", [IO.Boolean.Input("pbr", default=False)]),
+ IO.DynamicCombo.Option(
+ "LowPoly",
+ [
+ IO.Combo.Input("polygon_type", options=["triangle", "quadrilateral"]),
+ IO.Boolean.Input("pbr", default=False),
+ ],
+ ),
+ IO.DynamicCombo.Option("Geometry", []),
+ ],
+ ),
+ IO.Int.Input(
+ "seed",
+ default=0,
+ min=0,
+ max=2147483647,
+ display_mode=IO.NumberDisplay.number,
+ control_after_generate=True,
+ tooltip="Seed controls whether the node should re-run; "
+ "results are non-deterministic regardless of seed.",
+ ),
+ ],
+ outputs=[
+ IO.String.Output(display_name="model_file"),
+ ],
+ hidden=[
+ IO.Hidden.auth_token_comfy_org,
+ IO.Hidden.api_key_comfy_org,
+ IO.Hidden.unique_id,
+ ],
+ is_api_node=True,
+ is_output_node=True,
+ price_badge=IO.PriceBadge(
+ depends_on=IO.PriceBadgeDepends(widgets=["generate_type", "generate_type.pbr", "face_count"]),
+ expr="""
+ (
+ $base := widgets.generate_type = "normal" ? 25 : widgets.generate_type = "lowpoly" ? 30 : 15;
+ $pbr := $lookup(widgets, "generate_type.pbr") ? 10 : 0;
+ $face := widgets.face_count != 500000 ? 10 : 0;
+ {"type":"usd","usd": ($base + $pbr + $face) * 0.02}
+ )
+ """,
+ ),
+ )
+
+ @classmethod
+ async def execute(
+ cls,
+ model: str,
+ prompt: str,
+ face_count: int,
+ generate_type: InputGenerateType,
+ seed: int,
+ ) -> IO.NodeOutput:
+ _ = seed
+ validate_string(prompt, field_name="prompt", min_length=1, max_length=1024)
+ if model == "3.1" and generate_type["generate_type"].lower() == "lowpoly":
+ raise ValueError("The LowPoly option is currently unavailable for the 3.1 model.")
+ response = await sync_op(
+ cls,
+ ApiEndpoint(path="/proxy/tencent/hunyuan/3d-pro", method="POST"),
+ response_model=To3DProTaskCreateResponse,
+ data=To3DProTaskRequest(
+ Model=model,
+ Prompt=prompt,
+ FaceCount=face_count,
+ GenerateType=generate_type["generate_type"],
+ EnablePBR=generate_type.get("pbr", None),
+ PolygonType=generate_type.get("polygon_type", None),
+ ),
+ )
+ if response.Error:
+ raise ValueError(f"Task creation failed with code {response.Error.Code}: {response.Error.Message}")
+ result = await poll_op(
+ cls,
+ ApiEndpoint(path="/proxy/tencent/hunyuan/3d-pro/query", method="POST"),
+ data=To3DProTaskQueryRequest(JobId=response.JobId),
+ response_model=To3DProTaskResultResponse,
+ status_extractor=lambda r: r.Status,
+ )
+ model_file = f"hunyuan_model_{response.JobId}.glb"
+ await download_url_to_bytesio(
+ get_glb_obj_from_response(result.ResultFile3Ds).Url,
+ os.path.join(get_output_directory(), model_file),
+ )
+ return IO.NodeOutput(model_file)
+
+
+class TencentImageToModelNode(IO.ComfyNode):
+
+ @classmethod
+ def define_schema(cls):
+ return IO.Schema(
+ node_id="TencentImageToModelNode",
+ display_name="Hunyuan3D: Image(s) to Model (Pro)",
+ category="api node/3d/Tencent",
+ inputs=[
+ IO.Combo.Input(
+ "model",
+ options=["3.0", "3.1"],
+ tooltip="The LowPoly option is unavailable for the `3.1` model.",
+ ),
+ IO.Image.Input("image"),
+ IO.Image.Input("image_left", optional=True),
+ IO.Image.Input("image_right", optional=True),
+ IO.Image.Input("image_back", optional=True),
+ IO.Int.Input("face_count", default=500000, min=40000, max=1500000),
+ IO.DynamicCombo.Input(
+ "generate_type",
+ options=[
+ IO.DynamicCombo.Option("Normal", [IO.Boolean.Input("pbr", default=False)]),
+ IO.DynamicCombo.Option(
+ "LowPoly",
+ [
+ IO.Combo.Input("polygon_type", options=["triangle", "quadrilateral"]),
+ IO.Boolean.Input("pbr", default=False),
+ ],
+ ),
+ IO.DynamicCombo.Option("Geometry", []),
+ ],
+ ),
+ IO.Int.Input(
+ "seed",
+ default=0,
+ min=0,
+ max=2147483647,
+ display_mode=IO.NumberDisplay.number,
+ control_after_generate=True,
+ tooltip="Seed controls whether the node should re-run; "
+ "results are non-deterministic regardless of seed.",
+ ),
+ ],
+ outputs=[
+ IO.String.Output(display_name="model_file"),
+ ],
+ hidden=[
+ IO.Hidden.auth_token_comfy_org,
+ IO.Hidden.api_key_comfy_org,
+ IO.Hidden.unique_id,
+ ],
+ is_api_node=True,
+ is_output_node=True,
+ price_badge=IO.PriceBadge(
+ depends_on=IO.PriceBadgeDepends(
+ widgets=["generate_type", "generate_type.pbr", "face_count"],
+ inputs=["image_left", "image_right", "image_back"],
+ ),
+ expr="""
+ (
+ $base := widgets.generate_type = "normal" ? 25 : widgets.generate_type = "lowpoly" ? 30 : 15;
+ $multiview := (
+ inputs.image_left.connected or inputs.image_right.connected or inputs.image_back.connected
+ ) ? 10 : 0;
+ $pbr := $lookup(widgets, "generate_type.pbr") ? 10 : 0;
+ $face := widgets.face_count != 500000 ? 10 : 0;
+ {"type":"usd","usd": ($base + $multiview + $pbr + $face) * 0.02}
+ )
+ """,
+ ),
+ )
+
+ @classmethod
+ async def execute(
+ cls,
+ model: str,
+ image: Input.Image,
+ face_count: int,
+ generate_type: InputGenerateType,
+ seed: int,
+ image_left: Input.Image | None = None,
+ image_right: Input.Image | None = None,
+ image_back: Input.Image | None = None,
+ ) -> IO.NodeOutput:
+ _ = seed
+ if model == "3.1" and generate_type["generate_type"].lower() == "lowpoly":
+ raise ValueError("The LowPoly option is currently unavailable for the 3.1 model.")
+ validate_image_dimensions(image, min_width=128, min_height=128)
+ multiview_images = []
+ for k, v in {
+ "left": image_left,
+ "right": image_right,
+ "back": image_back,
+ }.items():
+ if v is None:
+ continue
+ validate_image_dimensions(v, min_width=128, min_height=128)
+ multiview_images.append(
+ Hunyuan3DViewImage(
+ ViewType=k,
+ ViewImageUrl=await upload_image_to_comfyapi(
+ cls,
+ downscale_image_tensor_by_max_side(v, max_side=4900),
+ mime_type="image/webp",
+ total_pixels=24_010_000,
+ ),
+ )
+ )
+ response = await sync_op(
+ cls,
+ ApiEndpoint(path="/proxy/tencent/hunyuan/3d-pro", method="POST"),
+ response_model=To3DProTaskCreateResponse,
+ data=To3DProTaskRequest(
+ Model=model,
+ FaceCount=face_count,
+ GenerateType=generate_type["generate_type"],
+ ImageUrl=await upload_image_to_comfyapi(
+ cls,
+ downscale_image_tensor_by_max_side(image, max_side=4900),
+ mime_type="image/webp",
+ total_pixels=24_010_000,
+ ),
+ MultiViewImages=multiview_images if multiview_images else None,
+ EnablePBR=generate_type.get("pbr", None),
+ PolygonType=generate_type.get("polygon_type", None),
+ ),
+ )
+ if response.Error:
+ raise ValueError(f"Task creation failed with code {response.Error.Code}: {response.Error.Message}")
+ result = await poll_op(
+ cls,
+ ApiEndpoint(path="/proxy/tencent/hunyuan/3d-pro/query", method="POST"),
+ data=To3DProTaskQueryRequest(JobId=response.JobId),
+ response_model=To3DProTaskResultResponse,
+ status_extractor=lambda r: r.Status,
+ )
+ model_file = f"hunyuan_model_{response.JobId}.glb"
+ await download_url_to_bytesio(
+ get_glb_obj_from_response(result.ResultFile3Ds).Url,
+ os.path.join(get_output_directory(), model_file),
+ )
+ return IO.NodeOutput(model_file)
+
+
+class TencentHunyuan3DExtension(ComfyExtension):
+ @override
+ async def get_node_list(self) -> list[type[IO.ComfyNode]]:
+ return [
+ TencentTextToModelNode,
+ TencentImageToModelNode,
+ ]
+
+
+async def comfy_entrypoint() -> TencentHunyuan3DExtension:
+ return TencentHunyuan3DExtension()
diff --git a/comfy_api_nodes/nodes_kling.py b/comfy_api_nodes/nodes_kling.py
index 3ec71530b..739fe1855 100644
--- a/comfy_api_nodes/nodes_kling.py
+++ b/comfy_api_nodes/nodes_kling.py
@@ -249,7 +249,6 @@ async def finish_omni_video_task(cls: type[IO.ComfyNode], response: TaskStatusRe
ApiEndpoint(path=f"/proxy/kling/v1/videos/omni-video/{response.data.task_id}"),
response_model=TaskStatusResponse,
status_extractor=lambda r: (r.data.task_status if r.data else None),
- max_poll_attempts=160,
)
return IO.NodeOutput(await download_url_to_video_output(final_response.data.task_result.videos[0].url))
diff --git a/comfy_api_nodes/nodes_sora.py b/comfy_api_nodes/nodes_sora.py
index 87e663845..afc18bb25 100644
--- a/comfy_api_nodes/nodes_sora.py
+++ b/comfy_api_nodes/nodes_sora.py
@@ -149,7 +149,6 @@ class OpenAIVideoSora2(IO.ComfyNode):
response_model=Sora2GenerationResponse,
status_extractor=lambda x: x.status,
poll_interval=8.0,
- max_poll_attempts=160,
estimated_duration=int(45 * (duration / 4) * model_time_multiplier),
)
return IO.NodeOutput(
diff --git a/comfy_api_nodes/nodes_topaz.py b/comfy_api_nodes/nodes_topaz.py
index c052e7656..8fccde25a 100644
--- a/comfy_api_nodes/nodes_topaz.py
+++ b/comfy_api_nodes/nodes_topaz.py
@@ -203,7 +203,6 @@ class TopazImageEnhance(IO.ComfyNode):
progress_extractor=lambda x: getattr(x, "progress", 0),
price_extractor=lambda x: x.credits * 0.08,
poll_interval=8.0,
- max_poll_attempts=160,
estimated_duration=60,
)
diff --git a/comfy_api_nodes/util/__init__.py b/comfy_api_nodes/util/__init__.py
index 364976000..c3c9ff4bf 100644
--- a/comfy_api_nodes/util/__init__.py
+++ b/comfy_api_nodes/util/__init__.py
@@ -13,6 +13,7 @@ from .conversions import (
bytesio_to_image_tensor,
convert_mask_to_image,
downscale_image_tensor,
+ downscale_image_tensor_by_max_side,
image_tensor_pair_to_batch,
pil_to_bytesio,
resize_mask_to_image,
@@ -33,6 +34,7 @@ from .download_helpers import (
from .upload_helpers import (
upload_audio_to_comfyapi,
upload_file_to_comfyapi,
+ upload_image_to_comfyapi,
upload_images_to_comfyapi,
upload_video_to_comfyapi,
)
@@ -61,6 +63,7 @@ __all__ = [
# Upload helpers
"upload_audio_to_comfyapi",
"upload_file_to_comfyapi",
+ "upload_image_to_comfyapi",
"upload_images_to_comfyapi",
"upload_video_to_comfyapi",
# Download helpers
@@ -75,6 +78,7 @@ __all__ = [
"bytesio_to_image_tensor",
"convert_mask_to_image",
"downscale_image_tensor",
+ "downscale_image_tensor_by_max_side",
"image_tensor_pair_to_batch",
"pil_to_bytesio",
"resize_mask_to_image",
diff --git a/comfy_api_nodes/util/client.py b/comfy_api_nodes/util/client.py
index f372ec7b5..8a1259506 100644
--- a/comfy_api_nodes/util/client.py
+++ b/comfy_api_nodes/util/client.py
@@ -141,7 +141,7 @@ async def poll_op(
queued_statuses: list[str | int] | None = None,
data: BaseModel | None = None,
poll_interval: float = 5.0,
- max_poll_attempts: int = 120,
+ max_poll_attempts: int = 160,
timeout_per_poll: float = 120.0,
max_retries_per_poll: int = 3,
retry_delay_per_poll: float = 1.0,
@@ -238,7 +238,7 @@ async def poll_op_raw(
queued_statuses: list[str | int] | None = None,
data: dict[str, Any] | BaseModel | None = None,
poll_interval: float = 5.0,
- max_poll_attempts: int = 120,
+ max_poll_attempts: int = 160,
timeout_per_poll: float = 120.0,
max_retries_per_poll: int = 3,
retry_delay_per_poll: float = 1.0,
diff --git a/comfy_api_nodes/util/conversions.py b/comfy_api_nodes/util/conversions.py
index 546741b7b..0e15a0efe 100644
--- a/comfy_api_nodes/util/conversions.py
+++ b/comfy_api_nodes/util/conversions.py
@@ -144,6 +144,21 @@ def downscale_image_tensor(image: torch.Tensor, total_pixels: int = 1536 * 1024)
return s
+def downscale_image_tensor_by_max_side(image: torch.Tensor, *, max_side: int) -> torch.Tensor:
+ """Downscale input image tensor so the largest dimension is at most max_side pixels."""
+ samples = image.movedim(-1, 1)
+ height, width = samples.shape[2], samples.shape[3]
+ max_dim = max(width, height)
+ if max_dim <= max_side:
+ return image
+ scale_by = max_side / max_dim
+ new_width = round(width * scale_by)
+ new_height = round(height * scale_by)
+ s = common_upscale(samples, new_width, new_height, "lanczos", "disabled")
+ s = s.movedim(1, -1)
+ return s
+
+
def tensor_to_data_uri(
image_tensor: torch.Tensor,
total_pixels: int = 2048 * 2048,
diff --git a/comfy_api_nodes/util/upload_helpers.py b/comfy_api_nodes/util/upload_helpers.py
index 2794be35c..2190f9639 100644
--- a/comfy_api_nodes/util/upload_helpers.py
+++ b/comfy_api_nodes/util/upload_helpers.py
@@ -88,6 +88,28 @@ async def upload_images_to_comfyapi(
return download_urls
+async def upload_image_to_comfyapi(
+ cls: type[IO.ComfyNode],
+ image: torch.Tensor,
+ *,
+ mime_type: str | None = None,
+ wait_label: str | None = "Uploading",
+ total_pixels: int = 2048 * 2048,
+) -> str:
+ """Uploads a single image to ComfyUI API and returns its download URL."""
+ return (
+ await upload_images_to_comfyapi(
+ cls,
+ image,
+ max_images=1,
+ mime_type=mime_type,
+ wait_label=wait_label,
+ show_batch_index=False,
+ total_pixels=total_pixels,
+ )
+ )[0]
+
+
async def upload_audio_to_comfyapi(
cls: type[IO.ComfyNode],
audio: Input.Audio,