My Node.js Text-to-Image Gate: A Web App API Contract Test

Pick the text-to-image API that makes its response contract easy to test, then hide that contract behind your own Node.js adapter. That is the choice I make for a web app in 2026. Developer experience matters, but a polished SDK cannot rescue an ambiguous payload, an undocumented asynchronous state, or an image URL that expires before my worker stores it. I want docs, an SDK only where it saves real work, and a response format I can validate at the boundary. The experiment: a pretty demo versus a boring contract I ran the same prompt through three API shapes: an immediate binary response, a JSON response containing a URL, and a job response that required polling. The first shape was fast to demo but awkward for retries. The second fit a browser-facing workflow, provided I copied the bytes into durable storage. The third was the most operationally honest for slow generation, but it added state, idempotency, and a queue to my small app. The failure that changed my checklist was a cost surprise. I estimated a weekend image feature at about $40, then the invoice landed at $186. The culprit wasn't one expensive image; my retry loop regenerated an image after a client timeout, and the browser also retried a form submission. I had measured successful requests, not attempts. That number is why I now log a request ID, prompt hash, retry count, and final image ID before I call a generation API. The postmortem took most of an afternoon because the logs from the browser and worker used different IDs. I had to line up timestamps, prompt hashes, and storage keys by hand, then replay the same timeout with a fake provider. The fix was unglamorous: create the idempotency key at the web boundary, pass it through every retry, and record an attempt before sending bytes. I also put a hard per-user attempt limit in front of the queue. The limit isn't a substitute for billing alerts, but it turns an accidental loop into a visible, bounded event. That is the kind of developer experience I now look for in docs: can I explain the lifecycle to myself at 2 a.m., and can I prove which request produced the artifact? Short tests beat opinions. For each candidate I send one deliberately ordinary prompt, one prompt near the input limit, and one request with an idempotency key. I record time to first response, time to usable bytes, payload size, error fields, and whether the docs explain retention. My UI has a 900 ms acknowledgment budget, so I measure that separately from the final image latency. Then I repeat the run from a cold worker. Your mileage may vary, especially if the provider queues work by region. How do I test a Node.js web app's text-to-image API response format? I start with a provider-neutral interface. The web route should return my schema, not a vendor's accidental field names. Here is the smallest adapter I can live with: type ImageResult = { id: string; status: "completed" | "pending"; url?: string; bytesBase64?: string; }; type ImageRequest = { prompt: string; size: "square" | "landscape" | "portrait"; idempotencyKey: string; }; function assertImageResult(value: unknown): asserts value is ImageResult { if (!value || typeof value !== "object") throw new Error("Image response is not an object"); const result = value as Record; if (typeof result.id !== "string") throw new Error("Image response has no stable id"); if (result.status !== "completed" && result.status !== "pending") { throw new Error("Image response has an unknown status"); } if (result.url !== undefined && typeof result.url !== "string") { throw new Error("Image response url is not a string"); } } export async function generateImage( endpoint: string, token: string, request: ImageRequest, ): Promise { const response = await fetch(endpoint, { method: "POST", headers: { authorization: `Bearer ${token}`, "content-type": "application/json", "idempotency-key": request.idempotencyKey, }, body: JSON.stringify(request), }); const body: unknown = await response.json(); if (!response.ok) throw new Error(`Image API request failed: ${response.status}`); assertImageResult(body); return body; } The endpoint is injected so I can run contract tests against a fixture server and swap providers without changing the web handler. I also reject a successful HTTP status when the application status is unknown. A 200 is transport evidence, not proof that an image exists. What should docs, SDKs, and response formats prove before launch? I grade the developer experience with artifacts, not vibes. Docs should show authentication, a complete request, every response state, rate-limit headers, and retention rules. An SDK should expose cancellation and typed errors; if it only shortens fetch by two lines, I would rather own the adapter. The response format needs a stable ID, an explicit status, and a durable way to obtain bytes. A temporary URL is fine as a handoff, not as my database record. Check Prefer Treat as a warning Request semantics documented size, format, and safety fields fields shown only in samples Long jobs pending status plus polling or webhook contract a request that can hang indefinitely Errors machine-readable code and retry guidance prose-only error messages Delivery URL expiry and byte download rules are explicit an opaque URL with no lifetime SDK versioned types and raw-response escape hatch generated client with weak types I keep these checks in CI with recorded fixtures. One fixture is a completed response, one is pending, and one is a malformed 200. The malformed case has caught more integration mistakes than happy-path snapshots. I'm not sure why teams skip it; perhaps the demo output looks so persuasive that the boundary becomes invisible. My adapter pattern is a poor fit when a product needs interactive canvas updates every few hundred milliseconds, strict on-premise execution, or pixel-level reproducibility across months. In those cases, use a local inference stack or a specialized rendering service whose latency and artifact controls match the requirement. A general API can also be the wrong tool for bulk catalogs: a batch workflow with explicit quotas and resumable manifests is easier to audit than thousands of request-level retries. The trade-off is maintenance. I pay for a small amount of schema code and fixture upkeep, but I get a stable application contract and can measure real generation attempts. That is a better bargain for a solo founder than being locked to an SDK's object model. I still revisit the choice when quality, region availability, or licensing requirements change. Before copying this approach, measure three things with your own prompts: usable-image latency, duplicate-attempt rate, and the percentage of responses that require a second request. If those numbers are unknown, the API selection is still a guess. References https://platform.openai.com/docs/guides/batch https://www.promptingguide.ai