Image generation and editing APIs

Read these first

• Chat API shape

What you will know

• Integrate an image generation API into a product flow

  The production path needs asynchronous job handling, asset persistence, moderation, and a usable timeout and retry policy.

• Measure cost and latency across representative prompts and output settings

  Resolution, inference steps, queueing, provider pricing, and tail latency can change the economics far more than a single successful request suggests.

• Control output enough to be usable in a brand context

  A prompt that works once rarely survives model or version drift; references, constraints, and human review establish the acceptance bar.

• Implement and verify at least two image editing operations

  Mask boundaries, alpha handling, image dimensions, and compositing artifacts commonly undermine otherwise successful edits.

• Handle a generation that fails or returns something unusable

  Retries can multiply spend, while safety refusals, malformed files, and visually poor results require different user-visible outcomes.

Chapters

1. 1

   An image request is a job, and its result is your asset

   Calling the generation API inline and returning the URL works in dev and fails three ways in production: generations that run tens of seconds hit gateway timeouts, the client retry starts a second billed generation, and the provider-hosted URL you stored expires within hours and takes the image with it. The production shape is a job record, an idempotency key, polling or a webhook, and a copy of the bytes into storage you own.

   Read chapter
2. 2

   Moderation you owe is separate from the refusal the provider gives

   A provider declining your prompt is the provider's policy; the policy on your own surface is a different artefact and nobody else writes it. Decide what users may submit for editing, covering likeness, minors, trademarks and NSFW, and check the returned asset before it reaches anyone but the person who asked for it, because a hero-image button ships generated content into a customer's product and background replacement takes photographs of real people. Settle retention, who can retrieve a generation later, and whether the assets you emit carry provenance metadata, before the pipeline is already carrying user uploads.

   Read chapter
3. 3

   Four ways a generation fails, four different answers

   A safety refusal must not be retried, because the same prompt will refuse again and each attempt bills; tell the user specifically what to change. A malformed response or transport error is worth a bounded retry. A timeout needs the job checked before it is reissued. A technically valid but visually unusable image is none of those, and regenerating is a product decision with a price attached.

   Read chapter
4. 4

   Unit cost is per accepted image, not per API call

   At $0.04 a generation and 6.2 generations per accepted result, your real cost is $0.25 per delivered image, and that 6.2 is simultaneously a quality metric worth driving down. Resolution and quality tier move the per-image price several-fold, so a single successful request tells you almost nothing about the economics. The mean is not the argument, though, because the shallow answer uses the same mean: a $29 plan breaks even near 116 accepted images before any other cost, unlimited is priced by the top percentile rather than the average user, and a worse model that pushes 6.2 higher moves that line again. Counter with an included allowance and metered or degraded overage rather than a promise.

   Read chapter
5. 5

   A brand look is built from references, seeds and constraints, not adjectives

   Output a brand team will accept does not come from better wording. Reference or style images bind the result far harder than text and you need to know how hard; a fixed seed makes a comparison repeatable, though not necessarily across model versions; negative prompts and explicit aspect and layout constraints remove what a prompt cannot add; and some brand attributes are not reachable through prompt text at all, which is a finding worth reaching early rather than after three weeks of tuning. This also decides whether the next chapter's method means anything, since without a fixed seed or several samples per prompt a side-by-side difference may be the dice rather than the version.

   Read chapter
6. 6

   A tuned prompt is not a contract with the model

   Six months of on-brand output ends the day the provider rolls its default model version, and the output is subtly off rather than obviously broken, so nobody catches it for a week. What was missing beforehand is a pinned version and a golden prompt set rendered and compared side by side on every version change. Reference images, explicit constraints and a named human acceptance bar do the rest.

   Read chapter
7. 7

   Masks, alpha and edges: why edits fail on real uploads

   Inpainting endpoints usually treat the transparent region of the mask as the area to replace, so code that paints the target white edits everything except it. Beyond polarity, edits break on dimension mismatch between mask and source, premultiplied alpha, and matting around hair, glass and motion blur, which is why background replacement looks clean on the designer's studio shots and halos on real phone photos.

   Read chapter