---
name: comfyui_text_to_3d_oneshot
kind: pipeline
lang: py
domain: pipelines
version: "1.0.0"
purity: impure
signature: "def comfyui_text_to_3d_oneshot(prompt: str, *, server: str = \"127.0.0.1:8188\", ckpt_name: str = \"IMG_v1-5-pruned-emaonly-fp16.safetensors\", negative: str = \"\", textured: bool = False, variant: str = \"mini\", dest: str | None = None, image_wait_timeout: float = 300.0, wait_timeout: float = 600.0, **gen) -> dict"
description: "Pipeline prompt de texto -> malla 3D GLB en una sola llamada. Genera una imagen desde texto con Stable Diffusion (txt2img), la sube al input/ del servidor y reconstruye una malla 3D desde ella (malla nativa Hunyuan3D-2 o, con textured=True, malla texturizada PBR multi-vista). Compone comfyui_build_txt2img_workflow + submit + wait + fetch_output_image + comfyui_build_image_to_3d_workflow (o comfyui_build_textured_3d_multiview_workflow) + submit + wait + comfyui_fetch_output_mesh. Reutiliza el helper de upload del pipeline hermano comfyui_image_to_3d_oneshot. Promocion de secuencia texto->imagen->3D (issue 0087). Impuro: HTTP + disco."
tags: [comfyui, img-to-3d, pipelines, ml, stable-diffusion, hunyuan3d]
uses_functions:
  - comfyui_build_txt2img_workflow_py_ml
  - comfyui_build_image_to_3d_workflow_py_ml
  - comfyui_build_textured_3d_multiview_workflow_py_ml
  - comfyui_submit_workflow_py_ml
  - comfyui_wait_result_py_ml
  - comfyui_fetch_output_image_py_ml
  - comfyui_fetch_output_mesh_py_ml
  - comfyui_image_to_3d_oneshot_py_pipelines
uses_types: []
returns: []
returns_optional: false
error_type: error_go_core
imports: []
params:
  - name: prompt
    desc: "Prompt positivo de texto para la generacion de la imagen base (txt2img)."
  - name: server
    desc: "host:port del servidor ComfyUI (sin esquema). keyword-only."
  - name: ckpt_name
    desc: "Checkpoint Stable Diffusion para el txt2img (default SD1.5 IMG_v1-5-pruned-emaonly-fp16). keyword-only."
  - name: negative
    desc: "Prompt negativo del txt2img. keyword-only."
  - name: textured
    desc: "True = malla texturizada PBR multi-vista (Hunyuan3DWrapper); False = malla nativa Hunyuan3D-2 segun variant. keyword-only."
  - name: variant
    desc: "mini (default), standard o mv; checkpoint Hunyuan3D-2 del paso 3D no texturizado (ignorado si textured=True). keyword-only."
  - name: dest
    desc: "Ruta destino de la malla (None = cwd; dir = dentro; archivo = ahi). La imagen intermedia se guarda en una carpeta derivada de dest. keyword-only."
  - name: image_wait_timeout
    desc: "Segundos maximos esperando la generacion de la imagen. keyword-only."
  - name: wait_timeout
    desc: "Segundos maximos esperando la reconstruccion 3D. keyword-only."
  - name: gen
    desc: "Parametros del txt2img reenviados a comfyui_build_txt2img_workflow (steps, cfg, width, height, seed, sampler_name, scheduler, filename_prefix); las demas claves se ignoran."
output: "dict {ok, image_path, mesh_path, prompt_ids, error}. image_path = ruta local del PNG generado; mesh_path = ruta local de la malla GLB; prompt_ids = [id_txt2img, id_3d]. Si falla, ok=False y error indica el paso (submit/wait/fetch txt2img o 3D)."
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/pipelines/comfyui_text_to_3d_oneshot.py"
---

## Ejemplo

```python
import sys, os
sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions"))
from pipelines.comfyui_text_to_3d_oneshot import comfyui_text_to_3d_oneshot

# Texto -> malla 3D nativa (SD1.5 + Hunyuan3D-2 mini), una sola llamada.
res = comfyui_text_to_3d_oneshot(
    "a cute robot toy, full body, centered, plain background, sharp focus",
    dest="/tmp/comfy_text_to_3d",
    steps=20,
    seed=42,
)
# res == {"ok": True, "image_path": "/tmp/.../comfy_00001_.png",
#         "mesh_path": "/tmp/comfy_text_to_3d/3d_mesh_00001_.glb",
#         "prompt_ids": ["<id_txt2img>", "<id_3d>"], "error": ""}

# Malla texturizada PBR multi-vista (requiere el wrapper Hunyuan3DWrapper instalado):
res2 = comfyui_text_to_3d_oneshot("a stylized ceramic mug", textured=True, dest="/tmp/comfy_text_to_3d")
```

Lánzalo con el python del venv (import de arriba o heredoc). `./fn run` directo no
aplica porque la firma usa `*` (keyword-only) + `**gen`, no soportado por el
generador de runner de `fn run`.

## Cuando usarla

Cuando quieras una malla 3D a partir de SOLO una descripción de texto, sin pasar
por generar la imagen a mano. Promueve a una llamada la secuencia que antes eran
dos pasos encadenados (texto->imagen con `comfyui_build_txt2img_workflow`, luego
imagen->3D con `comfyui_build_image_to_3d_workflow`). Si ya tienes la imagen en
disco, usa directamente el pipeline hermano `comfyui_image_to_3d_oneshot`.

## Gotchas

- Impuro: dispara DOS trabajos de GPU encadenados (txt2img + reconstrucción 3D).
  En 8 GB usa SD1.5 (`ckpt_name` default) + `variant="mini"`; SDXL o `textured=True`
  necesitan más VRAM/tiempo y los modelos correspondientes ya instalados.
- El checkpoint SD (`ckpt_name`) y el de Hunyuan3D (`variant`) deben estar
  presentes en el servidor; este pipeline NO los descarga. Valida con
  `comfyui_validate_workflow` o `comfyui_object_info` si dudas.
- La imagen generada queda en el `output/` del servidor; el pipeline la baja a
  disco y la re-sube al `input/` (POST /upload/image) porque el nodo `LoadImage`
  del paso 3D lee del `input/`. Eso implica un round-trip imagen completo.
- `textured=True` requiere el custom node Hunyuan3DWrapper (kijai); sin él, el
  submit del paso 3D falla con HTTP 400 y `ok=False` con el error del nodo.
- `**gen` solo reenvía claves de txt2img (`steps, cfg, width, height, seed,
  sampler_name, scheduler, filename_prefix`); cualquier otra clave se ignora en
  silencio (el paso 3D usa sus defaults).
- `prompt_ids` se va rellenando incrementalmente: si falla el paso 3D, contiene
  igualmente el id del txt2img que sí se encoló (útil para depurar).
