Cómo empaquetar el flujo de trabajo de ComfyUI en API: tutoriales, solución de problemas y preguntas frecuentes

ComfyUI es excelente para crear flujos de trabajo de dibujo con IA, intercambio de rostros, ampliación, redibujado parcial y generación de video. Pero si solo arrastras nodos en la interfaz web, se parece más a una herramienta creativa; si quieres integrarlo en un sitio web, un bot, tareas de backend o procesos empresariales, necesitas empaquetar el flujo de trabajo como una API.

Este artículo está organizado según “Tutorial + Solución de problemas + Preguntas frecuentes”. El objetivo es convertir un flujo de trabajo que se puede ejecutar manualmente en ComfyUI en una interfaz donde el backend pueda enviar tareas, esperar resultados y descargar imágenes. La atención se centra no en escribir una plataforma compleja, sino en atravesar primero el circuito cerrado más pequeño.

Primero comprenda la idea API de ComfyUI

La esencia de la llamada API de ComfyUI no es “convertir nodos en funciones”, sino enviar todo el flujo de trabajo JSON como un mensaje al backend de ComfyUI. El backend se ejecuta según el gráfico de nodos. Después de generar los resultados, puede obtener el resultado a través del historial o la interfaz de archivos.

El enlace mínimo es:

1. Configure el flujo de trabajo en la interfaz web de ComfyUI.
2. Exporte el flujo de trabajo JSON en formato API.
3. Reemplace el mensaje, la imagen, el tamaño, la semilla y otras entradas en el código de fondo.
4. Llame a /prompt para enviar la tarea.
5. Consulta /history según prompt_id.
6. Lea la imagen de salida o el archivo de video.

Mientras este enlace esté abierto, puede continuar encapsulándolo en su propia API REST, tareas en cola o funciones SaaS.

Prepare un flujo de trabajo estable

No utilice API para un flujo de trabajo complejo con docenas de nodos personalizados desde el principio. Primero elija un flujo de trabajo básico que pueda producir imágenes estables, por ejemplo:

• Cuadro vicenciano.
• Las imágenes dan lugar a imágenes.
• Ampliación de imagen.
• Redibujo parcial.
• Póster de estilo fijo.

Primero confirme algunas cosas en la interfaz de usuario web:

• Se ha descargado el archivo del modelo.
• No faltan nodos personalizados.
• La ruta de la imagen de entrada se puede leer normalmente.
• Una sola ejecución puede generar resultados.
• Los nodos de salida pueden guardar imágenes.

Si no puede ejecutarlo manualmente, las llamadas a la API solo ocultarán el problema más profundamente.

Exportar flujo de trabajo en formato API

En la interfaz ComfyUI, el flujo de trabajo normalmente guardado y el mensaje JSON requerido para las llamadas API no son exactamente los mismos. Por lo general, es necesario habilitar las opciones relacionadas con el desarrollador y luego exportar el formato API.

El JSON que desea obtener se ve así:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "3": {
    "class_type": "KSampler",
    "inputs": {
      "seed": 123456,
      "steps": 20,
      "cfg": 7,
      "sampler_name": "euler",
      "scheduler": "normal"
    }
  },
  "6": {
    "class_type": "CLIPTextEncode",
    "inputs": {
      "text": "a cat sitting on a desk"
    }
  }
}

Cada clave numérica es una ID de nodo. Al realizar cambios en la API, lo que hay que modificar suele ser el inputs de estos nodos.

Encuentre el nodo que necesita ser reemplazado

No se apresure a escribir código después de exportarlo. Abra el JSON y marque qué campos deben ser controlados por la entrada del usuario.

Campos comunes que deben reemplazarse:

Se recomienda mantener una tabla de mapeo en el proyecto, por ejemplo:

1
2
3
4
5
6
7

{
  "positive_prompt_node": "6",
  "negative_prompt_node": "7",
  "sampler_node": "3",
  "latent_node": "5",
  "save_node": "9"
}

De esta manera, cuando ajuste los nodos del flujo de trabajo más adelante, solo necesitará cambiar la asignación, sin tener que buscar el ID del nodo en todas partes del código comercial.

Enviar mensaje en Python

Aquí hay un ejemplo mínimo: lea el JSON del flujo de trabajo, reemplace las palabras del mensaje y envíelo a ComfyUI local.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

import json
import urllib.request
import uuid

COMFYUI_URL = "http://127.0.0.1:8188"


def queue_prompt(prompt):
    payload = {
        "prompt": prompt,
        "client_id": str(uuid.uuid4())
    }
    data = json.dumps(payload).encode("utf-8")
    req = urllib.request.Request(
        f"{COMFYUI_URL}/prompt",
        data=data,
        headers={"Content-Type": "application/json"}
    )
    with urllib.request.urlopen(req) as resp:
        return json.loads(resp.read().decode("utf-8"))


with open("workflow_api.json", "r", encoding="utf-8") as f:
    workflow = json.load(f)

workflow["6"]["inputs"]["text"] = "a clean product photo of a white sneaker"
workflow["7"]["inputs"]["text"] = "blurry, low quality, text watermark"
workflow["3"]["inputs"]["seed"] = 123456789

result = queue_prompt(workflow)
print(result)

Normalmente, se devolverá prompt_id en caso de éxito. Luego confiará en él para consultar los resultados.

Consultar resultados de la tarea

Después de enviar la tarea, ComfyUI no le devolverá la imagen directamente de inmediato. Necesidad de consultar el historial:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

import json
import time
import urllib.request


def get_history(prompt_id):
    with urllib.request.urlopen(f"{COMFYUI_URL}/history/{prompt_id}") as resp:
        return json.loads(resp.read().decode("utf-8"))


prompt_id = result["prompt_id"]

for _ in range(60):
    history = get_history(prompt_id)
    if prompt_id in history:
        print(json.dumps(history[prompt_id], indent=2, ensure_ascii=False))
        break
    time.sleep(1)
else:
    raise TimeoutError("ComfyUI task timed out")

El historial contendrá información del archivo y del nodo de salida. Debe encontrar filename, subfolder, type y otros campos, y luego llamar a /view para descargar.

Descargar imagen de salida

Un método de descarga común es:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

from urllib.parse import urlencode


def download_image(filename, subfolder="", folder_type="output"):
    params = urlencode({
        "filename": filename,
        "subfolder": subfolder,
        "type": folder_type
    })
    url = f"{COMFYUI_URL}/view?{params}"
    with urllib.request.urlopen(url) as resp:
        return resp.read()

Después de obtener los bytes, puede escribirlos en un archivo local, cargarlos en el almacenamiento de objetos o devolverlos a la API de su empresa.

Encapsulado en su propia API REST

En proyectos reales, no se recomienda permitir que el front-end llame directamente a ComfyUI. Una estructura más estable es:

1
2
3
4
5
6
7
8
9

Frontend de usuario
  ↓
Tu API de negocio
  ↓
Cola de tareas
  ↓
ComfyUI API
  ↓
Almacenamiento de objetos / directorio local de salida

La API empresarial es responsable de:

• Verificar parámetros de usuario.
• Controlar tamaño, pasos, modelo y estilo.
• Limitar la concurrencia y la frecuencia.
• Gestionar el estado de las tareas.
• Devuelve la URL de la imagen final.

ComfyUI solo es responsable de la generación de ejecución y no está expuesto directamente a la red pública.

Error común: no se puede conectar a ComfyUI

Rendimiento típico:

1
2

connection refused
failed to connect to 127.0.0.1:8188

Consultar orden:

1. Si ComfyUI se está ejecutando.
2. Si el puerto es 8188.
3. Si el código backend y ComfyUI están en la misma máquina.
4. ¿localhost en Docker, WSL o servidor remoto apunta correctamente?
5. Si el firewall bloquea el puerto.

Si el backend se ejecuta en un contenedor, 127.0.0.1 se refiere al contenedor en sí, no al host. Debe cambiarlo a la dirección del host o usar el nombre del servicio de red Docker.

Error común: el formato del mensaje es incorrecto

Rendimiento típico:

1
2

invalid prompt
prompt outputs failed validation

Razones comunes:

• Se utilizó JSON de flujo de trabajo simple en lugar del formato API JSON.
• El ID del nodo está escrito incorrectamente.
• Se ha eliminado una entrada requerida.
• El tipo de entrada no coincide; por ejemplo, los números se escriben como cadenas.
• Falta el nodo personalizado, lo que hace que no se reconozca el tipo_clase.

Método de solución de problemas:

• Enviar primero con el JSON original exportado sin ningún reemplazo.
• Se puede ejecutar el JSON original y luego los campos se reemplazan uno por uno.
• Compare los ID de nodos y los campos en la interfaz de usuario web.
• Consulte la consola ComfyUI para obtener informes de errores detallados.

No reemplace una docena de campos a la vez. Cambiar sólo una variable a la vez es lo más fácil de localizar.

Errores comunes: modelo o nodo personalizado no encontrado

Rendimiento típico:

1
2
3

CheckpointLoaderSimple: ckpt_name not found
Cannot import custom node
class_type not found

El motivo suele ser que el entorno del servidor API no es coherente con el entorno donde exportó el flujo de trabajo.

Consulte estos directorios:

• models/checkpoints
• models/loras
• models/vae
• models/controlnet
• custom_nodes

Si se puede ejecutar en la máquina de desarrollo pero no en la máquina de implementación, verifique primero el nombre del archivo del modelo, la versión del nodo personalizado y los paquetes dependientes.

Error común: no se pudo leer la imagen de entrada

Los problemas de ruta de la imagen se encuentran a menudo al crear imágenes, cambiar caras y volver a dibujar imágenes parcialmente.

Tenga en cuenta algunos puntos:

• LoadImage normalmente lee archivos en el directorio de entrada de ComfyUI.
• Es posible que no esté disponible la transferencia directa a cualquier ruta en la máquina local.
• Es posible que tengas que cargar imágenes en ComfyUI antes de llamar a la API.
• Los formatos de ruta de Windows y Linux son diferentes.

Un enfoque más estable es cargar la imagen del usuario en el directorio de entrada de ComfyUI o usar la interfaz de carga y luego escribir el nombre del archivo devuelto en el nodo LoadImage.

Error común: las tareas siempre están en cola

Si /prompt devuelve prompt_id, pero el historial no tiene resultados, puede ser:

• La GPU está realizando otras tareas.
• Un nodo está atascado.
• La carga del modelo es muy lenta.
• La memoria de vídeo insuficiente provoca cambios repetidos.
• El backend de ComfyUI ha informado de un error pero el final comercial no lo ha leído.

Se recomienda hacer:

• Ver el registro de la consola ComfyUI.
• Agregar tiempo de espera a las encuestas del lado empresarial.
• Limitar el número de tareas simultáneas.
• Establezca tiempos de espera más largos pero claros para imágenes grandes, vídeos y restauraciones HD.
• Devolver un error legible en caso de falla en lugar de hacer esperar al usuario.

Error común: memoria de vídeo insuficiente

Rendimiento típico:

1
2

CUDA out of memory
Allocation failed

Método de procesamiento:

• Reducir la resolución.
• Reducir el tamaño del lote.
• Reducir pasos.
• Cambiar a un modelo más pequeño.
• Desactive las correcciones innecesarias de ControlNet, LoRA o HD.
• Configurar diferentes colas para diferentes flujos de trabajo.

Después de convertirse en API, es aún más importante controlar la entrada del usuario. No permita que los usuarios carguen 4096 x 4096, 100 pasos o múltiples pilas LoRA a voluntad; de lo contrario, el servicio se llenará fácilmente.

Preguntas frecuentes: archivo de resultados no encontrado

Si hay un nombre de archivo en el historial pero se produce un error 404 al descargarlo, las razones más comunes son:

• Los parámetros filename, subfolder, type se transmiten incorrectamente.
• El nodo de salida no es SaveImage.
• El archivo se guarda en un directorio temporal.
• La tarea falló y no hay resultados reales en el historial.
• Durante la implementación de múltiples instancias, se solicitó otra ComfyUI.

Al solucionar problemas, imprima primero los resultados del historial y no deletree la URL desde la memoria.

Protección antes de conectarse

Después de incluir ComfyUI en una API, no se conecte desnudo. Como mínimo considere:

• Autenticación.
• Límites de frecuencia.
• Límites de concurrencia.
• Introduzca límites de tamaño.
• límite de longitud del aviso.
• Deshabilitar la selección por parte del usuario de rutas de modelos arbitrarias.
• Limpieza de archivos de salida.
• Reintentos fallidos y tiempos de espera.
• Persistencia del estado de la tarea.

ComfyUI es muy adecuado como motor de generación, pero la capa empresarial necesita proporcionar permisos, colas, auditorías y control de recursos por sí misma.

Preguntas frecuentes

¿ComfyUI viene con su propia API?

tener. Las interfaces más utilizadas son /prompt, /history/{prompt_id} y /view. Los proyectos reales generalmente envuelven una capa de API empresarial en el exterior para evitar exponer directamente ComfyUI.

¿Por qué no se puede llamar directamente al flujo de trabajo exportado?

La exportación puede ser un flujo de trabajo normal, no un formato API; También es posible que falten modelos, nodos personalizados o que algunas rutas de entrada solo sean válidas en el entorno actual de la interfaz de usuario web. Pruebe primero con la API JSON original y luego reemplace gradualmente los parámetros.

¿Puede la interfaz llamar a ComfyUI directamente?

No recomendado. Las llamadas directas desde el front-end expondrán la dirección del servicio y dificultarán la autenticación, la limitación de corriente y el control de parámetros. Lo que es más estable es que el front-end llama al back-end y el back-end llama a ComfyUI.

¿Cómo manejar la concurrencia multiusuario?

No permita que todas las solicitudes vayan directamente a ComfyUI. Se recomienda agregar una cola de tareas, limitar la cantidad de concurrencias y realizar encuestas según el estado de la tarea. Los flujos de trabajo de alto costo se pueden poner en cola por separado.

¿Dónde deberían almacenarse las imágenes de salida?

El directorio de salida de ComfyUI puede existir durante el desarrollo. Después de conectarse, se recomienda cargarlo en el almacenamiento de objetos o en el servicio de archivos comerciales, luego regresar a la URL estable y limpiar los archivos temporales locales con regularidad.

¿Qué debo hacer si cambia el ID del nodo?

Si vuelve a editar el flujo de trabajo, el ID del nodo puede cambiar. Se recomienda mantener un mapa de parámetros y ejecutar una prueba API mínima después de cada actualización del flujo de trabajo.

¿Se pueden convertir varios flujos de trabajo en una sola API?

Sí, pero no permita que los usuarios pasen directamente JSON de flujo de trabajo arbitrario. Un enfoque más seguro es mantener una lista blanca de plantillas en el backend, y los usuarios solo pueden seleccionar plantillas y parámetros limitados.

¿Cuál es la diferencia entre el flujo de trabajo de vídeo y el flujo de trabajo de imágenes?

Los flujos de trabajo de vídeo suelen tardar más, ejercen más presión sobre la memoria de vídeo y producen archivos de salida más grandes, lo que requiere colas, tiempos de espera y gestión de archivos más estrictos. Primero conecte el enlace de la imagen y luego expanda el video.

resumen

La esencia de empaquetar el flujo de trabajo de ComfyUI en una API es convertir el gráfico de nodo estable en un mensaje JSON con parámetros reemplazables, luego enviar la tarea a través de /prompt, consultar los resultados a través de /history y obtener el archivo a través de /view. La verdadera dificultad no está en realizar solicitudes, sino en la estabilidad del flujo de trabajo, los límites de los parámetros, la simultaneidad de las colas, la gestión de archivos y el manejo de errores.

Se recomienda comenzar con el flujo de trabajo del diagrama Vincent más simple y seguir los cuatro pasos de exportación, envío, sondeo y descarga. Una vez que el ciclo cerrado mínimo se estabilice, se agregarán imágenes cargadas, plantillas de estilo, colas de usuarios y protección a nivel de producción.