Skip to main content
POST /v2/models/{provider}/{model} mantiene la conexión abierta hasta que el modelo termina. La entrega en cola usa el mismo ID de modelo y el mismo cuerpo de solicitud nativo, pero responde en cuanto Router ha admitido la ejecución. Recibes un request_id de inmediato y recuperas el resultado cuando está listo, desde el mismo proceso o desde otro. La ruta síncrona está limitada a 10 minutos. El plazo predeterminado de Router se puede configurar por implementación. Una llamada síncrona que lo alcanza se corta con 504 / deadline_exceeded, sin importar si el proveedor sigue trabajando. Pon en cola una ejecución si puede superar el plazo o si quien llama no puede mantener una conexión abierta tanto tiempo. Consulta Las llamadas se cortan en el plazo del servidor para saber qué te dice el plazo sobre la facturación y qué no. Usa la cola cuando una generación pueda durar más que la conexión que puedes mantener, cuando una solicitud web tenga que responder de inmediato, cuando envíes en un proceso y recojas en otro, o cuando quieras muchas generaciones en curso a la vez. El orden, la admisión, los reintentos, los tiempos de espera, la facturación y la caducidad se deciden en el servidor. Los SDK solo añaden sondeo y comodidad de uso, nada más.

Elegir un modo de entrega

Los SDK (comfy-sdk y @comfyorg/sdk, 0.3.0 o posterior) exponen la cola como tres métodos junto a run:
  • submit(model, body) envía la solicitud y devuelve un handle de inmediato. El handle incluye status(), get(), cancel() y un iterador de eventos (iter_events() en Python, events() en TypeScript).
  • subscribe(model, body, ...) es enviar, consultar y recoger en una sola llamada, con un callback de progreso.
  • handle(model, request_id) reconstruye un handle en otro proceso a partir de los dos IDs, sin hacer ninguna llamada.
Los dos IDs hacen falta en todas partes porque ambos direccionan la solicitud: la ruta es /v2/models/{provider}/{model}/requests/{request_id}.
Aquí events() no es el job.events() del cliente de Comfy Cloud. Este consulta la ruta de estado y produce observaciones de la cola (estado y posición en la cola) para una solicitud del Router. El de Cloud es un flujo SSE en vivo de una tarea de flujo de trabajo de ComfyUI que transporta progreso, vistas previas y salidas. subscribe() es además una tercera cosa: no es un iterador en absoluto, sino enviar, consultar y recoger combinados en una sola llamada. Consulta events() no es subscribe().

Rutas de la cola

status es uno de IN_QUEUE, IN_PROGRESS o COMPLETED. No existe un estado aparte de fallido o cancelado: una solicitud que no tuvo éxito es COMPLETED y lleva un error_type, así que bifurca según la presencia de ese campo, no según un cuarto valor de estado. Los SDK lo hacen por ti: get() lanza o rechaza con el error tipado de Router en lugar de devolver el fallo como resultado. No hay eventos de progreso, webhooks ni niveles de prioridad: la ruta de estado es la forma de seguir una solicitud. La referencia de la API contiene el contrato completo de cada ruta.

Enviar y recoger una solicitud

Esto encola la misma solicitud que envía el inicio rápido y recoge la imagen. Primero exporta tu clave como COMFY_API_KEY.
Cada página de modelo incluye esta forma para su propio modelo en Poner en cola y recoger después, junto al fragmento síncrono.

Seguir el progreso y recoger en una sola llamada

Cuando sí quieres esperar pero también quieres mostrar el progreso, subscribe combina envío, consulta y recogida en una sola llamada:
El tiempo de espera es un límite del lado del cliente, sin significado en el servidor. Cuando se agota, subscribe hace un intento de cancelación de mejor esfuerzo antes de lanzar. Una cancelación solo surte efecto en una solicitud que aún no ha empezado a ejecutarse: una generación que ya está en curso en el socio se completa y se cobra, la recoja alguien o no. Usa submit cuando la solicitud deba sobrevivir a quien la llama.

Recoger desde otro proceso

Guarda el request_id junto al ID del modelo. Ambos son necesarios para reconstruir un handle, y no se hace ninguna llamada hasta que lo uses.

Consultar el estado o cancelar

status() es una sola consulta y devuelve el estado actual. cancel() pide al servidor que detenga una solicitud que no ha terminado. Es una petición, no una garantía: una ejecución que ya está en marcha en el socio puede completarse de todos modos, y el siguiente status() es lo que es cierto.

Python asíncrono

AsyncComfy replica cada nombre, argumento y orden de argumentos. No existe submit_async, por la misma razón por la que no existe run_async.

Errores que lanzan los SDK

Una solicitud que terminó sin éxito se reporta como COMPLETED con un error_type. get() y subscribe() lo convierten en el error tipado de Router que corresponde al grupo: las clases de comfy_sdk.router_exceptions en Python, y routerErrors.* en TypeScript. El iterador de eventos no lanza en ese caso, porque es una vista del progreso de la cola: una finalización que lleva un error_type se entrega como la última observación, y es get() el que recoge. Un 403 not_enabled en el envío llega como NotEnabled y es terminal, así que los SDK no lo reintentan.

Formas de respuesta de la cola

Enviar, 201. En este punto, status siempre es IN_QUEUE. Las tres URL son absolutas y usan la misma clave que el envío para autenticarse.
request_id también es el valor del encabezado X-Comfy-Request-Id del envío. Mantén el ID del modelo junto a él: la solicitud se identifica por ambos. Estado, 200. La misma forma, con el estado actual. queue_position cuenta las solicitudes que tienes por delante y llega a 0 cuando la ejecución está al frente. Retry-After en esta respuesta es la estimación de Router de cuándo merece la pena volver a consultar. Es una indicación, no un límite, y a una solicitud al final de la cola se le indica que espere más que a una que ya se está ejecutando. Consultar más rápido no permite enterarte antes de nada y consume tu propio margen de límite de velocidad.
Una solicitud que finalizó sin éxito es COMPLETED con un error_type, que lleva la misma categoría general que la lectura del resultado asigna a X-Comfy-Error-Type. El campo está ausente en caso de éxito en lugar de ser null.
Resultado. 200 contiene la salida nativa propia del modelo, byte por byte lo que la ruta síncrona devuelve para el mismo modelo y entrada, bajo el Content-Type propio del proveedor. Mientras la solicitud no ha finalizado, la lectura responde 202 con el cuerpo de estado anterior, de modo que un cliente que solo consulta la URL del resultado analiza un único tipo. Una solicitud fallida vuelve como una respuesta de error con X-Comfy-Error-Type establecido, las mismas categorías que la ruta síncrona. Cancelar. 202 con CANCELLATION_REQUESTED significa que la solicitud se aceptó, no que la ejecución se haya detenido. Una ejecución que ya está en curso en el socio puede completarse de todos modos, y una generación del socio que se completa se cobra tanto si alguien la recoge como si no. Consulta el estado después: una cancelación que surtió efecto aparece como COMPLETED con error_type: cancelled. Una solicitud que caducó antes de poder ejecutarse muestra queue_timeout de la misma manera. Una solicitud que ya había finalizado responde 409 con ALREADY_COMPLETED.

Idempotencia y facturación

  • El mismo cargo que en la ruta síncrona. Se te factura cuando el proveedor factura a Comfy. El tiempo de espera en la cola no se cobra.
  • Una Idempotency-Key por envío. El SDK genera una clave nueva por cada llamada a submit, así que dos envíos deliberados de la misma entrada son dos solicitudes. Un reintento de la misma llamada con la misma clave no encola una segunda ejecución: devuelve el handle original con Idempotent-Replayed: true. Pasa tu propia clave cuando una respuesta perdida podría haberte costado el request_id. Consulta Encabezados.
  • Los resultados caducan. Una solicitud finalizada permanece disponible durante 24 horas después de completarse. Después de eso, las lecturas de estado y resultado responden 410 y el resultado desaparece. Recoge el resultado de inmediato y descarga las URL de recursos que incluya la salida.
  • Las consultas de sondeo también son solicitudes. Las lecturas de estado y resultado cuentan para la tasa de solicitudes por solicitante. Respeta Retry-After en lugar de sondear a un intervalo corto fijo.

Respuestas de error de la cola

Cada respuesta de error incluye X-Comfy-Request-Id. Cítalo cuando contactes con soporte.

Próximos pasos