# How APIMart Is Integrated for Image Generation in Awesome‑GPT‑Image‑2

> Discover how Awesome-GPT-Image-2 integrates APIMart for AI image generation using a three-layer architecture for seamless backend operations and efficient image creation.

- Repository: [苍何/awesome-gpt-image-2](https://github.com/freestylefly/awesome-gpt-image-2)
- Tags: how-to-guide
- Published: 2026-09-04

---

**The Awesome‑GPT‑Image‑2 repository integrates APIMart as its core backend for AI image generation through a three‑layer architecture that separates configuration, HTTP client logic, and server‑side orchestration.**

This open‑source project leverages APIMart to transform text prompts into images asynchronously. Understanding how APIMart is integrated for image generation reveals a clean separation of concerns across shared utilities, client wrappers, and serverless API routes that handle quota management and error recovery.

## Three-Layer Architecture for APIMart Integration

The integration follows a deliberate layered design that isolates APIMart‑specific logic from the UI layer. This architecture allows the provider to be swapped or extended without modifying front‑end components.

### Layer 1: Shared Configuration and Utilities

The file [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js) serves as the central source of truth for all APIMart configuration. It exports constants for the **model name**, **base URL**, **pricing tiers**, and **rate limits**, alongside helper functions for building request payloads.

Key utilities include `buildApimartGenerationPayload` for constructing valid request bodies, functions for extracting and normalizing task IDs, and error parsers that translate APIMart responses into canonical internal codes. This consolidated approach ensures that changes to APIMart's API contract require updates in only one location.

### Layer 2: Client-Side API Wrapper

The [`src/apimartClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js) module provides a thin abstraction over the raw APIMart REST API. It exposes three primary functions for personal API key workflows:

- **`verifyPersonalApimartKey`** – Validates that a user‑provided API key is active and authorized.
- **`submitPersonalGeneration`** – Submits a generation request to APIMart and returns a task ID for asynchronous tracking.
- **`pollApimartTask`** – Polls the APIMart endpoint until the task reaches a terminal state (`completed` or `failed`).

This wrapper also manages **local storage** for pending and completed generations, caching task states to reduce redundant network calls. All HTTP errors are normalized using the helpers from [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js) before being returned to callers.

### Layer 3: Server-Side Orchestration Endpoint

The serverless function [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js) acts as the application's entry point for image generation requests. When a user submits a prompt, this endpoint executes a strict workflow:

1. **Configuration Verification** – Calls `getApimartConfig` to confirm the service is properly configured.
2. **Quota Reservation** – Reserves a generation slot in Supabase via `reserveGeneration` to prevent oversubscription.
3. **Task Submission** – Invokes `submitApimartGeneration` (exposed from [`api/_lib/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/apimart.js)), which forwards the request to `src/apimartClient.submitPersonalGeneration`.
4. **Task Tracking** – Stores the returned task ID in the `generation_reservations` table.
5. **Response** – Returns a **202 Accepted** status with the task ID and initial status to the client.

If any step fails, the endpoint maps internal APIMart error codes to public error codes (`publicErrorCode`) and releases the reservation to maintain quota accuracy.

## Server-Side Workflow and Quota Management

The server layer coordinates between the user's request and APIMart's asynchronous infrastructure. Before submitting to APIMart, the system verifies that a generation quota exists via Supabase interactions defined in [`api/_lib/supabase.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/supabase.js).

The `submitApimartGeneration` function bridges the API route and the client wrapper, ensuring that server‑side APIMart keys are used for platform‑managed generations while still supporting personal API key flows through the same interface. This dual‑mode support allows both hosted and bring‑your‑own‑key usage patterns.

## Client-Side Implementation Patterns

### Submitting a Generation Request

When users supply their own APIMart API key, the client invokes the submission flow directly:

```javascript
import { submitPersonalGeneration } from './src/apimartClient.js';
import { buildApimartGenerationPayload } from './shared/apimart.js';

const apiKey = 'sk-...';                // user‑provided API key
const prompt = 'A futuristic cityscape';
const language = 'en';

await submitPersonalGeneration(prompt, apiKey, language);
// → { taskId: 'task_abcdef123456', status: 'submitted' }

```

This function constructs the payload using shared utilities and returns a task ID that the UI can use to track progress.

### Polling for Task Completion

Since APIMart processes images asynchronously, the client must poll until the task completes:

```javascript
import { fetchPersonalTask, pollApimartTask } from './src/apimartClient.js';

const taskId = 'task_abcdef123456';
const apiKey = 'sk-...';

const fetchTask = () => fetchPersonalTask(taskId, apiKey, 'en');
await pollApimartTask(fetchTask, {
  onProgress: task => console.log('Progress:', task.progress),
  maxAttempts: 100,
});

```

The `pollApimartTask` utility handles exponential backoff and provides progress callbacks, abstracting the polling mechanics from the UI components.

### Calling the Server Endpoint

For platform‑managed generations (using the server's APIMart quota), the front‑end calls the Next.js API route:

```javascript
await fetch('/api/generate-image', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ caseId: 42, prompt: 'A cute robot', language: 'en' })
});

```

This returns immediately with a 202 status, allowing the UI to begin polling the task status endpoint while the server manages the APIMart interaction.

## Error Handling and Task Lifecycle

The integration implements comprehensive error mapping at every layer. In [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js), raw APIMart errors are parsed and normalized into canonical codes. The client wrapper ([`src/apimartClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js)) catches HTTP exceptions and enriches them with retry logic.

On the server side, [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js) implements rollback logic: if APIMart returns an error after a quota reservation is made, the endpoint releases the reservation via Supabase before returning the error to the client. This prevents ghost reservations from consuming user quotas during transient APIMart failures.

## Summary

- **Centralized Configuration**: [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js) houses all APIMart constants, pricing, and payload builders, creating a single point of maintenance for API contract changes.
- **Client Abstraction**: [`src/apimartClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js) wraps HTTP interactions, offering key verification, generation submission, and intelligent polling with local storage caching.
- **Server Orchestration**: [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js) handles quota reservation, task submission, and error rollback, returning 202 Accepted for asynchronous processing.
- **Dual-Mode Support**: The architecture supports both server‑managed APIMart keys and user‑provided personal keys through the same interface.
- **Robust Error Handling**: Errors are normalized at the utility layer, caught at the client layer, and trigger reservation rollbacks at the server layer to maintain data consistency.

## Frequently Asked Questions

### What is the role of [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js) in the APIMart integration?

[`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js) acts as the configuration hub and utility library for all APIMart interactions. It exports the base URL, model identifiers, pricing structures, and helper functions like `buildApimartGenerationPayload` that ensure requests conform to APIMart's expected schema. By centralizing these definitions, the file enables consistent error parsing and payload construction across both client and server code.

### How does the server handle quota management before submitting to APIMart?

Before calling APIMart, the server endpoint [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js) reserves a generation slot in Supabase using `reserveGeneration`. This reservation prevents race conditions and oversubscription. If the APIMart submission succeeds, the task ID is stored with the reservation; if it fails, the reservation is released immediately to return the quota to the user.

### What happens if an APIMart generation task fails?

When a task fails, the error propagates through the normalized error codes defined in [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js). The server catches this in [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js), maps it to a `publicErrorCode`, releases any held Supabase reservation to free the quota, and returns the error details to the client. The client can then display the specific failure reason without exposing internal implementation details.

### Can users supply their own APIMart API keys instead of using the server's quota?

Yes. The [`src/apimartClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js) module exposes `submitPersonalGeneration` and `verifyPersonalApimartKey` specifically for users who provide their own API keys. This bypasses the server's Supabase quota system and submits directly to APIMart using the user's credentials, while still utilizing the same payload builders and error handlers from the shared utilities.