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
        # Seconds to wait before re-sending the SAME Idempotency-Key. Router
        # sends it on the two answers that mean "the work exists, ask again" -
        # a deadline_exceeded 504 over a generation still running, and the 409
        # that refuses a key whose original call is still in flight.
        raw_retry_after = response.headers.get("Retry-After")
        self.retry_after = int(raw_retry_after) if (raw_retry_after or "").isdigit() else None
        # 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}/v2/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;
  /** Seconds to wait before re-sending the SAME `Idempotency-Key`. Router
   * sends it on the two answers that mean "the work exists, ask again" — a
   * `deadline_exceeded` `504` over a generation still running, and the `409`
   * that refuses a key whose original call is still in flight. */
  readonly retryAfter: number | null;
  /** 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;
    const retryAfter = Number(response.headers.get("Retry-After"));
    this.retryAfter = Number.isInteger(retryAfter) && retryAfter > 0 ? retryAfter : null;
    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}/v2/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

import json
import uuid

# Persist BEFORE the request, so a crash between here and the response still
# leaves a key — and the exact request it belongs to — you can retry with.
request = {
    "model": MODEL,
    "arguments": {"prompt": "a red teapot on a windowsill, morning light"},
    "idempotency_key": str(uuid.uuid4()),
}
with open("pending-call.json", "w") as f:
    json.dump(request, f)

result = run(request["model"], request["arguments"], idempotency_key=request["idempotency_key"])

import time


def collect(model: str, arguments: dict, idempotency_key: str, attempts: int = 30) -> dict:
    """Re-send one call under its ORIGINAL key until Router has an answer."""
    for _ in range(attempts):
        try:
            response = httpx.post(
                f"{BASE_URL}/v2/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)
            if response.headers.get("Idempotent-Replayed") == "true":
                print("collected the original generation; not charged again")
            return response.json()
        except RouterError as exc:
            # deadline_exceeded means the generation is still running;
            # concurrency_limit_exceeded on a 409 means another attempt is
            # already collecting it. Both say "ask again", and both name when.
            # Anything without a Retry-After is Router's final answer on this
            # key - including the 409 that says the key is spent for good.
            if exc.retry_after is None:
                raise
            time.sleep(exc.retry_after)
        except httpx.HTTPError:
            # The flaky connection that lost the response in the first place can
            # just as easily lose a collect attempt. The key is unchanged, so
            # asking again is still safe.
            time.sleep(2)
    raise TimeoutError(f"gave up collecting {idempotency_key} after {attempts} attempts")


# Mint the key FIRST, so it survives the call that fails.
arguments = {"prompt": "a red teapot on a windowsill, morning light"}
key = str(uuid.uuid4())
try:
    result = run(MODEL, arguments, idempotency_key=key)
except RouterError as exc:
    if exc.error_type != "deadline_exceeded":
        raise
    result = collect(MODEL, arguments, idempotency_key=key)
except httpx.HTTPError:
    # A dropped connection never reached a response, so there is no bucket to
    # branch on - but the key is still good and the generation may still be
    # running, which is exactly what collect() is for.
    result = collect(MODEL, arguments, idempotency_key=key)
print("image:", result["result"]["sample"])

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

/** Re-send one call under its ORIGINAL key until Router has an answer. */
async function collect<T>(
  model: string,
  args: Record<string, unknown>,
  idempotencyKey: string,
  attempts = 30,
): Promise<T> {
  for (let i = 0; i < attempts; i++) {
    let response: Response;
    try {
      response = await fetch(`${BASE_URL}/v2/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),
      });
    } catch (exc) {
      // The flaky connection that lost the response in the first place can just
      // as easily lose a collect attempt. The key is unchanged, so asking again
      // is still safe - but a caller's own abort is theirs and stops the loop.
      if (!(exc instanceof TypeError || exc instanceof DOMException)) throw exc;
      await sleep(2000);
      continue;
    }
    const body = await parseBody(response);
    if (response.ok) {
      if (response.headers.get("Idempotent-Replayed") === "true") {
        console.log("collected the original generation; not charged again");
      }
      return body as T;
    }
    // `deadline_exceeded` means the generation is still running;
    // `concurrency_limit_exceeded` on a 409 means another attempt is already
    // collecting it. Both say "ask again", and both name when. Anything with no
    // `Retry-After` is Router's final answer on this key.
    const error = new RouterError(response, body);
    if (error.retryAfter === null) throw error;
    await sleep(error.retryAfter * 1000);
  }
  throw new Error(`gave up collecting ${idempotencyKey} after ${String(attempts)} attempts`);
}

// Mint the key FIRST, so it survives the call that fails.
const args = { prompt: "a red teapot on a windowsill, morning light" };
const key = crypto.randomUUID();
let image: { result: { sample: string } };
try {
  image = await run<{ result: { sample: string } }>(MODEL, args, key);
} catch (exc) {
  const lostTheResponse =
    exc instanceof RouterError
      ? exc.errorType === "deadline_exceeded"
      // A dropped connection or a local abort never reached a response, so it
      // arrives as a plain fetch failure with no bucket to branch on - but the
      // key is still good and the generation may still be running, which is
      // what collect() is for. Anything else is a bug in this program rather
      // than a lost result, so it propagates.
      : exc instanceof TypeError || exc instanceof DOMException;
  if (!lostTheResponse) throw exc;
  image = await collect<{ result: { sample: string } }>(MODEL, args, key);
}
console.log("image:", image.result.sample);

key = f"order-{order_id}-render"   # deterministic, stored with the order

curl -H "X-API-Key: $COMFY_API_KEY" \
  "https://api.comfy.org/v2/models?limit=50"

{
  "data": [
    { "id": "bfl/flux-2-pro", "provider": "bfl", "model": "flux-2-pro", "billing": { "charges_on_policy_rejection": "no" } }
  ],
  "has_more": true,
  "next_cursor": "q7Fm2xTn9pLd4RsV",
  "limit": 50
}

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