---
name: comfyui_txt2img_oneshot
kind: pipeline
lang: py
domain: pipelines
version: "1.0.0"
purity: impure
signature: "def comfyui_txt2img_oneshot(prompt: str, *, ckpt: str = \"dreamshaper_8.safetensors\", negative: str = \"\", server: str = \"127.0.0.1:8188\", dest: str | None = None, wait_timeout: float = 300.0, **gen) -> dict"
description: "Pipeline prompt de texto -> PNG en disco en una sola llamada. Construye el workflow txt2img de Stable Diffusion, lo encola en ComfyUI, espera y descarga la imagen. Compone comfyui_build_txt2img_workflow + comfyui_submit_workflow + comfyui_wait_result + comfyui_fetch_output_image. Promocion de secuencia (issue 0087). Impuro: HTTP + disco."
tags: [comfyui, pipelines, txt2img, stable-diffusion, launcher]
uses_functions: [comfyui_build_txt2img_workflow_py_ml, comfyui_submit_workflow_py_ml, comfyui_wait_result_py_ml, comfyui_fetch_output_image_py_ml]
uses_types: []
returns: []
returns_optional: false
error_type: error_py_core
imports: [comfyui_build_txt2img_workflow_py_ml, comfyui_submit_workflow_py_ml, comfyui_wait_result_py_ml, comfyui_fetch_output_image_py_ml]
params:
  - name: prompt
    desc: "Prompt positivo (lo que se quiere ver en la imagen)."
  - name: ckpt
    desc: "Checkpoint Stable Diffusion tal como lo ve el servidor (CheckpointLoaderSimple). Por defecto 'dreamshaper_8.safetensors'. keyword-only."
  - name: negative
    desc: "Prompt negativo. Por defecto ''. keyword-only."
  - name: server
    desc: "host:port del servidor ComfyUI (sin esquema). keyword-only."
  - name: dest
    desc: "Directorio local donde guardar el PNG (None = cwd). keyword-only."
  - name: wait_timeout
    desc: "Segundos maximos esperando a que el server termine. keyword-only."
  - name: gen
    desc: "Parametros de generacion pasados a comfyui_build_txt2img_workflow (steps, cfg, width, height, seed, sampler_name, scheduler, filename_prefix). keyword-only (**gen)."
output: "dict {ok, image_path, prompt_id, error}. image_path = ruta local del PNG descargado; prompt_id = id del trabajo en ComfyUI. Si falla, ok=False y error explica en que paso."
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/pipelines/comfyui_txt2img_oneshot.py"
---

## Ejemplo

```bash
# Genera una imagen desde texto y la baja a /tmp.
./fn run comfyui_txt2img_oneshot "a red apple on a wooden table, sharp focus"
```

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

res = comfyui_txt2img_oneshot(
    "a red apple on a wooden table, sharp focus",
    negative="blurry, low quality",
    dest="/tmp/comfy_txt2img",
    steps=20,
    seed=42,
)
# res["ok"] == True
# res["image_path"]  # ruta local del PNG
print(res["image_path"], res["prompt_id"])
```

## Cuando usarla

Cuando solo quieres "texto → imagen" sin montar el grafo a mano ni encadenar
submit/wait/fetch tú mismo. Es la forma de una sola llamada del flujo txt2img más
común. Para añadir detalle de caras encadénala con `comfyui_build_facedetailer_workflow`,
o para nitidez en alta con `comfyui_build_hires_fix_workflow` (esos son builders;
este pipeline ejecuta el camino básico end-to-end).

## Gotchas

- Impuro: requiere el **servidor ComfyUI vivo** en `server` (default
  `127.0.0.1:8188`). Si está caído, falla en el paso submit con el error de conexión.
- `ckpt` debe existir en el servidor (CheckpointLoaderSimple). Default
  `dreamshaper_8.safetensors`; cámbialo si usas SDXL u otro.
- `dest` es un **directorio** (se crea si no existe), no un nombre de archivo: el
  PNG conserva el nombre que le da ComfyUI (`<filename_prefix>_NNNNN_.png`).
- `wait_timeout` por defecto 300 s. Subir resolución/steps puede requerir más; si
  el server está cargando el modelo por primera vez, la primera generación tarda más.
- Devuelve el **primer** PNG de los outputs. Para batches de varias imágenes usa
  `comfyui_batch_generate` o itera con distintos `seed`.
- No reintenta: si el server está ocupado con otra cola, encola igualmente y espera
  su turno hasta `wait_timeout`.

## Capability growth log

- v1.0.0 (2026-06-24) — pipeline inicial. Compone build_txt2img + submit + wait +
  fetch_output_image (issue 0087, roadmap del report 0092).