{"record":{"id":"ac210e7261cbbb2b","repo":"sgl-project/sglang","slug":"hunyuan3d-only-supports-num-outputs-per-prompt-1","errorCode":null,"errorMessage":"Hunyuan3D only supports num_outputs_per_prompt=1.","messagePattern":"Hunyuan3D only supports num_outputs_per_prompt=1\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/hunyuan3d/shape.py","lineNumber":162,"sourceCode":"        self.config = config\n        self.latent_shape = latent_shape\n        self.guidance_embed = guidance_embed\n\n    def _validate_input(self, batch: Req, server_args: ServerArgs) -> None:\n        if batch.image_path is None:\n            raise ValueError(\"Hunyuan3D requires 'image_path' input.\")\n        if isinstance(batch.image_path, list):\n            if len(batch.image_path) != 1:\n                raise ValueError(\"Hunyuan3D only supports a single image input.\")\n            batch.image_path = batch.image_path[0]\n        if not isinstance(batch.image_path, str):\n            raise ValueError(\n                f\"Hunyuan3D expects image_path as str, got {type(batch.image_path)}\"\n            )\n        if not os.path.exists(batch.image_path):\n            raise FileNotFoundError(f\"Image path not found: {batch.image_path}\")\n        if batch.num_outputs_per_prompt != 1:\n            raise ValueError(\"Hunyuan3D only supports num_outputs_per_prompt=1.\")\n\n    def _prepare_latents(self, batch_size, dtype, device, generator, scheduler):\n        from diffusers.utils.torch_utils import randn_tensor\n\n        shape = (batch_size, *self.latent_shape)\n        latents = randn_tensor(shape, generator=generator, device=device, dtype=dtype)\n        return latents * getattr(scheduler, \"init_noise_sigma\", 1.0)\n\n    def component_uses(\n        self, server_args: ServerArgs, stage_name: str | None = None\n    ) -> list[ComponentUse]:\n        return [\n            ComponentUse(\n                self._component_stage_name(stage_name), \"hy3dshape_conditioner\"\n            )\n        ]\n\n    def _find_conditioner_dtype(self, items_fn_name: str) -> torch.dtype | None:","sourceCodeStart":144,"sourceCodeEnd":180,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/hunyuan3d/shape.py#L144-L180","documentation":"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.","triggerScenarios":"Setting num_outputs_per_prompt=2+ (or an OpenAI-style n parameter mapped to it) on a Hunyuan3D request.","commonSituations":"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.","solutions":["Set num_outputs_per_prompt=1 (or omit n so it defaults to 1)","Issue multiple separate requests if you need several shape variants","Ensure gateway/proxy defaults do not inject n>1 for this endpoint"],"exampleFix":"# before\nreq.num_outputs_per_prompt = 4\n\n# after\nreq.num_outputs_per_prompt = 1","handlingStrategy":"validation","validationCode":"if getattr(req, \"num_outputs_per_prompt\", 1) != 1:\n    req.num_outputs_per_prompt = 1  # or reject early","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin n/num_outputs_per_prompt=1 for 3D endpoints in gateway defaults","Reject n>1 early with a clear 400 instead of a mid-pipeline error"],"tags":["hunyuan3d","input-validation","unsupported-parameter"],"backgroundTag":"unsupported-parameter-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}