sgl-project/sglang · error · ValueError

Hunyuan3D only supports num_outputs_per_prompt=1.

Error message

Hunyuan3D only supports num_outputs_per_prompt=1.

What it means

The Hunyuan3D shape generation stage only produces one output per prompt; its denoising and mesh extraction path is hard-coded to batch size 1 in outputs. _validate_input rejects any request with batch.num_outputs_per_prompt != 1.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/hunyuan3d/shape.py:162

        self.config = config
        self.latent_shape = latent_shape
        self.guidance_embed = guidance_embed

    def _validate_input(self, batch: Req, server_args: ServerArgs) -> None:
        if batch.image_path is None:
            raise ValueError("Hunyuan3D requires 'image_path' input.")
        if isinstance(batch.image_path, list):
            if len(batch.image_path) != 1:
                raise ValueError("Hunyuan3D only supports a single image input.")
            batch.image_path = batch.image_path[0]
        if not isinstance(batch.image_path, str):
            raise ValueError(
                f"Hunyuan3D expects image_path as str, got {type(batch.image_path)}"
            )
        if not os.path.exists(batch.image_path):
            raise FileNotFoundError(f"Image path not found: {batch.image_path}")
        if batch.num_outputs_per_prompt != 1:
            raise ValueError("Hunyuan3D only supports num_outputs_per_prompt=1.")

    def _prepare_latents(self, batch_size, dtype, device, generator, scheduler):
        from diffusers.utils.torch_utils import randn_tensor

        shape = (batch_size, *self.latent_shape)
        latents = randn_tensor(shape, generator=generator, device=device, dtype=dtype)
        return latents * getattr(scheduler, "init_noise_sigma", 1.0)

    def component_uses(
        self, server_args: ServerArgs, stage_name: str | None = None
    ) -> list[ComponentUse]:
        return [
            ComponentUse(
                self._component_stage_name(stage_name), "hy3dshape_conditioner"
            )
        ]

    def _find_conditioner_dtype(self, items_fn_name: str) -> torch.dtype | None:

View on GitHub (pinned to 0132848349)

Solutions

1. Set num_outputs_per_prompt=1 (or omit n so it defaults to 1)
2. Issue multiple separate requests if you need several shape variants
3. Ensure gateway/proxy defaults do not inject n>1 for this endpoint

Example fix

# before
req.num_outputs_per_prompt = 4

# after
req.num_outputs_per_prompt = 1

if getattr(req, "num_outputs_per_prompt", 1) != 1:
    req.num_outputs_per_prompt = 1  # or reject early

When it happens

Trigger: Setting num_outputs_per_prompt=2+ (or an OpenAI-style n parameter mapped to it) on a Hunyuan3D request.

Common situations: Reusing a text-generation request template with n>1; a generic gateway defaulting n to 4; attempting best-of-N image-to-3D generation in one call.

Related errors

• Hunyuan3D requires 'image_path' input.
• Hunyuan3D only supports a single image input.
• Hunyuan3D expects image_path as str, got {type(batch.image_p
• unsupported input for causal Conv3D cat/pad CUDA
• unsupported input for usp_merge_heads CUDA

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/ac210e7261cbbb2b. Report an issue: GitHub.