Referencia de la API de Comfy Router

Rutas canónicas de Comfy Router, direccionadas por ID de modelo. URL base: https://api.comfy.org Todos los endpoints siguientes requieren autenticación. Envía X-API-Key: <api-key> o Authorization: Bearer <jwt>. Las claves de API de Comfy también se pueden enviar como tokens Bearer. X-API-Key tiene prioridad cuando se proporcionan ambos encabezados de credenciales. Consulta encabezados de autenticación para ver la distinción entre clave y JWT y la guía de inicio rápido para conocer los requisitos de acceso.

​

Endpoints

​

GET /v2/models

Enumera los modelos que Comfy Router puede ejecutar. Consulta los IDs de modelo disponibles y los datos de facturación. Usa next_cursor mientras has_more sea verdadero. Parámetros Respuestas

​

GET /v2/models/{provider}/{model}

Lee la entrada del catálogo de un modelo socio por su ID de modelo canónico. Lee los detalles de un modelo sin listar el catálogo completo. Parámetros Respuestas

​

POST /v2/models/{provider}/{model}

Ejecuta un modelo socio de forma sincrónica mediante el ID canónico del modelo. Ejecuta un modelo y recibe su resultado finalizado en la misma respuesta. Parámetros Cuerpo de la solicitud application/json — RouterModelInput (requerido) La entrada JSON nativa del modelo socio. Sin model_provider, la solicitud ejecuta el despacho nativo en el proveedor predeterminado del modelo y este cuerpo es el propio esquema nativo del modelo, reenviado sin cambios (strict_mode no tiene sentido ahí y no cambia nada). Con model_provider seleccionando un proveedor alternativo y strict_mode=false (el valor predeterminado), el cuerpo se traduce al esquema real de ese proveedor antes de enviarse: cualquier campo nativo que no se pueda expresar con exactitud se descarta y se divulga mediante el encabezado X-Comfy-Router-Dropped-Params de la respuesta, nunca en silencio. Con model_provider seleccionando un proveedor alternativo y strict_mode=true no se ejecuta ninguna traducción: el cuerpo ya debe ser el esquema real propio de ese proveedor alternativo, no el nativo de este modelo (consulta strict_mode), y se reenvía sin cambios. Los propios campos del cuerpo también seleccionan qué operación ejecuta Router en un modelo que admite más de una: para un modelo de imagen editable, incluir una imagen de entrada lo cambia de la operación texto a imagen a la operación imagen a imagen (edición), que puede facturarse con su propia tarifa; para un modelo de video Seedance, content[].role selecciona la operación (una imagen de primer fotograma selecciona imagen a video, y una imagen o un clip de referencia selecciona referencia a video). En el despacho nativo, la facturación de Seedance sigue los tipos de medio en content, no los roles: una solicitud con cualquier entrada de video se factura como video a video; si no, una con cualquier imagen se factura como imagen a video; si no, texto a video, salvo que un render final de un elemento draft_task se factura como la operación del Draft que renderiza; algunos modelos cobran la misma tarifa para texto a video e imagen a video. Con model_provider seleccionando un proveedor alternativo, cada operación condicionada puede facturarse con la tarifa propia de ese proveedor. Respuestas

​

POST /v2/models/{provider}/{model}/estimate

Calcula el precio de una llamada a un modelo antes de ejecutarla, sin ejecutarla. Devuelve una estimación previa, en dólares estadounidenses, de lo que costará ejecutar este cuerpo en este modelo, con precios tomados de la misma tarifa con la que se factura la ejecución. Es una estimación, no el cargo final: lo que pagas es el cargo liquidado en los registros de uso y facturación de tu espacio de trabajo. El cuerpo se valida primero contra el esquema de entrada del modelo, tal como lo valida una ejecución predeterminada (sin strict_mode, sin reject_unknown_fields), así que un cuerpo que no cumple el esquema del modelo produce aquí el mismo 422 que en la ejecución; no se despacha nada a un proveedor y no se cobra nada. La respuesta no es un bloqueo de precio: se calcula con las tarifas vigentes en pricing_as_of, y una ejecución se cobra con las tarifas vigentes cuando se tarifica. Mientras la función se está desplegando, la ruta responde 403 con error_type: not_enabled. Parámetros Cuerpo de la solicitud application/json — RouterModelInput (requerido) La entrada JSON nativa del modelo del socio, idéntica al cuerpo que la ruta síncrona acepta para este modelo. Se valida contra el esquema de entrada propio del modelo tal como lo valida una ejecución predeterminada (esta ruta no acepta strict_mode ni reject_unknown_fields), y sus propios campos (el número de salidas, la operación que selecciona una imagen de entrada) deciden qué se tarifica. Respuestas

​

GET /v2/models/{provider}/{model}/openapi.json

Lee los esquemas de entrada y salida de un modelo socio como documento OpenAPI. Lee los esquemas de entrada y salida de un modelo como un documento OpenAPI independiente. Parámetros Respuestas

​

POST /v2/models/{provider}/{model}/requests

Envía una ejecución de modelo asociado a la cola y regresa de inmediato. El modo de entrega en cola de Comfy Router. El cuerpo de la solicitud es la misma entrada JSON nativa del socio que POST /v2/models/{provider}/{model} acepta para este modelo: una sola forma de cuerpo, un esquema por modelo, dos modos de entrega; pero esta ruta no mantiene la conexión para el resultado. Admite la ejecución, responde 201 con un identificador y quien llama recoge el resultado más tarde mediante las tres lecturas que aparecen a continuación. Parámetros Cuerpo de la solicitud application/json — RouterModelInput (requerido) La entrada JSON nativa del modelo asociado, idéntica al cuerpo que la ruta síncrona acepta para este modelo, y que selecciona la operación y se factura de la misma manera: los campos del propio cuerpo eligen qué operación ejecuta Router en un modelo que admite más de una (una imagen de entrada cambia un modelo de imagen editable a imagen a imagen, lo que puede facturarse con su propia tarifa; una imagen de primer fotograma de Seedance selecciona imagen a video, y una imagen o clip de referencia selecciona referencia a video). En el despacho nativo, una solicitud de Seedance se factura según los tipos de medio en content, no según los roles: cualquier entrada de video se factura como video a video; de lo contrario, cualquier imagen se factura como imagen a video; de lo contrario, texto a video; salvo que un render final a partir de un elemento draft_task se factura como la operación del Draft que renderiza, con algunos modelos cobrando la misma tarifa para texto a video e imagen a video; y con model_provider seleccionando un proveedor alternativo, cada operación condicionada puede facturarse con la tarifa propia de ese proveedor. El mismo contrato de selección de proveedor se aplica en el despacho: sin model_provider, o con model_provider y strict_mode=false (el valor predeterminado), el cuerpo es el documento nativo del modelo y se valida contra el esquema de entrada propio del modelo antes de admitir la ejecución, por lo que un cuerpo que el modelo rechazaría es un 422 aquí en vez de una solicitud en cola que falla minutos después; además, un cuerpo no estricto de proveedor alternativo se traduce al esquema real de ese proveedor en el despacho. Con strict_mode=true, el cuerpo ya debe ser el esquema propio del proveedor alternativo y se reenvía sin cambios: la validación del esquema nativo se omite, exactamente como en la ruta síncrona (consulta model_provider y strict_mode). Respuestas

​

GET /v2/models/{provider}/{model}/requests/{request_id}

Recupera el resultado de una solicitud enviada. El endpoint de recogida. Sobre una solicitud que ha finalizado correctamente, devuelve la salida nativa del modelo del socio, byte por byte lo que la ruta síncrona entrega en su 200 para el mismo modelo y la misma entrada, de modo que los dos modos de entrega producen una sola forma de resultado y un cliente puede pasar de uno a otro sin necesidad de un segundo analizador. Parámetros Respuestas

​

PUT /v2/models/{provider}/{model}/requests/{request_id}/cancel

Solicitar la cancelación de una solicitud enviada. Le pide a Comfy que detenga una solicitud que no ha finalizado. Es una solicitud, no una garantía, y el 202 lo dice exactamente: CANCELLATION_REQUESTED significa que la petición fue aceptada, no que la ejecución se haya detenido. Una ejecución que ya está en curso en un socio puede completarse de todos modos, y una generación del socio que se completa se cobra, se haya recogido o no, así que quien llama y necesita saber qué pasó realmente consulta el endpoint de estado después, donde una cancelación que surtió efecto aparece como COMPLETED con un error_type, igual que cualquier otro resultado terminal. Parámetros Respuestas

​

GET /v2/models/{provider}/{model}/requests/{request_id}/status

Lee el estado en la cola de una solicitud enviada. El endpoint de sondeo. Responde con el estado actual de la solicitud y nunca con el resultado, así que un cliente puede seguir una generación larga sin transferir su salida en cada sondeo: el resultado se recoge una sola vez, desde la lectura de abajo, cuando este indica COMPLETED. Parámetros Respuestas Las descripciones aquí son breves. Usa Uso de la API de Comfy Router para la selección de modelos, la validación, los reintentos y la facturación, y Encabezados para el comportamiento de los encabezados.

​

Categorías de error

Categoría de error del Router legible por máquina, que también se envía en el encabezado X-Comfy-Error-Type.

​

Categorías a nivel de solicitud

Se generan para una solicitud que el Router aceptó y luego no pudo completar.

​

Categorías a nivel de transporte

Las genera el propio Router, antes de la llamada al modelo o en torno a ella.

​

Encabezados de respuesta

​

Estimaciones de costos previas a la ejecución

POST /v2/models/{provider}/{model}/estimate tarifica un cuerpo sin ejecutarlo, y un envío en cola (POST /v2/models/{provider}/{model}/requests) devuelve el mismo RouterCostEstimate que estimate en su 201. Ambos se calculan con la tarjeta de tarifas contra la que Comfy factura la ejecución. Cada cifra que devuelve cualquiera de los dos es una estimación, no el cargo final: el cargo liquidado en los registros de uso y facturación de tu espacio de trabajo es el definitivo. Comfy no factura una ejecución con tu propia clave de proveedor (ver abajo). Mientras la estimación se está implementando, la ruta responde 403 con error_type: not_enabled y la respuesta del envío omite estimate. El catálogo sigue sin mostrar precios. Lee source antes de cualquier cantidad. Que falte una cifra nunca significa que sea gratis. El reason de una estimación unknown es uno de los siguientes:

• not_quotable: Router no puede tarificar esta llamada antes de que se ejecute, porque se factura según una cantidad que el proveedor reporta de vuelta y que el cuerpo no acota, o porque no se puede tarificar el cuerpo tal como se envió. Trata cualquier reason no reconocido como not_quotable.
• unpriced_model: la tarjeta de tarifas no tarifica esta solicitud.
• byok (solo envío en cola): la ejecución usa tu propia clave de proveedor, por lo que Comfy no cobra nada por ella.
• pricing_unavailable (solo envío en cola): no se pudo leer la tarjeta de tarifas cuando se admitió la solicitud. El envío se acepta igualmente y la ejecución se cobra como de costumbre.

Los modelos para los que Router aún no puede calcular un precio antes de una ejecución se enumeran en modelos sin una estimación previa a la ejecución. Un modelo que no aparezca allí puede responder igualmente unknown para un cuerpo concreto, así que lee source en cada estimación. Cuándo la estimación falla de forma segura:

• Cuando una cifra necesita la tarjeta de tarifas y la tarjeta no está cargada o está desactualizada, /estimate responde 503 en lugar de adivinar. Router nunca rechaza el envío en cola por su estimación; en su lugar, este lleva source: unknown con reason: pricing_unavailable. Router responde a una llamada que no se puede tarificar antes de ejecutarse en absoluto (not_quotable), o a un envío en cola con tu propia clave de proveedor (byok), sin leer la tarjeta, así que ese 200 no dice nada sobre si la tarjeta está actualizada.
• /estimate valida el cuerpo con el esquema de entrada propio del modelo igual que lo hace una ejecución predeterminada, así que un cuerpo que no cumple el esquema del modelo recibe el mismo 422, con la misma forma de detail[], que respondería la ejecución. No se calcula ningún precio ni se despacha nada.
• Una repetición idempotente de un envío en cola (Idempotent-Replayed: true) omite estimate, porque la cotización original no se almacena.

Límites de la estimación. Una cifra de 200 no garantiza que la ejecución se acepte ni que se cobre exactamente eso:

• /estimate no acepta strict_mode ni reject_unknown_fields, así que solo comprueba el contrato nativo del modelo: un cuerpo que una ejecución con strict_mode=true acepta en el esquema propio del proveedor alternativo puede recibir aquí un 422, y aquí se calcula el precio de un campo de nivel superior no declarado que una ejecución con reject_unknown_fields=true rechazaría.
• pricing_as_of indica cuándo se obtuvo la tarjeta de tarifas (o, cuando no se leyó ninguna, cuándo se respondió la estimación). No es un bloqueo de precio: la ejecución se cobra con las tarifas vigentes cuando se tarifica.
• /estimate cotiza el tramo que indica model_provider, o el proveedor nativo. No acepta el parámetro fallback_provider ni strict_mode. Una ejecución síncrona cuyo reintento de respaldo recae en otro proveedor se cobra con la tarifa de ese proveedor, que la estimación no cotizó; X-Comfy-Router-Fallback-Provider en la respuesta de la ejecución indica que ocurrió. Un envío en cola no tiene respaldo, así que su estimate cotiza el tramo que se ejecuta.
• /estimate y el estimate de un envío en cola pueden calcular el precio de documentos ligeramente distintos para el mismo cuerpo en un tramo de model_provider, o para un cuerpo que se ejecuta en una operación hermana. El estimate del envío se calcula sobre el documento que envía la ejecución.
• /estimate siempre cotiza el cargo de la plataforma. Comfy no factura una ejecución con tu propia clave de proveedor, pero /estimate no lo detecta y aun así devuelve una cifra; solo un envío en cola responde reason: byok.
• Los dólares se calculan a partir de centavos sin redondear, con hasta 8 decimales, y una amount cobrable inferior a un centavo nunca se muestra como 0. credits es round(amount × 211, 2), la misma conversión que X-Comfy-Credits-Used aplica a un cargo, así que credits puede redondearse a 0 para un precio muy pequeño distinto de cero; presupuesta con amount o amount_cents, no con credits, cuando eso importe. Ese encabezado sigue siendo la cifra a posteriori de una ejecución; los saldos están en la plataforma de Comfy.

​

Recursos del resultado

Un modelo puede devolver URL de recursos, bytes en línea o ambos. Los proveedores siguientes copian los recursos seleccionados en el almacenamiento de Comfy y sustituyen sus URL. Este comportamiento depende del modelo; no hay ningún encabezado de solicitud que lo seleccione. Estos tiempos de vida empiezan cuando se firma la URL, no cuando la abres. Las URL en caché o de una llamada repetida pueden tener menos tiempo restante; repetir la llamada no las renueva. Descarga el recurso cuanto antes. Solo se copian los recursos indicados en cada fila: las imágenes byteplus/seedream-* y byteplus/seededit-* no están cubiertas por la fila de video de BytePlus. La copia la realiza únicamente el proveedor nativo del modelo. Una ejecución atendida por un proveedor alternativo (model_provider que nombre uno, o una ejecución nativa cuyo reintento de respaldo haya recaído en uno, indicado por X-Comfy-Router-Fallback-Provider) devuelve las URL propias de ese proveedor, que siguen la caducidad del proveedor y no se copian. Los valores default, comfy y comfyui de model_provider no nombran ningún proveedor alternativo, por lo que esas ejecuciones son nativas y se copian como se describe arriba, igual que una ejecución con model_provider cuyo reintento de respaldo haya vuelto a recaer en el proveedor nativo. Veo (veo/*) tiene una ruta de almacenamiento aparte. En response.videos[], lee el miembro que esté presente: bytesBase64Encoded contiene el clip en línea, mientras que gcsUri contiene un enlace HTTPS firmado por Comfy cuando el entorno está configurado para que el proveedor escriba directamente en el almacenamiento de Comfy. Ese enlace es válido durante 24 horas desde la respuesta. En este último caso el recurso se escribe directamente en lugar de copiarse, por lo que Veo no figura en la tabla de realojamiento. Otros modelos devuelven referencias a recursos del proveedor o bytes en línea. Las URL del proveedor siguen la caducidad del proveedor, que puede ser mucho más corta que los tiempos de vida anteriores y no está especificada por el contrato del Router. La copia se hace con el mejor esfuerzo en cada recurso. Si una copia falla, esa entrada conserva su referencia del proveedor; la respuesta puede contener tanto URL de Comfy como del proveedor, sin un campo explícito de estado de copia por recurso. La generación se completa igualmente y se cobra. No deduzcas el tiempo de vida de todas las URL a partir de un recurso realojado con éxito. Que un resultado esté alojado en Comfy también determina si más tarde aún es posible repetir una llamada completada desde su registro de Idempotency-Key; el parámetro Idempotency-Key de arriba indica qué recibe un reintento cuando no es posible.

​

Esquema de entrada y salida por modelo

Lee los campos de cada modelo desde GET /v2/models/{provider}/{model}/openapi.json. Esa llamada requiere una clave API. El mismo documento, para cada modelo con un esquema definido explícitamente, también se publica en este sitio sin clave, en /router-schemas/{provider}/{model}.json. Esa copia es una instantánea tomada en la última actualización de la documentación, así que el endpoint es la fuente autoritativa cuando hay diferencias. El requestBody de la operación describe la validación de la entrada; su respuesta 200 describe la forma de la salida y el tipo de medio cuando este está definido explícitamente. Cuando x-comfy-input-schema-authored es false, Router acepta cualquier objeto JSON sin prevalidación específica del modelo. Los requisitos del proveedor siguen aplicando. Los esquemas de salida describen resultados; Router no valida contra ellos las cargas útiles que devuelve el proveedor. Una salida sin esquema definido explícitamente puede usar */* en lugar de application/json; revisa el tipo de contenido de la respuesta antes de decodificarla.

​

Esquemas

​

RouterChargesOnPolicyRejection

Indica si un rechazo por política de contenido se cobra en este modelo. Trata un valor desconocido como potencialmente cobrado. Tipo: string

​

RouterCostEstimate

Una estimación previa de cuánto costará esta llamada, en dólares estadounidenses, calculada antes del despacho a partir de la misma tabla de tarifas con la que se factura la ejecución. No es el cargo final: el cargo que pagas es el liquidado en los registros de uso y facturación de tu espacio de trabajo. X-Comfy-Credits-Used, que se informa después de la ejecución, es una cifra redondeada calculada a posteriori, no un recibo. source indica cuánto puedes confiar en el número: exact incluye amount; estimated incluye min_amount y max_amount y ningún amount; unknown no incluye ninguno de los dos y sí un reason. Nunca interpretes un amount ausente como gratis. No es un bloqueo de precio: consulta pricing_as_of. Campos

​

RouterErrorResponse

Cuerpo de error para fallos de autenticación, acceso, búsqueda de modelos, cuota y transporte del proveedor. Campos

​

RouterErrorType

Categoría de error del Router legible por máquina, que también se envía en el encabezado X-Comfy-Error-Type. Tipo: string

​

RouterModelBilling

Comportamiento de facturación que debes revisar antes de invocar un modelo. No incluye precios ni uso. Campos

​

RouterModelDetail

Detalle por modelo de un modelo de Comfy Router: todo lo que el listado del catálogo reporta para ese modelo, más los campos por modelo que solo incluye la ruta de modelo único. Combina RouterModelListEntry y RouterModelDetailFields. Tipo: object

​

RouterModelDetailFields

Campos opcionales que devuelve el endpoint de detalles del modelo. Campos

​

RouterModelId

El ID del modelo que se usa en POST /v2/models/{provider}/{model}. Tipo: string. ID del modelo, p. ej. anthropic/claude-opus-4-6. Hasta 193 caracteres.

​

RouterModelInput

El objeto de entrada del modelo. Consulta el documento OpenAPI del modelo seleccionado para ver los campos y la validación. Tipo: object

​

RouterModelInputSchemaDocument

Un documento OpenAPI independiente para la entrada y la salida de un modelo. Tipo: object

​

RouterModelListEntry

El ID de un modelo y sus datos de facturación. Campos

​

RouterModelListResponse

Una página del catálogo de modelos del Router. Campos

​

RouterModelOutput

El objeto de resultado del modelo. Consulta el esquema de salida del modelo seleccionado para conocer su forma exacta. Tipo: object

​

RouterModelSegment

La parte del modelo de un ID de modelo {provider}/{model}. Tipo: string. Slug alfanumérico, p. ej. claude-opus-4-6, de hasta 128 caracteres

​

RouterPageCursor

Un cursor de catálogo opaco. Devuélvelo sin cambios como cursor. Tipo: string. Cursor opaco devuelto como next_cursor, de 1 a 512 caracteres.

​

RouterProviderSegment

La parte del proveedor de un ID de modelo {provider}/{model}. Tipo: string: slug alfanumérico, p. ej. anthropic, hasta 64 caracteres

​

RouterQueueCancelResponse

La respuesta a una solicitud de cancelación en los dos estados que describen una solicitud que esta ruta resolvió: el 202 y el 409. Una sola forma de cuerpo para ambos en lugar de un envelope de éxito más un envelope de error, porque ambos son la misma afirmación (lo que encontró la cancelación) y un cliente que tiene que analizar un tipo distinto por código de estado no gana nada con la separación. Campos

​

RouterQueueCancelStatus

Qué encontró una solicitud de cancelación, para los dos resultados que describen una solicitud que esta ruta realmente resolvió. Ambos se reflejan en el estado HTTP, así que un cliente puede ramificar según cualquiera de los dos. Tipo: string

​

RouterQueuePosition

Cuántas solicitudes hay por delante de esta en la cola, en el instante en que se compuso la respuesta. Cero significa que esta solicitud está al frente. Tipo: integer — Al menos 0

​

RouterQueueRequestId

Identificador de una solicitud de Router en cola: el identificador que usa quien llama para consultar, cancelar y recoger un resultado. Tipo: string — pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$, uuid, hasta 36 caracteres

​

RouterQueueStatus

El estado de una solicitud Router en cola. Tiene exactamente tres valores y, a diferencia de RouterErrorType, este es un enum cerrado, porque los dos esquemas están cerrados en direcciones opuestas a propósito. RouterErrorType clasifica los fallos y se espera que su conjunto crezca, por lo que un cliente generado que rechazara de forma estricta un bucket no reconocido fallaría más justo cuando algo ya hubiera salido mal. Este es un ciclo de vida, y un ciclo de vida al que se le añade más tarde un cuarto estado es un cambio incompatible para todos los bucles de sondeo escritos contra él, se declare como enum o no, así que se declara como uno y la restricción se indica donde un cliente pueda verla. Tipo: string

​

RouterQueueStatusFields

La mitad de RouterQueueStatusResponse que no es el bloque de URL: la identidad de una solicitud en cola, su estado actual y, cuando ese estado es terminal y la ejecución no tuvo éxito, el grupo genérico que indica por qué. Campos

​

RouterQueueStatusResponse

Estado actual de una solicitud en cola, compuesto con las mismas tres URL que devolvió el envío. Compone RouterQueueUrls, RouterQueueStatusFields. Tipo: object

​

RouterQueueSubmitFields

La mitad de RouterQueueSubmitResponse que no es el bloque de URL: la identidad de la nueva solicitud y su estado en el instante en que fue admitida. Campos

​

RouterQueueSubmitResponse

El identificador que se devuelve cuando una ejecución se admite en la cola: la identidad y el estado de la solicitud, compuesto con las tres URL que direccionan el resto de su ciclo de vida. Está compuesto por RouterQueueUrls y RouterQueueSubmitFields. Tipo: object

​

RouterQueueUrls

Las tres URL que abarcan el resto del ciclo de vida de una solicitud en cola y que se devuelven en cada respuesta que incluye un handle activo, para que el cliente nunca tenga que componer por su cuenta una URL de cola. Campos

​

RouterValidationErrorContext

Detalles proporcionados por el proveedor sobre la regla de validación que falló. Tipo: object

​

RouterValidationErrorDetail

Un fallo de validación a nivel de campo. Campos

​

RouterValidationErrorInput

El valor de entrada rechazado, cuando el proveedor lo incluye.

​

RouterValidationErrorResponse

El cuerpo del error de validación 422. Lee X-Comfy-Error-Type para conocer su categoría. Campos