# How the GPT-Image2 Reservation System Works for Image Generation

> Understand the GPT-Image2 reservation system for image generation. Learn how it ensures idempotent processing with Supabase reservations and provider callbacks.

- Repository: [苍何/awesome-gpt-image-2](https://github.com/freestylefly/awesome-gpt-image-2)
- Tags: architecture
- Published: 2026-09-11

---

**The GPT-Image2 reservation system creates a unique database slot for every image generation request, ensuring idempotent processing by tracking the request from pending through completion or failure via Supabase reservations and provider callbacks.**

The `freestylefly/awesome-gpt-image-2` repository implements a robust **reservation system for GPT-Image2 image generation** that guarantees reliable task tracking and prevents duplicate processing. This architecture uses Supabase as the persistence layer and implements a state machine that transitions reservations from `pending` to `succeeded` or `failed` based on external provider responses.

## Creating a Generation Reservation

When a client initiates image generation via **`POST /api/generate-image`**, the handler defined in [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js) immediately inserts a row into the Supabase table `generation_reservations`. This record establishes a unique slot with `status = 'pending'` and `provider = 'apimart'`, returning a `reservation_id` to the caller before any external processing begins.

If the database insertion fails, the handler throws `RESERVATION_FAILED`, ensuring the client receives an immediate error rather than a lost request:

```javascript
// src: api/generate-image.js (lines 27-48)
const reservation = normalizeReservation(data);
if (!reservation) throw new Error('RESERVATION_FAILED');
return reservation;

```

## Reserving the Task with Metadata

The internal helper **`reserveGeneration`** (called from [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js)) persists the reservation ID alongside metadata required for the provider. This reservation ID serves as the correlation key that later matches the provider's asynchronous callback to the original client request, ensuring every generation task maintains a persistent identity throughout its lifecycle.

## Handling Provider Callbacks

When the external provider (Apimart) completes image rendering, it POSTs to **`/api/generation/callback`**. The handler in [`api/generation/callback.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generation/callback.js) uses **`findReservation`** to locate the pending record and validates its state before proceeding:

```javascript
// src: api/generation/callback.js (lines 29-38)
const reservation = await findReservation(client, taskId);
if (!reservation) return { state: 'ignored' };
if (reservation.status !== 'pending') return { state: 'duplicate' };
await settle(client, reservation, verifiedTask);

```

This validation prevents processing duplicate callbacks or updating already-settled reservations.

## Settlement Logic and State Transitions

The core settlement logic resides in **`settlePlatformGeneration`** within [`api/_lib/generation.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/generation.js). This function updates the reservation with provider result fields (`provider_cost_usd`, `provider_result_url`) and executes database RPC calls to finalize the state:

- **Successful completion**: Calls `complete_generation_reservation` to mark the reservation as `succeeded`
- **Failure handling**: Calls `release_generation_reservation` with an error code to transition to `failed`

```javascript
// src: api/_lib/generation.js (lines 60-84)
if (task.status === 'completed' && task.image) {
  await client.rpc('complete_generation_reservation', { p_reservation_id: reservation.id });
} else {
  await client.rpc('release_generation_reservation', {
    p_reservation_id: reservation.id,
    p_error_code: task.errorCode || 'GENERATION_FAILED'
  });
}

```

## Querying Generation Status

Clients poll **`GET /api/generation/status/:taskId`** to retrieve results. The handler uses **`findPlatformGeneration`** to fetch the reservation from Supabase, then formats a public-safe response using **`formatStoredGeneration`**:

```javascript
// src: api/_lib/generation.js (lines 29-45)
export function formatStoredGeneration(reservation) {
  if (!reservation) return null;
  const succeeded = reservation.status === 'succeeded';
  const failed    = reservation.status === 'failed';
  if (!succeeded && !failed) return null;
  return {
    taskId: reservation.provider_task_id,
    status: succeeded ? 'completed' : 'failed',
    image: reservation.provider_result_url || '',
    // …
  };
}

```

## Idempotency and Error Handling

The system guarantees exactly-once semantics through multiple defensive mechanisms:

- **Pending-state validation**: `settlePlatformGeneration` verifies the reservation status remains `pending` before updating, preventing race conditions during concurrent callback processing
- **Idempotent release**: The `release_generation_reservation` RPC is designed to be idempotent, ensuring failed tasks release the reservation exactly once regardless of retry attempts
- **Duplicate detection**: The callback handler returns `{ state: 'duplicate' }` when encountering reservations already processed

## Complete Client Implementation Example

Below is a complete client-side implementation demonstrating reservation creation, polling, and result retrieval:

```javascript
// 1️⃣ Request a new image (client side)
fetch('/api/generate-image', {
  method: 'POST',
  body: JSON.stringify({ prompt: 'a futuristic city at sunset' })
})
  .then(r => r.json())
  .then(({ reservationId }) => {
    console.log('Reservation created:', reservationId);
    // 2️⃣ Poll for status
    const poll = setInterval(() => {
      fetch(`/api/generation/status/${reservationId}`)
        .then(r => r.json())
        .then(data => {
          if (data.status === 'completed') {
            clearInterval(poll);
            console.log('Image ready:', data.image);
          } else if (data.status === 'failed') {
            clearInterval(poll);
            console.error('Generation failed:', data.errorMessage);
          }
        });
    }, 3000);
  });

```

## Summary

- **Unique slot guarantee**: Every `POST /api/generate-image` creates a distinct row in `generation_reservations` with `status = 'pending'` before external processing begins
- **State machine tracking**: Reservations transition through `pending` → `succeeded`/`failed` via `complete_generation_reservation` or `release_generation_reservation` RPC calls
- **Safe callback handling**: The [`api/generation/callback.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generation/callback.js) handler validates reservation state before calling `settlePlatformGeneration` to prevent duplicate processing
- **Idempotent settlement**: Core functions in [`api/_lib/generation.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/generation.js) ensure exactly-once execution regardless of provider retry behavior
- **Clean API surface**: Clients interact via standard REST endpoints while internal implementation details remain encapsulated in library functions

## Frequently Asked Questions

### What happens if the provider callback fails or times out?

The reservation remains in `pending` status indefinitely until a successful callback occurs or manual intervention occurs. Clients should implement polling timeouts at the application level, as the `GET /api/generation/status/:taskId` endpoint (implemented in [`api/generation/status.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generation/status.js)) only returns results once the reservation reaches a terminal state via `formatStoredGeneration`.

### How does the system prevent duplicate image generation charges?

The `settlePlatformGeneration` function in [`api/_lib/generation.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/generation.js) checks that the reservation status is strictly `pending` before invoking `complete_generation_reservation`. If a duplicate callback arrives after settlement, the handler in [`api/generation/callback.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generation/callback.js) returns `{ state: 'duplicate' }` and ignores the payload, ensuring providers cannot bill for the same reservation twice.

### What database tables does the reservation system use?

The system primarily uses the **`generation_reservations`** table in Supabase, which stores fields including `reservation_id`, `provider_task_id`, `status`, `provider`, `provider_cost_usd`, and `provider_result_url`. State transitions occur through RPC functions `complete_generation_reservation` and `release_generation_reservation` rather than direct table updates.

### Can I use a different provider instead of Apimart?

While the current implementation in [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js) hardcodes `provider = 'apimart'`, the architecture supports provider abstraction. The `provider` field in the reservation record and the callback handler's use of `provider_task_id` allow for future extension, though you would need to modify the provider-specific logic in [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js) and the callback verification in [`api/generation/callback.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generation/callback.js) to integrate alternative services.