DEV Community: Barry Xiong

Building a Reliable AI Image Pipeline: Tasks, Failures, and Credit Refunds

Barry Xiong — Thu, 06 Aug 2026 15:36:19 +0000

Most AI image generators look like a prompt box with a Generate button. That is also how my first version started.

But once real users entered the workflow, the difficult problems appeared somewhere else: browser refreshes, external task IDs, reference images, partial failures, credit refunds, private assets, and public artwork moderation.

While building Magggic, I learned that an AI image generator is less like a form submission and more like a small distributed job system. This article covers the decisions that made that workflow more reliable.

The code samples below are intentionally simplified. The important part is the shape of the workflow, not a specific database or image provider.

The prompt box is only the beginning

A synchronous prototype is easy to imagine:

const images = await provider.generate(prompt);
return images;

That version works until the request takes a minute, the provider times out, one of four requested images fails, or the user refreshes the page.

The production workflow I needed looked more like this:

Prompt + references
        ↓
Create a local queued task
        ↓
Charge credits with an idempotency key
        ↓
Submit work to the image provider
        ↓
Persist every completed output immediately
        ↓
Finalize the task and refund failed outputs
        ↓
Keep the result private until the user publishes it

The provider request is only one step. The local task is the source of truth for what the user sees.

1. Persist the task before calling the provider

The first important decision was to create a generation record before making the external API request.

A generation stores the information needed to reconstruct the job:

type Generation = {
  id: string;
  userId: string;
  idempotencyKey: string;
  prompt: string;
  referenceImages: string[];
  model: string;
  ratio: string;
  resolution: string;
  count: number;
  cost: number;
  status: "queued" | "generating" | "completed" | "failed";
  outputs: string[];
  providerRequestIds: string[];
  failureReason: string | null;
};

Persisting first gives the UI a stable generation ID immediately. The browser can refresh, reconnect, or open the task from history without depending on the original HTTP connection.

It also gives operational errors a useful identity. “The provider timed out” is difficult to investigate. “Generation abc123 timed out after provider task xyz789” is actionable.

2. Make state transitions explicit

Generation states should not be decorative labels. They should control which writes are valid.

For example, a worker should only start a queued task:

const started = await updateGeneration({
  id: generationId,
  expectedStatus: "queued",
  nextStatus: "generating",
});

if (!started) return;

Likewise, an output should only be attached while the task is generating. Final completion should fail loudly if the task is already in an unexpected state.

This avoids two common problems:

two workers processing the same task;
a late provider response overwriting a task that has already failed or completed.

I prefer conditional updates over reading a status and then updating it later. The condition and the transition happen together, which makes races much easier to reason about.

3. Persist each output as soon as it succeeds

When a user requests four images, the provider may effectively give you four independent outcomes. Waiting for every result before saving anything creates unnecessary risk.

The workflow now persists each completed image as it arrives:

async function persistCompletedOutput(output: ProviderOutput) {
  const storedUrl = await storeImage(output.bytes, output.contentType);

  await appendGenerationOutput({
    generationId,
    expectedStatus: "generating",
    outputIndex: output.index,
    storedUrl,
    externalTaskId: output.taskId,
  });
}

This produces three useful properties:

A successful image is not lost because another image failed later.
Progress is based on real persisted outputs, not an invented percentage.
The UI can show completed images while the remaining outputs are still running.

There is one uncomfortable edge case: storage succeeds but the database write fails. In that case, the stored object should be deleted or recorded for cleanup. Otherwise every database outage can leave orphaned files behind.

4. Treat partial success as a real outcome

The easiest implementation treats a batch as either successful or failed. That is also the least useful implementation for the user.

Suppose the user requests four images:

three images complete successfully;
one provider task fails;
the total generation price was 32 credits.

Marking the whole task as failed hides three valid outputs. Marking it as fully successful charges the user for something they did not receive.

The better result is:

status: completed
successful outputs: 3
failed outputs: 1
credits refunded: 8
failure note: one output could not be completed

In simplified form:

const failedCount = results.filter(isRejected).length;
const refundAmount = failedCount * unitCost;

await transaction(async (tx) => {
  await refundCredits(tx, generationId, refundAmount);
  await completeGeneration(tx, generationId, {
    outputs: completedOutputs,
    failureReason: failedCount ? buildPartialFailureMessage() : null,
  });
});

The final state can still be completed because usable outputs exist. The partial-failure message explains why fewer images were returned and how many credits were refunded.

5. Credits need a ledger, not only a balance

At first, a credit system looks like one integer on the user record:

user.credits -= cost;

That stops being sufficient as soon as you need to answer basic support questions:

Why did this balance change?
Was this generation charged twice?
Was a failed task refunded?
Which type of credits were consumed?
What was the balance after the operation?

The approach I settled on keeps both current balances and an append-only ledger.

type CreditLedgerEntry = {
  userId: string;
  kind: "grant" | "spend" | "refund" | "expire" | "adjustment";
  amount: number;
  balanceAfter: number;
  referenceType: "generation" | "payment" | null;
  referenceId: string | null;
  idempotencyKey: string;
};

Every spend or refund has a unique idempotency key. Retrying the same completion handler cannot create a second refund.

This is especially important with asynchronous providers. Network timeouts encourage retries, and retries are exactly where accidental double charges and double refunds appear.

6. Prompt remix and reference reuse are different operations

An image detail page often needs two actions that look similar but have different semantics:

Create similar reuses the prompt and generation parameters.
Use as reference sends the current image back as a visual input.

Combining them into one generic “Remix” action makes the data ambiguous. A future reviewer cannot tell whether the result came from text alone or from another image.

I now store reference images on the generation task and carry a separate reference-image status onto a published artwork. For manually imported artwork, the status can be used, not_used, or unknown.

This provenance matters for three reasons:

The UI can explain what another user needs to reproduce the result.
Public pages do not need to expose the original private reference file.
Moderation and support can distinguish text-to-image from image-guided generation.

7. A generated asset is not automatically a public artwork

Another early design mistake is treating every generated image as public content.

Generation outputs belong in the user's private assets and history. Publishing is a separate action with a separate lifecycle:

type ArtworkStatus =
  | "pending"
  | "published"
  | "rejected"
  | "withdrawn"
  | "hidden";

The artwork record can reference a generation output, but it also owns public metadata such as category, tags, publication time, moderation state, and the public image URL.

This separation keeps several product rules simple:

Refreshing generation history never publishes anything.
A user can submit only the output they choose.
Moderation can reject or hide a public artwork without deleting the private generation.
Public Latest and Popular feeds operate on approved artwork, not raw generation history.

It also prevents a privacy problem: a successful provider response should never equal automatic consent to publish.

8. Design failure states as part of the product

Failure UI is often added at the end, but it is part of the core workflow.

A useful failed task should tell the user:

what happened in plain language;
whether any outputs were saved;
whether credits were refunded;
whether retrying will create a new task;
where the failed attempt remains visible.

I keep failed records in generation history instead of removing them. Retrying creates a new history item rather than rewriting the old one. That gives both the user and the support team a truthful timeline.

The same rule applies to progress. If the provider only gives a queued state and a completed result, the UI should show those real states. A beautiful fake “73%” progress bar is still fake.

What I would do from the first day now

If I were starting the generation workflow again, I would make these decisions before polishing the prompt box:

Create a persistent local task before calling any provider.
Use conditional state transitions for workers and result writes.
Persist each output independently.
Model partial success instead of flattening every batch into pass or fail.
Record credits in an idempotent ledger.
Keep text remix and image reference reuse separate.
Separate private generated assets from moderated public artwork.

None of these ideas is limited to image generation. Any AI product that combines asynchronous providers, paid usage, and persistent outputs will eventually face the same questions.

The prompt box is the visible part. Reliability is the product underneath it.

I would be interested to hear how other developers model partial AI task failures, provider retries, and idempotent refunds.

How I model scientific claims before generating a diagram

Barry Xiong — Tue, 28 Jul 2026 16:05:57 +0000

A prompt I keep using when I test scientific image models is short: "Draw the MAPK pathway."

That sentence leaves most of the important decisions unstated. Which branch matters? Which cell type are we talking about? Does an arrow mean activation, transport, or simply "this happens next"? Is the figure explaining a known mechanism or summarizing one experiment?

A model can make those missing decisions on its own. The result may look polished and still be scientifically useless.

The picture is the last step

When I started working on text-to-figure generation, I spent most of my time thinking about rendering. Line quality, spacing, color, export size. Within a week, I was spending more time checking arrows than pixels.

The useful intermediate artifact turned out to be a small figure specification. Mine often starts this simply:

{
  "purpose": "Show how MEK inhibition changes downstream ERK signaling",
  "entities": ["MEK", "ERK", "transcription factor"],
  "relations": [
    { "from": "MEK", "to": "ERK", "kind": "activates" }
  ],
  "evidence": "literature plus this experiment",
  "exclude": ["unmeasured branches", "unlisted proteins"]
}

This is not a production schema. It is a quick way to expose decisions before a model hides them under attractive pixels.

If I cannot write the purpose in one sentence, the figure usually has too much work to do. Shrinking the labels will not fix that. I split the figure instead.

Arrows need types

An arrow is one of the easiest shapes to draw and one of the easiest ways to make a false claim.

In a workflow, an arrow may mean sequence. In a pathway, it may mean activation or inhibition. In an equipment diagram, it may mean material flow. Those meanings should not be interchangeable just because they share the same SVG path.

For a developer, the relation deserves its own type:

type Edge = {
  from: string
  to: string
  kind: "activates" | "inhibits" | "transports" | "next-step"
  evidence: "measured" | "literature" | "interpretation"
}

The type does two useful things. It lets the renderer choose a visual convention, and it gives the validator something concrete to inspect. A vague "connect these nodes" instruction gives us neither.

I also keep relation meaning out of color whenever possible. Color disappears in grayscale printing, on poor projectors, and for some readers with color-vision differences. Arrowheads, line styles, and labels carry the meaning. Color can help, but it should not be the only carrier.

Evidence and explanation need different treatment

Scientific papers mix several kinds of visuals. A chart presents measurements. A microscopy image records an observation. A mechanism diagram explains how the author thinks pieces fit together.

The trouble starts when a generated illustration borrows the visual authority of measured data.

A detailed receptor model can imply structural precision that was never measured. A realistic anatomical cutaway can look patient-specific even when it is generic. The more convincing the render, the easier it is to miss that distinction.

I now attach a source category to anything that enters a figure:

measured in the current work
supported by cited literature
interpretation or hypothesis
orientation only

Those categories can change line weight, labels, captions, and citations. They also make review easier. A co-author can disagree with the category without arguing about the entire composition.

For explanatory figures, I often prefer plain line art to a cinematic render. Lower visual detail leaves less room for accidental claims.

My validation loop is deliberately boring

I used to regenerate a figure until one version felt right. That loop rewards appearance. A clean layout can distract me from a wrong connection.

Now I check four things in order:

Is the topology correct?
Do the labels match the paper or source material?
Can I explain what every arrow means?
Is the figure readable at its final size?

A typo is usually a local edit. A topology error sends the figure back to the specification. There is no point tuning shadows on the wrong graph.

The final-size check catches more problems than I expected. A figure that looks comfortable in a full browser window may collapse inside a two-column paper. I test the exported size, not the editor view.

Where generation fits

Generative tools are useful for mechanism sketches, experimental workflows, equipment concepts, and early graphical-abstract drafts. They reduce the cost of getting from an empty canvas to something a team can discuss.

They are a poor substitute for data-driven charts, original microscopy, diagnostic images, or exact chemical structures. Those visuals should come from the underlying data or specialist software. A generated image may explain evidence, but it should not impersonate it.

I eventually built parts of this workflow into Scientific Figure Generator. It can produce line art, flat illustrations, and 3D-style drafts from text. I still treat every result as a draft, including the ones that look finished.

The product question I keep coming back to is how much structure to expose. Too little invites invented relationships. Too much turns a quick visual task into a long form with dozens of fields. I do not think that tradeoff has a universal answer.

For now, my rule is simple: before a generated diagram reaches a paper or presentation, every relationship in it needs a source. If I cannot find one, the figure is not ready.

How are you handling semantic validation when AI generates diagrams in your own tools?

Disclosure: I used an AI writing assistant to help edit the English and tighten this draft. The examples, workflow, and product decisions come from my work building scientific-visualization tools.