@fudrouter/fsrouter 0.6.61 → 0.6.63

package/open-sse/handlers/imageProviders/blackForestLabs.js

@@ -0,0 +1,63 @@
+/**
+ * Black Forest Labs FLUX API adapter.
+ *
+ * Providers: black-forest-labs
+ * Auth: x-key header (not Authorization Bearer) — uses apiKey or accessToken
+ * Format: JSON body → async polling via task result URL
+ * Polling: Yes — polls until status == "Ready"
+ *
+ * Supported request params:
+ * @param {string}  prompt                  - (required) Image description
+ * @param {string}  [model]                 - Model ID (e.g. "flux-pro-1.1", "flux-kontext-pro")
+ * @param {string}  [size]                  - Dimensions → parsed to width/height integers
+ * @param {number}  [seed]                  - Fixed seed
+ * @param {number}  [guidance]              - Guidance scale
+ * @param {number}  [num_steps]             - Diffusion steps
+ * @param {string}  [output_format="jpeg"]  - "jpeg"|"png"|"webp"
+ * @param {string}  [image_url]             - Reference image (Kontext edit models only)
+ *
+ * Response normalize: result.sample → { created, data: [{ url }] }.
+ */
+// Black Forest Labs (FLUX) — async submit + polling_url
+import { sleep, nowSec, POLL_INTERVAL_MS, POLL_TIMEOUT_MS } from "./_base.js";
+
+const BASE_URL = "https://api.bfl.ai/v1";
+
+export default {
+  async: true,
+  buildUrl: (model) => `${BASE_URL}/${model}`,
+  buildHeaders: (creds) => {
+    const key = creds?.apiKey || creds?.accessToken;
+    return { "Content-Type": "application/json", "x-key": key };
+  },
+  buildBody: (_model, body) => {
+    const req = { prompt: body.prompt };
+    if (body.size) {
+      const [w, h] = body.size.split("x").map(Number);
+      if (w) req.width = w;
+      if (h) req.height = h;
+    }
+    if (body.image) req.image_prompt = body.image;
+    return req;
+  },
+  async parseResponse(response, { headers }) {
+    const data = await response.json();
+    const pollingUrl = data.polling_url;
+    if (!pollingUrl) throw new Error("BFL: no polling_url returned");
+    const deadline = Date.now() + POLL_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      await sleep(POLL_INTERVAL_MS);
+      const r = await fetch(pollingUrl, { headers: { "x-key": headers["x-key"], "Accept": "application/json" } });
+      if (!r.ok) throw new Error(`BFL status ${r.status}`);
+      const s = await r.json();
+      if (s.status === "Ready") return s;
+      if (s.status === "Error" || s.status === "Failed") throw new Error(s.error || "BFL generation failed");
+    }
+    throw new Error("BFL polling timeout");
+  },
+  normalize: (responseBody) => {
+    const sample = responseBody.result?.sample;
+    if (sample) return { created: nowSec(), data: [{ url: sample }] };
+    return { created: nowSec(), data: [] };
+  },
+};

package/open-sse/handlers/imageProviders/cloudflareAi.js

@@ -0,0 +1,207 @@
+/**
+ * Cloudflare AI Workers image generation adapter.
+ *
+ * Providers: cloudflare-ai
+ * Auth: Bearer token via Authorization header
+ *       Requires providerSpecificData.accountId for endpoint construction.
+ * Format: JSON body OR FormData (model-dependent) → sync base64 response
+ * Polling: None (synchronous)
+ *
+ * Endpoint: https://api.cloudflare.com/client/v4/accounts/{accountId}/ai/run/{model}
+ *
+ * Supported request params:
+ * @param {string}  prompt               - (required) Image description
+ * @param {string}  [size]               - Parsed to width/height integers (e.g. "1024x1024")
+ * @param {number}  [seed]               - Fixed seed
+ * @param {number}  [num_steps]          - Diffusion steps
+ * @param {number}  [guidance]           - CFG guidance scale
+ * @param {string}  [negative_prompt]    - Elements to exclude
+ * @param {string}  [image_url]          - Reference image for img2img (SD v1.5-img2img)
+ * @param {string}  [mask_image]         - Mask image for inpainting (SD v1.5-inpainting)
+ *
+ * Body format:
+ * - FLUX.2 Dev and similar multipart-only models → FormData
+ * - All other models → JSON { prompt, width, height, ... }
+ *
+ * Response normalize:
+ * - string → { data: [{ b64_json: result }] }
+ * - { image: b64 } → { data: [{ b64_json: image }] }
+ */
+import { nowSec, urlToBase64 } from "./_base.js";
+
+const BASE_URL = "https://api.cloudflare.com/client/v4/accounts";
+
+const MULTIPART_MODELS = new Set([
+  "@cf/black-forest-labs/flux-2-dev",
+  "@cf/black-forest-labs/flux-2-klein-4b",
+  "@cf/black-forest-labs/flux-2-klein-9b",
+]);
+
+const OPTIONAL_FIELDS = [
+  "negative_prompt",
+  "guidance",
+  "seed",
+  "num_steps",
+  "steps",
+  "strength",
+];
+
+function sizeToDimensions(size) {
+  const match = /^(\d+)x(\d+)$/.exec(String(size || ""));
+  if (!match) return {};
+  return {
+    width: Number(match[1]),
+    height: Number(match[2]),
+  };
+}
+
+function getDimensions(body) {
+  return {
+    ...sizeToDimensions(body.size),
+    ...(Number.isFinite(Number(body.width)) ? { width: Number(body.width) } : {}),
+    ...(Number.isFinite(Number(body.height)) ? { height: Number(body.height) } : {}),
+  };
+}
+
+async function resolveImageInput(value) {
+  if (Array.isArray(value)) {
+    return { bytes: value, b64: Buffer.from(value).toString("base64") };
+  }
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (/^https?:\/\//i.test(trimmed)) {
+    const b64 = await urlToBase64(trimmed);
+    return { bytes: base64ToBytes(b64), b64 };
+  }
+  const match = /^data:image\/[^;]+;base64,(.+)$/i.exec(trimmed);
+  const b64 = match ? match[1] : trimmed;
+  return { bytes: base64ToBytes(b64), b64 };
+}
+
+function base64ToBytes(value) {
+  try {
+    return Array.from(Buffer.from(value, "base64"));
+  } catch {
+    return value;
+  }
+}
+
+function addOptionalFields(target, body, append) {
+  for (const key of OPTIONAL_FIELDS) {
+    const value = body[key];
+    if (value === undefined || value === null || value === "") continue;
+    append(target, key, value);
+  }
+}
+
+async function buildJsonBody(body) {
+  const req = { prompt: body.prompt, ...getDimensions(body) };
+
+  addOptionalFields(req, body, (target, key, value) => {
+    target[key] = value;
+  });
+
+  const imageData = await resolveImageInput(body.image);
+  if (imageData) {
+    req.image_b64 = imageData.b64;
+    req.image = imageData.bytes;
+  }
+
+  const maskData = await resolveImageInput(body.mask_image || body.maskImage || body.mask);
+  if (maskData) {
+    req.mask_b64 = maskData.b64;
+    req.mask = maskData.bytes;
+    req.mask_image = maskData.bytes;
+  }
+
+  return req;
+}
+
+function buildMultipartBody(body) {
+  const form = new FormData();
+  form.append("prompt", body.prompt);
+
+  const dimensions = getDimensions(body);
+  for (const [key, value] of Object.entries(dimensions)) {
+    form.append(key, String(value));
+  }
+
+  addOptionalFields(form, body, (target, key, value) => {
+    target.append(key, String(value));
+  });
+
+  return form;
+}
+
+function imageItemFromString(value) {
+  if (typeof value !== "string" || !value) return null;
+  if (/^data:image\/[^;]+;base64,/i.test(value)) {
+    return { b64_json: value.replace(/^data:image\/[^;]+;base64,/i, "") };
+  }
+  if (/^https?:\/\//i.test(value)) return { url: value };
+  return { b64_json: value };
+}
+
+function normalizeCloudflareResponse(responseBody) {
+  if (responseBody?.created && Array.isArray(responseBody?.data)) return responseBody;
+
+  const result = responseBody?.result ?? responseBody;
+  const queuedResponse = Array.isArray(result?.responses)
+    ? result.responses.find((item) => item?.success !== false)?.result
+    : null;
+  if (queuedResponse) return normalizeCloudflareResponse(queuedResponse);
+
+  const image =
+    (typeof result === "string" ? result : null) ||
+    result?.image ||
+    result?.data?.[0]?.b64_json ||
+    result?.data?.[0]?.url;
+
+  const item = imageItemFromString(image);
+  return {
+    created: nowSec(),
+    data: item ? [item] : [],
+  };
+}
+
+export default {
+  buildUrl: (model, creds) => {
+    const accountId = creds?.providerSpecificData?.accountId;
+    if (!accountId) throw new Error("cloudflare-ai requires accountId in providerSpecificData");
+    return `${BASE_URL}/${accountId}/ai/run/${model}`;
+  },
+
+  buildHeaders: (creds, requestBody) => {
+    const headers = {};
+    const isMultipart = typeof FormData !== "undefined" && requestBody instanceof FormData;
+    if (!isMultipart) {
+      headers["Content-Type"] = "application/json";
+    }
+    const key = creds?.apiKey || creds?.accessToken;
+    if (key) headers.Authorization = `Bearer ${key}`;
+    return headers;
+  },
+
+  buildBody: async (model, body) => (
+    MULTIPART_MODELS.has(model)
+      ? buildMultipartBody(body)
+      : await buildJsonBody(body)
+  ),
+
+  async parseResponse(response) {
+    const contentType = (response.headers.get("Content-Type") || "").toLowerCase();
+    if (contentType.startsWith("image/")) {
+      const buf = await response.arrayBuffer();
+      return {
+        created: nowSec(),
+        data: [{ b64_json: Buffer.from(buf).toString("base64") }],
+      };
+    }
+
+    const json = await response.json();
+    return normalizeCloudflareResponse(json);
+  },
+
+  normalize: normalizeCloudflareResponse,
+};

package/open-sse/handlers/imageProviders/codex.js

@@ -0,0 +1,217 @@
+/**
+ * OpenAI Codex (Responses API) image generation adapter.
+ *
+ * Providers: codex (ChatGPT Plus/Pro accounts via OAuth session)
+ * Auth: Bearer session token + chatgpt-account-id header
+ * Format: JSON body → SSE stream (parses image_generation_call delta events)
+ * Polling: None (streaming SSE)
+ *
+ * Supported request params:
+ * @param {string}  prompt                        - (required) Image description
+ * @param {string}  [model="gpt-4o"]              - Model ID ("-image" suffix is stripped automatically)
+ * @param {string}  [size="1024x1024"]            - Dimensions: "1024x1024"|"1792x1024"|"1024x1792"|"1536x1024"|"1024x1536"
+ * @param {string}  [quality="auto"]              - "low"|"medium"|"high"|"auto"
+ * @param {string}  [output_format="png"]         - "png"|"jpeg"|"webp"
+ * @param {string}  [background="auto"]           - "auto"|"transparent"|"opaque"
+ * @param {string}  [image_detail="high"]         - "low"|"high"|"auto"
+ * @param {string}  [image]                       - Reference image URL or base64 data URI
+ * @param {string[]} [images]                     - Multiple reference images
+ */
+// Codex (ChatGPT Plus/Pro) image generation via Responses API + SSE
+import { randomUUID } from "node:crypto";
+import { nowSec } from "./_base.js";
+
+const CODEX_RESPONSES_URL = "https://chatgpt.com/backend-api/codex/responses";
+const CODEX_USER_AGENT = "codex_cli_rs/0.136.0";
+const CODEX_VERSION = "0.136.0";
+const CODEX_ORIGINATOR = "codex_cli_rs";
+const CODEX_MODEL_SUFFIX = "-image";
+const CODEX_REF_DETAIL = "high";
+
+function decodeAccountId(idToken) {
+  try {
+    const parts = String(idToken || "").split(".");
+    if (parts.length !== 3) return null;
+    const b64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const pad = (4 - (b64.length % 4)) % 4;
+    const payload = JSON.parse(Buffer.from(b64 + "=".repeat(pad), "base64").toString("utf8"));
+    return payload?.["https://api.openai.com/auth"]?.chatgpt_account_id || null;
+  } catch {
+    return null;
+  }
+}
+
+function stripImageSuffix(model) {
+  return model.endsWith(CODEX_MODEL_SUFFIX) ? model.slice(0, -CODEX_MODEL_SUFFIX.length) : model;
+}
+
+function toDataUrl(input) {
+  if (!input || typeof input !== "string") return null;
+  if (/^data:image\//i.test(input) || /^https?:\/\//i.test(input)) return input;
+  return `data:image/png;base64,${input}`;
+}
+
+function buildContent(prompt, refs, detail = CODEX_REF_DETAIL) {
+  const content = [];
+  refs.forEach((url, index) => {
+    content.push({ type: "input_text", text: `<image name=image${index + 1}>` });
+    content.push({ type: "input_image", image_url: url, detail });
+    content.push({ type: "input_text", text: "</image>" });
+  });
+  content.push({ type: "input_text", text: prompt });
+  return content;
+}
+
+// Parse Codex SSE stream → final base64 image. Optional callbacks for client streaming.
+async function parseStream(response, log, callbacks = {}) {
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let imageB64 = null;
+  let lastEvent = null;
+  let bytesReceived = 0;
+  let lastProgressLogMs = 0;
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    bytesReceived += value?.byteLength || 0;
+    buffer += decoder.decode(value, { stream: true });
+
+    let sepIdx;
+    while ((sepIdx = buffer.indexOf("\n\n")) !== -1) {
+      const block = buffer.slice(0, sepIdx);
+      buffer = buffer.slice(sepIdx + 2);
+
+      const lines = block.split("\n");
+      let eventName = null;
+      let dataStr = "";
+      for (const line of lines) {
+        if (line.startsWith("event:")) eventName = line.slice(6).trim();
+        else if (line.startsWith("data:")) dataStr += line.slice(5).trim();
+      }
+      if (!eventName) continue;
+      if (eventName !== lastEvent) {
+        log?.info?.("IMAGE", `codex progress: ${eventName}`);
+        lastEvent = eventName;
+      }
+
+      const now = Date.now();
+      if (callbacks.onProgress && now - lastProgressLogMs > 200) {
+        lastProgressLogMs = now;
+        callbacks.onProgress({ stage: eventName, bytesReceived });
+      }
+
+      if (eventName === "response.image_generation_call.partial_image" && dataStr) {
+        try {
+          const data = JSON.parse(dataStr);
+          if (callbacks.onPartialImage && data?.partial_image_b64) {
+            callbacks.onPartialImage({ b64_json: data.partial_image_b64, index: data.partial_image_index });
+          }
+        } catch {}
+      }
+
+      if (eventName === "response.output_item.done" && dataStr) {
+        try {
+          const data = JSON.parse(dataStr);
+          const item = data?.item;
+          if (item?.type === "image_generation_call" && item.result) {
+            imageB64 = item.result;
+          }
+        } catch {}
+      }
+    }
+  }
+  return imageB64;
+}
+
+// SSE Response that pipes codex progress + partial + done events to client
+function buildSseResponse(providerResponse, log, onSuccess) {
+  const stream = new ReadableStream({
+    async start(controller) {
+      const enc = new TextEncoder();
+      const send = (event, data) => {
+        controller.enqueue(enc.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
+      };
+      try {
+        const b64 = await parseStream(providerResponse, log, {
+          onProgress: (info) => send("progress", info),
+          onPartialImage: (info) => send("partial_image", info),
+        });
+        if (!b64) {
+          send("error", { message: "Codex did not return an image. Account may not be entitled (Plus/Pro required)." });
+        } else {
+          if (onSuccess) await onSuccess();
+          send("done", { created: nowSec(), data: [{ b64_json: b64 }] });
+        }
+      } catch (err) {
+        send("error", { message: err?.message || "Stream failed" });
+      } finally {
+        controller.close();
+      }
+    },
+  });
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      "Connection": "keep-alive",
+      "X-Accel-Buffering": "no",
+      "Access-Control-Allow-Origin": "*",
+    },
+  });
+}
+
+export default {
+  stream: true,
+  buildUrl: () => CODEX_RESPONSES_URL,
+  buildHeaders: (creds) => {
+    const accountId = creds?.providerSpecificData?.chatgptAccountId || decodeAccountId(creds?.idToken);
+    return {
+      "accept": "text/event-stream, application/json",
+      "authorization": `Bearer ${creds?.accessToken || ""}`,
+      "chatgpt-account-id": accountId || "",
+      "content-type": "application/json",
+      "originator": CODEX_ORIGINATOR,
+      "session_id": randomUUID(),
+      "user-agent": CODEX_USER_AGENT,
+      "version": CODEX_VERSION,
+      "x-client-request-id": randomUUID(),
+    };
+  },
+  buildBody: (model, body) => {
+    const refs = [];
+    if (Array.isArray(body.images)) body.images.forEach((i) => { const u = toDataUrl(i); if (u) refs.push(u); });
+    const single = toDataUrl(body.image);
+    if (single) refs.push(single);
+    const detail = body.image_detail || CODEX_REF_DETAIL;
+    const imgTool = { type: "image_generation", output_format: (body.output_format || "png").toLowerCase() };
+    if (body.size && body.size !== "") imgTool.size = body.size;
+    if (body.quality && body.quality !== "") imgTool.quality = body.quality;
+    if (body.background && body.background !== "") imgTool.background = body.background;
+    return {
+      model: stripImageSuffix(model),
+      instructions: "",
+      input: [{ type: "message", role: "user", content: buildContent(body.prompt, refs, detail) }],
+      tools: [imgTool],
+      tool_choice: "auto",
+      parallel_tool_calls: false,
+      prompt_cache_key: randomUUID(),
+      stream: true,
+      store: false,
+      reasoning: null,
+    };
+  },
+  // Custom: codex parses SSE → either pipe to client or collect b64
+  async parseResponse(response, { log, streamToClient, onRequestSuccess }) {
+    if (streamToClient) {
+      return { sseResponse: buildSseResponse(response, log, onRequestSuccess) };
+    }
+    const b64 = await parseStream(response, log);
+    if (!b64) {
+      throw new Error("Codex did not return an image. Account may not be entitled (Plus/Pro required).");
+    }
+    return { created: nowSec(), data: [{ b64_json: b64 }] };
+  },
+  normalize: (responseBody) => responseBody,
+};

package/open-sse/handlers/imageProviders/comfyui.js

@@ -0,0 +1,25 @@
+/**
+ * ComfyUI local node-graph image generation adapter.
+ *
+ * Providers: comfyui (self-hosted instance)
+ * Auth: None (unauthenticated local endpoint)
+ * Format: JSON workflow prompt → async polling via /history endpoint
+ * Polling: Yes — submits prompt then polls /history/{prompt_id}
+ *
+ * Supported request params:
+ * @param {string}  prompt      - (required) Positive prompt text
+ * @param {number}  [n=1]       - Number of images
+ * @param {string}  [size]      - Dimensions → width/height in workflow
+ * @param {number}  [seed]      - Fixed seed
+ * @param {number}  [num_steps] - Sampling steps
+ *
+ * Response normalize: downloads generated images and converts to base64.
+ */
+// ComfyUI — local, noAuth (placeholder; full graph workflow not implemented)
+export default {
+  noAuth: true,
+  buildUrl: () => "http://localhost:8188",
+  buildHeaders: () => ({ "Content-Type": "application/json" }),
+  buildBody: (_model, body) => ({ prompt: body.prompt }),
+  normalize: (responseBody) => responseBody,
+};

package/open-sse/handlers/imageProviders/falAi.js

@@ -0,0 +1,62 @@
+/**
+ * Fal.ai asynchronous image generation adapter.
+ *
+ * Providers: fal-ai
+ * Auth: Key {apiKey} via Authorization header (uses "Key" prefix, not "Bearer")
+ * Format: JSON body → async queue submission + polling
+ * Polling: Yes — submits to /runs, polls /requests/{id}/status, fetches /requests/{id}
+ *
+ * Supported request params:
+ * @param {string}  prompt               - (required) Image description
+ * @param {string}  [model]              - Model path (e.g. "fal-ai/flux/schnell")
+ * @param {number}  [n=1]                - Number of images (num_images)
+ * @param {string}  [size="1024x1024"]   - Maps to image_size aspect ratio: "1:1"|"16:9"|"9:16" etc.
+ * @param {number}  [seed]               - Fixed seed for reproducibility
+ * @param {number}  [guidance]           - Guidance scale (model-dependent)
+ * @param {number}  [num_steps]          - Diffusion sampling steps
+ * @param {string}  [style]              - Style preset (Recraft/Ideogram only)
+ * @param {string}  [image]              - Reference image URL (img2img conditioning)
+ *
+ * Response normalize: maps images[] or image{} to { created, data: [{ url }] }.
+ */
+// Fal.ai — async submit + queue polling
+import { sleep, nowSec, sizeToAspectRatio, POLL_INTERVAL_MS, POLL_TIMEOUT_MS } from "./_base.js";
+
+const BASE_URL = "https://queue.fal.run";
+
+export default {
+  async: true,
+  buildUrl: (model) => `${BASE_URL}/${model}`,
+  buildHeaders: (creds) => {
+    const key = creds?.apiKey || creds?.accessToken;
+    return { "Content-Type": "application/json", "Authorization": `Key ${key}` };
+  },
+  buildBody: (_model, body) => {
+    const req = { prompt: body.prompt, num_images: body.n || 1 };
+    if (body.size) req.image_size = sizeToAspectRatio(body.size);
+    if (body.image) req.image_url = body.image;
+    return req;
+  },
+  async parseResponse(response, { headers }) {
+    const { status_url, response_url } = await response.json();
+    const deadline = Date.now() + POLL_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      await sleep(POLL_INTERVAL_MS);
+      const r = await fetch(status_url, { headers });
+      if (!r.ok) throw new Error(`Fal status ${r.status}`);
+      const s = await r.json();
+      if (s.status === "COMPLETED") {
+        const fr = await fetch(response_url, { headers });
+        return await fr.json();
+      }
+      if (s.status === "FAILED") throw new Error(s.error || "Fal generation failed");
+    }
+    throw new Error("Fal polling timeout");
+  },
+  normalize: (responseBody) => {
+    const images = Array.isArray(responseBody.images)
+      ? responseBody.images
+      : (responseBody.image ? [responseBody.image] : []);
+    return { created: nowSec(), data: images.map((img) => ({ url: img.url || img })) };
+  },
+};

package/open-sse/handlers/imageProviders/gemini.js

@@ -0,0 +1,40 @@
+/**
+ * Google Gemini multimodal image generation adapter.
+ *
+ * Providers: gemini (via NanoBanana tier routing)
+ * Auth: API key appended as ?key= query param
+ * Format: JSON body → sync JSON response (generateContent / generateImage)
+ * Polling: None (synchronous)
+ *
+ * Supported request params:
+ * @param {string} prompt  - (required) Image description text
+ *
+ * Notes:
+ * - No size, quality, or style params are supported by the Gemini image endpoint.
+ * - Response is normalized to { created, data: [{ b64_json, revised_prompt }] }.
+ */
+// Google Gemini adapter (Nano Banana models)
+import { nowSec } from "./_base.js";
+
+const BASE_URL = "https://generativelanguage.googleapis.com/v1beta/models";
+
+export default {
+  buildUrl: (model, creds) => {
+    const apiKey = creds?.apiKey || creds?.accessToken;
+    const modelId = model.replace(/^models\//, "");
+    return `${BASE_URL}/${modelId}:generateContent?key=${encodeURIComponent(apiKey)}`;
+  },
+  buildHeaders: () => ({ "Content-Type": "application/json" }),
+  buildBody: (_model, body) => ({
+    contents: [{ parts: [{ text: body.prompt }] }],
+    generationConfig: { responseModalities: ["TEXT", "IMAGE"] },
+  }),
+  normalize: (responseBody, prompt) => {
+    const parts = responseBody.candidates?.[0]?.content?.parts || [];
+    const images = parts.filter((p) => p.inlineData?.data).map((p) => ({ b64_json: p.inlineData.data }));
+    return {
+      created: nowSec(),
+      data: images.length > 0 ? images : [{ b64_json: "", revised_prompt: prompt }],
+    };
+  },
+};

package/open-sse/handlers/imageProviders/huggingface.js

@@ -0,0 +1,38 @@
+/**
+ * HuggingFace Inference API image generation adapter.
+ *
+ * Providers: huggingface
+ * Auth: Bearer token via Authorization header (apiKey or accessToken)
+ * Format: JSON body { inputs: prompt } → binary image response (PNG/JPEG)
+ * Polling: None (synchronous, may queue on HF side)
+ *
+ * Supported request params:
+ * @param {string} prompt  - (required) Image description text
+ *
+ * Notes:
+ * - Only "inputs" (prompt) is accepted by the HF Inference endpoint.
+ * - No size, quality, style, or other params are passed through.
+ * - Response normalize: converts raw binary image to base64 data URI.
+ */
+// HuggingFace Inference API — returns binary image
+import { nowSec } from "./_base.js";
+
+const BASE_URL = "https://api-inference.huggingface.co/models";
+
+export default {
+  buildUrl: (model) => `${BASE_URL}/${model}`,
+  buildHeaders: (creds) => {
+    const headers = { "Content-Type": "application/json" };
+    const key = creds?.apiKey || creds?.accessToken;
+    if (key) headers["Authorization"] = `Bearer ${key}`;
+    return headers;
+  },
+  buildBody: (_model, body) => ({ inputs: body.prompt }),
+  // HF returns raw image bytes — convert to b64_json
+  async parseResponse(response) {
+    const buf = await response.arrayBuffer();
+    const base64 = Buffer.from(buf).toString("base64");
+    return { created: nowSec(), data: [{ b64_json: base64 }] };
+  },
+  normalize: (responseBody) => responseBody,
+};