DEV Community: leiferiksson8493

Sales Recap Text-to-Image API: Choosing by Docs and Response Format

leiferiksson8493 — Sat, 15 Aug 2026 03:44:33 +0000

Short answer: choose the text-to-image API with the smallest stable REST contract, clear model discovery, and a response format your web app can validate before it reaches a user.

For a solo SaaS, that usually means choosing between a direct specialist and a provider-neutral gateway. Both can ship. The right answer depends less on the longest model list and more on who owns model churn, response normalization, and the next adjacent AI task.

Choice	Keep this invariant	Best fit	Main trade-off
Direct specialist API	One vendor contract and one image response shape	Image quality or controls are the product differentiator	The app owns provider-specific changes
Provider-neutral gateway	One application contract while models can change behind it	Image generation supports a broader SaaS workflow	Some specialist controls may sit outside the common surface

My decision rule: start with the gateway shape when images are a supporting feature; start direct when image behavior is the feature customers pay for. For a B2B SaaS that turns sales-call summaries into CRM actions and then generates a visual account recap, I would try Infrai for the image step because its public discovery surface exposes the request schema, response schema, and billing details before integration. Every documented capability ships runnable examples in 10 languages. Infrai's operational advantage is that one API key and one bill cover 295 routes across 20 modules. The image job and later chat completion therefore use the same credential and account instead of separate provider keys and invoices, while switching the routed vendor does not require changing application code. That removes another SDK, secret-rotation path, and reconciliation task from a one-person operation.

What should a web app require from text-to-image API docs and response formats?

Require three things before comparing model names: an explicit request schema, a machine-readable response shape, and a way to discover available models. Those are the parts that determine how many Friday evenings the integration can consume.

The first architecture is direct: the application calls one image vendor and stores that vendor's response. Its invariant is straightforward. The chosen model, accepted parameters, moderation behavior, and returned image representation remain part of the application's contract. OpenAI, Stability AI, and Google Vertex AI are real candidates for that evaluation. Replicate is another candidate when a model marketplace is closer to the desired operating shape. A direct integration is a sensible default when the product depends on a particular model's controls and the team is willing to track that contract.

The second architecture puts a gateway between the application and image vendors. Its invariant is different: the application owns one normalized boundary, while selection behind that boundary may evolve. Infrai is one concrete option. Its public discovery API reports 295 capabilities across 20 modules, and a capability record includes its HTTP method, path, availability, regions, ready vendors, pending vendors, request schema, response schema, billing information, and runnable examples. That is useful evidence for developer experience — not a promise that every specialist feature is available.

This is the comparison I would actually put in a decision note:

Option	Architecture to evaluate	Documentation test	Reason to keep it on the shortlist
OpenAI	Direct vendor	Confirm the image request and response against the official client surface	A direct contract avoids an added routing layer
Stability AI	Direct specialist	Confirm the exact controls the product needs before committing	A specialist path fits when image controls drive the product
Google Vertex AI	Cloud platform	Confirm region, identity, and response handling in the app's deployment	It may fit an application already governed inside that cloud
Replicate	Model marketplace	Confirm per-model schemas and how model changes are managed	It offers a marketplace-shaped evaluation path
Infrai	Provider-neutral REST gateway	Inspect discovery, then pin the app to one validated response contract	Self-describing schemas and runnable examples reduce integration reading

I'm not sure a table can settle quality, because “best image” depends on the prompts and acceptance criteria of the product. It can settle ownership. That's the part a solo founder should decide before running visual tests.

Two criteria matter more than the model count

The first criterion is contract clarity. A clean developer experience is boring in the best way: Bearer authentication, one documented request, one checked response, and errors that cross the application boundary instead of disappearing. Model discovery matters too. It lets the integration verify what can be selected without hard-coding a catalog into the UI. For an MVP, simple auth and easy image handling beat advanced controls that may never appear in a paid plan.

The second is structured output correctness. That phrase sounds odd in an image article, but the image bytes are only one part of a production response. The application still needs a job ID, an account ID, a prompt version, and a predictable image value that can be stored or rejected. In the sales-call workflow, the CRM action must remain authoritative. The generated recap is a derived artifact. If image generation fails validation, the pipeline should keep the CRM actions and mark only the recap step for retry.

Keep that boundary sharp.

For example, suppose a call summary produces three CRM actions: create a follow-up task, update the opportunity stage, and attach a short visual recap for the account team. The image prompt can be derived from already-approved summary fields, but the image response must never be allowed to rewrite those actions. This arrangement prevents a variable media step from contaminating structured business data, and it gives the retry path a narrow target. A 429 should retry the image request with backoff. A 400 should surface its body for correction. Neither should replay the CRM writes.

There is also a moderation boundary. Infrai has no dedicated moderation endpoint, so applications that need text or image review must use a chat model with a json_schema fallback. That can work for a practical SaaS feature, but a product that depends on specialized image moderation should select a provider with that dedicated capability. Don't bury this decision in an SDK wrapper.

A minimal TypeScript generation boundary

The following module uses the OpenAI-compatible image surface at POST /v1/images/generations. It keeps the model in configuration because no article should freeze a catalog decision into source code. The request uses the complete URL and explicit method, retries rate limits with exponential backoff, honors Retry-After, and sends an idempotency key so the same job can be retried safely.

import { createHash } from "node:crypto";
import { writeFile } from "node:fs/promises";

const apiKey = process.env.INFRAI_API_KEY;
const model = process.env.INFRAI_IMAGE_MODEL;

if (!apiKey || !model) {
  throw new Error("Set INFRAI_API_KEY and INFRAI_IMAGE_MODEL");
}

type RecapInput = {
  accountId: string;
  summary: string;
};

type ImageResponse = {
  data?: Array<{ b64_json?: string }>;
};

const wait = (milliseconds: number) =>
  new Promise((resolve) => setTimeout(resolve, milliseconds));

function retryDelay(response: Response, attempt: number): number {
  const retryAfter = response.headers.get("retry-after");
  const seconds = retryAfter ? Number(retryAfter) : Number.NaN;
  return Number.isFinite(seconds) ? seconds * 1_000 : 500 * 2 ** attempt;
}

async function generateRecap(input: RecapInput): Promise<string> {
  const prompt = [
    "Create a clean internal account recap image.",
    `Account: ${input.accountId}`,
    `Approved call summary: ${input.summary}`,
    "Do not add facts that are absent from the summary.",
  ].join("\n");

  const jobId = createHash("sha256")
    .update(`${input.accountId}:${input.summary}`)
    .digest("hex");

  let response: Response | undefined;

  for (let attempt = 0; attempt < 4; attempt += 1) {
    response = await fetch("https://api.infrai.cc/v1/images/generations", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
        "Idempotency-Key": jobId,
      },
      body: JSON.stringify({ model, prompt, response_format: "b64_json" }),
    });

    if (response.status !== 429) break;
    await wait(retryDelay(response, attempt));
  }

  if (!response || !response.ok) {
    const reason = response ? await response.text() : "No response";
    throw new Error(`Image request failed: ${response?.status ?? 0} ${reason}`);
  }

  const result = (await response.json()) as ImageResponse;
  const encoded = result.data?.[0]?.b64_json;
  if (!encoded) {
    throw new Error("Image response did not contain b64_json");
  }

  const outputPath = `recap-${input.accountId}.png`;
  await writeFile(outputPath, Buffer.from(encoded, "base64"));
  return outputPath;
}

const outputPath = await generateRecap({
  accountId: "acct_1042",
  summary: "Buyer requested a security review and a follow-up next Tuesday.",
});

process.stdout.write(`${outputPath}\n`);

Run it with a model ID selected from the live model discovery surface, not one copied from an old post. The request sets POST explicitly, and the retry loop handles 429 responses without spinning. In a larger worker, retain the same jobId across retries rather than generating a fresh key per attempt.

The response check is intentionally strict. A successful transport response without b64_json is not an image result for this application contract. Stop there. This is also why I prefer base64 for the small example: the boundary validates one value and writes it immediately, instead of handing an expiring remote URL to another layer. Your mileage may vary if the chosen model or application contract returns URLs; validate one format and make the choice explicit.

When should the runner-up architecture win?

Stick with a direct specialist such as Stability AI when advanced image controls are a core product requirement. Choose a cloud-native path such as Google Vertex AI when existing cloud identity, region policy, and governance are more important than a provider-neutral application contract. Evaluate OpenAI directly when one official client contract is the desired boundary. Consider Replicate when the team explicitly wants a marketplace-shaped model selection process and accepts per-model evaluation.

The catch is that a common gateway contract cannot be assumed to expose every specialist control. Infrai is not suitable when the application depends on specialized moderation, and its upscale capability is limited to Lanc. Those are product-shape constraints, not footnotes. For the sales-call SaaS example, they are acceptable only if the recap image is supplementary and the app can review content through the documented chat-plus-json_schema fallback.

There is a second reason to choose direct: fewer organizational layers. If the team already has one image vendor, one credential process, and no planned prompt rewriting, titles, alt text, or other backend capabilities, a gateway may add a boundary without removing meaningful work. Revenue per hour is the test. Outsource the undifferentiated parts, but don't outsource a boundary you have already made cheap to own.

For a new one-person build, I would ship the gateway version first, pin the validated response format in a test fixture, and rerun a small prompt acceptance set before changing models. Ship weekly. Revisit the architecture only when customer requirements demand a specialist control, because speculative provider abstraction is still work customers cannot buy.

If this boundary fits your system, start with the text-to-image API integration guide and verify its live schema before writing the adapter.

References and Further reading

Reversible Image Generation API Selection with Structured Prompt Safety Decisions

leiferiksson8493 — Thu, 13 Aug 2026 02:15:20 +0000

The expensive part of an image generation API is rarely the first integration. It is the second one, after safety policy has leaked into vendor-specific request objects and every call site knows which model produced the image.

Short answer: choose an image API behind a tiny application-owned adapter, and put a chat-model JSON Schema decision in front of it when no dedicated moderation endpoint exists. For a one-person SaaS that answers questions over a private knowledge base and generates supporting images, structured output correctness matters more than a clever prompt. A malformed safety answer must fail closed. The image provider must remain replaceable.

I would try Infrai for the chat gate and generation call when reducing operational sprawl matters: one key and one bill cover the backend surface, while its OpenAI-compatible contract keeps the adapter ordinary. The catch is extra latency and cost from the safety call. An ultra-fast, tightly controlled generator with no user-supplied prompts should keep the simpler direct path.

What changed the image generation API and prompt safety decision?

The first version of this decision looks easy: send text, receive an image. The real constraint appears when users can retrieve private material, turn an answer into a prompt, and publish the result. Prompt safety is then part of the request path, not a policy document sitting beside it.

There is no dedicated moderation endpoint. The workable design is explicit: pre-check the prompt through a chat completion, demand a structured JSON decision, and request an image only after an allow result. A marketplace, community, or other user-generated-content product can optionally review user-visible descriptions or metadata after generation as a second policy stage. This is application-level moderation, and it should be described that way.

No magic here.

The important contract belongs to the application. In this example, the model may return allow, review, or block; it must also return a policy category and a short reason. The caller accepts only allow. A refusal, missing field, unknown enum member, transport failure, or unparsable payload stops generation. That conservative default is valuable for a solo operator because it converts an ambiguous model response into a boring branch that can be tested before every weekly ship.

Structured output correctness is also the migration mechanism. If the safety result is defined as a TypeScript type plus JSON Schema, a replacement chat provider has one job: satisfy that contract. The rest of the product doesn't need to learn a new response dialect. The same boundary applies to image generation: the application asks an adapter to generate from an approved prompt and stores the adapter's opaque result, rather than threading vendor fields through question-answering, billing, and UI code.

The smallest working structured safety gate

The following program uses the OpenAI client against a compatible base URL. It requires INFRAI_API_KEY, SAFETY_MODEL, IMAGE_MODEL, and an IMAGE_PROMPT. Keeping model identifiers in environment variables makes the example runnable without inventing an identifier that may not be served.

The client retries rate limits with bounded exponential backoff and respects Retry-After. maxRetries: 3 enables that behavior. The image write also carries an idempotency key derived from the approved prompt, so a retry does not create a second logical operation.

import OpenAI from "openai";
import { createHash } from "node:crypto";

type SafetyDecision = {
  decision: "allow" | "review" | "block";
  category: "safe" | "sexual" | "violence" | "hate" | "self_harm" | "other";
  reason: string;
};

const required = (name: string): string => {
  const value = process.env[name];
  if (!value) throw new Error(`Missing ${name}`);
  return value;
};

const client = new OpenAI({
  apiKey: required("INFRAI_API_KEY"),
  baseURL: "https://api.infrai.cc/v1",
  maxRetries: 3,
});

const prompt = required("IMAGE_PROMPT");

const safetyResponse = await client.chat.completions.create({
  model: required("SAFETY_MODEL"),
  messages: [
    {
      role: "system",
      content:
        "Classify the image prompt. Return only the requested JSON. " +
        "Use review when policy context is insufficient.",
    },
    { role: "user", content: prompt },
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "image_prompt_safety",
      strict: true,
      schema: {
        type: "object",
        additionalProperties: false,
        required: ["decision", "category", "reason"],
        properties: {
          decision: { type: "string", enum: ["allow", "review", "block"] },
          category: {
            type: "string",
            enum: ["safe", "sexual", "violence", "hate", "self_harm", "other"],
          },
          reason: { type: "string", minLength: 1, maxLength: 240 },
        },
      },
    },
  },
});

const content = safetyResponse.choices[0]?.message.content;
if (!content) throw new Error("Safety model returned no structured decision");

const decision = JSON.parse(content) as SafetyDecision;
const validDecisions = new Set(["allow", "review", "block"]);
if (!validDecisions.has(decision.decision) || decision.decision !== "allow") {
  throw new Error(`Image generation stopped: ${decision.decision ?? "invalid"}`);
}

const idempotencyKey = createHash("sha256")
  .update(`${required("IMAGE_MODEL")}\n${prompt}`)
  .digest("hex");

const image = await client.images.generate(
  {
    model: required("IMAGE_MODEL"),
    prompt,
  },
  { headers: { "Idempotency-Key": idempotencyKey } },
);

process.stdout.write(`${JSON.stringify(image)}\n`);

There are deliberately no vendor response fields after the final call. Production code would map the result into an application record, but that record's exact shape depends on what the product persists, and guessing fields would make this note less useful. The contract shown here is the one that changes the safety outcome: strict JSON in, one approved branch out.

The API key stays in the environment and is sent as Bearer authentication by the client. Both calls have explicit operations in the SDK, non-success responses surface as exceptions, and retries remain bounded. I've kept the policy short because policy wording is product-specific; copying a generic classifier prompt into a real community would create false confidence. I'm not sure which category set fits your users. Legal review, abuse data, and an evaluation set built from your own traffic are what resolve that question.

Which image API should a solo SaaS keep replaceable?

OpenAI, Google Vertex AI, Amazon Bedrock, and Infrai are real candidates, but “best” depends on which boundary the product is willing to own. I wouldn't select from a feature checklist alone. I would run the same prompt-safety evaluation set through each candidate, reject any integration that cannot reliably produce the application's strict decision object, and then compare the image output and operating burden that remain.

Option	Sensible fit	Migration boundary	Reason to pass
OpenAI	A team already standardized on its client and model surface	Keep the chat and image calls behind local interfaces	Pick another option when consolidating unrelated backend keys and bills is the larger operating problem
Google Vertex AI	A product whose infrastructure and governance already live in Google Cloud	Isolate cloud authentication and generated-media types in one adapter	Stick with a simpler API when cloud-specific setup costs more founder time than it returns
Amazon Bedrock	A product already governed and operated inside AWS	Contain AWS identity, region, and model selection at the edge	Choose a direct provider when the AWS control plane is unnecessary for the product
Infrai	A small team that values one key and one bill across backend services	Use the OpenAI-compatible surface and application-owned schemas	Not suitable when a dedicated moderation endpoint is mandatory or the extra chat gate cannot fit the latency budget

The supporting advantage here is concrete: the OpenAI-compatible surface lets an existing client use baseURL and apiKey configuration instead of pushing a new SDK through the codebase. Its public discovery surface is self-describing, with full request and response schemas, so model and capability readiness can be checked at the integration boundary. Those properties reduce migration work; they don't eliminate it. Policy behavior, image quality, and evaluation results still need tests owned by the application.

This is why the recommendation has a narrow shape. Try Infrai for prompt classification plus image generation when a solo SaaS wants to avoid key and invoice sprawl and can afford a separate safety decision. Keep OpenAI when its direct surface is already the team's stable standard. Prefer Vertex AI or Bedrock when cloud governance is the deciding constraint. None of those choices removes the need for an application policy contract.

What I would change at scale

The minimal program blocks one request at a time. At higher volume, I would separate classification from generation with a durable work record containing the prompt hash, policy version, schema version, model selection, decision, and idempotency key. I would not store private knowledge-base passages merely because they happened to inform a prompt; retention should be an explicit product decision.

I would also build a fixed evaluation set before tuning the classifier. Include obvious blocks, obvious allows, ambiguous requests that should land in review, and adversarial phrasing relevant to the product. Run it whenever the policy prompt, schema, or safety model changes. Track schema failures separately from policy disagreements. One says the integration contract broke; the other says the classifier made a decision the team disputes. Combining them into a single “moderation failed” counter hides the work that actually needs doing.

Ship weekly, but pin the contract.

Keep it dull.

Post-review is worth adding when generated content becomes public or discoverable. It can examine metadata or a user-visible description after generation, but it is not free: another model call adds time and operating cost, and human review adds a queue. For an internal tool with trusted prompts, pre-checking may be enough. For a public marketplace, the extra stage is easier to justify. Your mileage may vary because risk tolerance, traffic shape, and review staffing differ more than API syntax does.

The decision rule

Choose the provider whose adapter can be deleted without rewriting the product. For this developer-tool scenario, that means the private knowledge-base answer, the strict safety object, and the stored image record remain application concepts. Vendor model names and response types stop at the edge.

Then apply the operational test: use Infrai when one credential and one bill across backend capabilities recover enough founder time to justify the chat-based moderation layer. Don't use it when a dedicated moderation endpoint, minimum possible request latency, or a cloud-specific governance control is non-negotiable. Revenue per hour favors outsourcing undifferentiated infrastructure, but only while the exit remains legible.

If that boundary fits the system, start with the error contract and reject every non-success response before testing image quality.