Comfy Router quickstart

export COMFY_API_KEY="comfyui-..."

pip install httpx

import os
import uuid

import httpx

BASE_URL = os.environ.get("COMFY_ROUTER_BASE_URL", "https://api.comfy.org")
MODEL = "bfl/flux-2-pro"

# Give the client headroom ABOVE Router's own server deadline (10 minutes by
# default) so a call that reaches the server bound comes back as a typed 504
# with a request id rather than as an opaque client abort. The deadline bounds
# how long Router holds the connection, not whether the call is billed: if the
# provider completed the generation, it is billed either way.
READ_TIMEOUT_SECONDS = 660.0


class RouterError(Exception):
    """A Comfy Router failure, typed by its X-Comfy-Error-Type bucket."""

    def __init__(self, response: httpx.Response) -> None:
        self.error_type = response.headers.get("X-Comfy-Error-Type", "internal_error")
        self.request_id = response.headers.get("X-Comfy-Request-Id")
        self.status_code = response.status_code
        # Parse defensively: an error can arrive as an HTML 502 from a load
        # balancer, a plain-text 429, an empty body or a truncated JSON one. The
        # status, the bucket and the request id above are the parts worth
        # keeping, so a body that will not parse must not replace this exception
        # with a JSONDecodeError and lose them.
        body = None
        if response.headers.get("content-type", "").startswith("application/json"):
            try:
                body = response.json()
            except ValueError:
                body = None
        detail = body.get("detail") if isinstance(body, dict) else None
        # A 422 carries a detail[] array - one entry per rejected field, each
        # keeping its own `loc`, `msg` and `type`. Every other bucket carries a
        # plain `detail` string.
        self.errors = detail if isinstance(detail, list) else []
        self.detail = detail if isinstance(detail, str) else f"HTTP {response.status_code}"
        super().__init__(self.detail)


def run(model: str, arguments: dict, idempotency_key: str) -> dict:
    # Idempotency-Key makes a retry safe on a PAID call: Router replays the
    # original response for 24h instead of dispatching (and billing) the
    # provider a second time. Reuse the SAME key when retrying one logical
    # call; generate a new one for a new call.
    response = httpx.post(
        f"{BASE_URL}/v1/models/{model}",
        headers={
            "X-API-Key": os.environ["COMFY_API_KEY"],
            "Idempotency-Key": idempotency_key,
        },
        json=arguments,
        timeout=httpx.Timeout(READ_TIMEOUT_SECONDS, connect=10.0),
    )
    if response.is_error:
        raise RouterError(response)
    return response.json()


result = run(
    MODEL,
    {"prompt": "a red teapot on a windowsill, morning light"},
    idempotency_key=str(uuid.uuid4()),
)
# Router forwards each provider's native output unchanged, so this path is
# BFL's, not a Router envelope. Reading a different model means reading its own
# output shape.
print("image:", result["result"]["sample"])

# The first failure most callers hit: a field the model's input schema requires
# is missing, so Router rejects the request BEFORE any provider call - which is
# why a 422 is never billed.
try:
    run(MODEL, {"width": 1024}, idempotency_key=str(uuid.uuid4()))
except RouterError as exc:
    print(f"{exc.error_type} (HTTP {exc.status_code}), request id {exc.request_id}")
    for entry in exc.errors:
        print("  ", ".".join(str(p) for p in entry["loc"]), "->", entry["msg"])

image: https://.../out.jpeg
invalid_input (HTTP 422), request id 6f1c...
   body.prompt -> Field required

npm install --save-dev tsx

const BASE_URL = process.env.COMFY_ROUTER_BASE_URL ?? "https://api.comfy.org";
const MODEL = "bfl/flux-2-pro";

// Headroom ABOVE Router's own server deadline (10 minutes by default), so a
// call that reaches the server bound returns a typed 504 with a request id
// rather than aborting locally at the same moment. The deadline bounds how
// long Router holds the connection, not whether the call is billed: if the
// provider completed the generation, it is billed either way.
const CLIENT_TIMEOUT_MS = 660_000;

interface ValidationEntry {
  loc: (string | number)[];
  msg: string;
  type: string;
}

/** A Comfy Router failure, typed by its `X-Comfy-Error-Type` bucket. */
class RouterError extends Error {
  readonly errorType: string;
  readonly requestId: string | null;
  readonly status: number;
  /** A 422 carries a `detail[]` array — one entry per rejected field, each
   * keeping its own `loc`, `msg` and `type`. Every other bucket carries a
   * plain `detail` string. */
  readonly errors: ValidationEntry[];

  constructor(response: Response, body: unknown) {
    const detail =
      typeof body === "object" && body !== null
        ? (body as { detail?: unknown }).detail
        : undefined;
    super(typeof detail === "string" ? detail : `HTTP ${String(response.status)}`);
    this.name = "RouterError";
    this.errorType = response.headers.get("X-Comfy-Error-Type") ?? "internal_error";
    this.requestId = response.headers.get("X-Comfy-Request-Id");
    this.status = response.status;
    this.errors = Array.isArray(detail) ? (detail as ValidationEntry[]) : [];
  }
}

/** Read a body without letting a non-JSON error page mask the real failure. */
async function parseBody(response: Response): Promise<unknown> {
  const text = await response.text();
  try {
    return JSON.parse(text) as unknown;
  } catch {
    return undefined;
  }
}

async function run<T>(
  model: string,
  args: Record<string, unknown>,
  idempotencyKey: string,
): Promise<T> {
  // Idempotency-Key makes a retry safe on a PAID call: Router replays the
  // original response for 24h instead of dispatching (and billing) the provider
  // a second time. Reuse the SAME key when retrying one logical call.
  const response = await fetch(`${BASE_URL}/v1/models/${model}`, {
    method: "POST",
    headers: {
      "X-API-Key": process.env.COMFY_API_KEY ?? "",
      "Idempotency-Key": idempotencyKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(args),
    signal: AbortSignal.timeout(CLIENT_TIMEOUT_MS),
  });
  // Branch on `ok` FIRST: an HTML 502, a plain-text 429 or an empty body must
  // still surface the status, the bucket and the request id.
  const body = await parseBody(response);
  if (!response.ok) throw new RouterError(response, body);
  return body as T;
}

const result = await run<{ result: { sample: string } }>(
  MODEL,
  { prompt: "a red teapot on a windowsill, morning light" },
  crypto.randomUUID(),
);
// Router forwards each provider's native output unchanged, so this path is
// BFL's, not a Router envelope. Reading a different model means reading its own
// output shape.
console.log("image:", result.result.sample);

// The first failure most callers hit: a field the model's input schema requires
// is missing, so Router rejects the request BEFORE any provider call - which is
// why a 422 is never billed.
try {
  await run(MODEL, { width: 1024 }, crypto.randomUUID());
} catch (exc) {
  if (!(exc instanceof RouterError)) throw exc;
  console.log(`${exc.errorType} (HTTP ${String(exc.status)}), request id ${String(exc.requestId)}`);
  for (const entry of exc.errors) console.log("  ", entry.loc.join("."), "->", entry.msg);
}

image: https://.../out.jpeg
invalid_input (HTTP 422), request id 6f1c...
   body.prompt -> Field required

curl -H "X-API-Key: $COMFY_API_KEY" \
  https://api.comfy.org/v1/models/bfl/flux-2-pro/openapi.json