# OpenRouter Image Responses: Handle URLs Without Breaking Base64 Clients

Migrate OpenRouter image response handling for optional URLs, expiry timestamps and base64 fallbacks without regenerating successful images unnecessarily.

By Paras Madan | 2026-11-20


An image-generation request can succeed while your application still fails to display the result. OpenRouter's November 19 schema change makes that distinction worth checking: clients can no longer treat every image response as a guaranteed base64 payload.

This is a response-handling migration, not a reason to replace your image model or regenerate your asset library. The first step is finding the code that turns a successful API response into a usable image.

## What changed, and what did not

The [OpenRouter API changelog](https://openrouter.ai/docs/changelog) marks removal of the required `b64_json` property from `ImageGenerationResponse.data` as an action-required change for `POST /images`. It also adds request `response_format`, image `url` fields and a response-level `expires_at` timestamp.

That does not mean base64 output has disappeared. Nor does it mean every existing request now returns a URL. A schema field becoming optional and a default changing are different events, and conflating them can create unnecessary migration work.

Start by listing direct callers of `/api/v1/images`, generated response types, validators and any code that immediately decodes `data[0].b64_json`. Include background workers as well as the interactive preview. A webpage can work while a scheduled export still assumes the older shape.

## Keep the default if it fits your application

The [image endpoint reference](https://openrouter.ai/docs/api/api-reference/images/generate-an-image) says `b64_json` remains the default. Setting `response_format` to `url` requests a signed download link instead. URLs expire up to 24 hours after storage; `expires_at` is the earliest expiry across returned URLs. The stored copy is deleted through the storage lifecycle within the following day.

URL requests can fall back to base64 for streaming responses, zero-data-retention requests or endpoints, and unavailable storage. A URL is a bearer link, so possession permits downloading until expiry.

For an application that already decodes and stores image bytes reliably, I would keep base64 during the initial client update. Introduce URL delivery as a separate rollout. That separates two questions: whether your parser accepts the new schema, and whether your asset workflow benefits from another download step.

Do not change both the delivery format and the image model in the same release. Otherwise, a failed preview leaves you investigating transport, decoding and generation behavior at once.

## Normalize each returned item

Treat the response as an input to your own asset pipeline rather than the application's permanent image record. One possible normalization layer is:

```typescript
type ImageItem = { b64_json?: string; url?: string };
type ImageSource =
  | { kind: "inline"; base64: string }
  | { kind: "download"; url: string; expiresAt: number };

function normalizeImage(
  item: ImageItem,
  expiresAt?: number
): ImageSource {
  if (item.b64_json) {
    return { kind: "inline", base64: item.b64_json };
  }
  if (item.url && typeof expiresAt === "number") {
    return { kind: "download", url: item.url, expiresAt };
  }
  throw new Error("Image response has no usable asset source");
}
```

This example deliberately fails an incomplete URL record instead of guessing an expiry. Call it for every returned image, passing the response-level timestamp. Keep decoding, downloading and durable storage in separate functions so each failure has a clear owner.

The normalizer should not generate another image. Its job ends at identifying a usable source or reporting why it could not.

## Separate generation from asset ingestion

Consider a proposed thumbnail workflow. A generation worker receives the result, an ingestion worker saves the bytes, and a publishing worker references your saved asset. Give those stages separate statuses, such as `generated`, `stored` and `published`.

If ingestion fails, retry ingestion while the source remains usable. Automatically repeating generation can add cost and produce a different thumbnail, even though the first generation was successful.

For URL delivery, prioritize the download before the recorded expiry. Once the asset is stored, use your own asset identifier in publication records rather than depending on the temporary link. If you intentionally keep only temporary previews, make that product choice visible to the user before the preview disappears.

## Test fallback and delayed work explicitly

Build fixtures for an inline image, a URL with an expiry, an already-expired URL and an item containing neither field. Also cover a URL-requested response that contains base64. The requested format should not be the only thing determining how your client reads the result.

Run the same fixtures through the preview screen and export worker. Check that a decoding failure is not labeled a generation failure, and that an expired source produces a recovery message rather than a blank published image.

For a batch publishing system, pause the ingestion worker in a non-production test and resume it later. This exposes assumptions about immediate processing that a fast manual preview would miss.

## Roll out with two useful counters

Track successful generations separately from successfully stored assets. Add a count of responses handled through each delivery path so unexpected fallbacks become visible without being treated as failures automatically.

The migration is complete when both supported shapes reach the same durable asset workflow, delayed jobs handle expiry deliberately, and a display problem cannot silently trigger another paid generation.

I'm Paras. I work at the intersection of AI, engineering and distribution.

I help AI teams explain technical products through clear documentation, practical guides and developer-focused content.

[Book a 30-minute call](https://cal.com/paras-madan/30min).
