# How the awesome-gpt-image-2 Backend API Works: A Complete Technical Guide

> Explore the awesome-gpt-image-2 backend API. Learn how this serverless Next.js app handles AI image generation, authentication, and payments with Supabase and Apimart.

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

---

**The awesome-gpt-image-2 backend API is a serverless Next.js application that orchestrates AI image generation, user authentication, and payment processing through RESTful endpoints in the `api/` directory, leveraging Supabase for data persistence and Apimart for image generation.**

This repository implements a production-ready backend architecture using Next.js API routes deployed as serverless functions. The system coordinates external services including Supabase for database operations, Apimart for AI image generation, and multiple payment providers to deliver a complete image generation platform.

## Architecture Overview

The backend follows a **serverless function architecture** where each file in the `api/` directory represents an independent HTTP endpoint. This design pattern separates concerns into distinct routes: authentication handlers, generation pipelines, billing webhooks, and administrative tools. All routes share common utilities centralized in `api/_lib/` to ensure consistent database connections, error handling, and external service integrations.

## Core API Routes and Functionality

### User Authentication and Profile Management

The authentication layer handles OAuth flows and session management through three primary endpoints:

- **[`api/me.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/me.js)** – Retrieves the current authenticated user's profile using the Supabase session
- **[`api/auth/watcha/start.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/auth/watcha/start.js)** – Initiates the Watcha OAuth flow by generating the authorization URL
- **[`api/auth/watcha/callback.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/auth/watcha/callback.js)** – Processes the OAuth callback from Watcha, exchanges the code for tokens, and establishes the user session

The authentication system relies on [`api/_lib/supabase.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/supabase.js) to validate session cookies and retrieve the current `user.id` for permission enforcement across protected routes.

### Image Generation Pipeline

The core functionality centers on asynchronous image generation through a three-endpoint workflow:

**[`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js)** accepts POST requests containing prompts, image sizes, and model selections. This endpoint:
1. Validates the user's authentication via [`api/_lib/supabase.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/supabase.js)
2. Forwards the generation request to [`api/_lib/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/apimart.js) (the external AI service wrapper)
3. Creates a job record in Supabase via [`api/_lib/generation.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/generation.js)
4. Returns a job ID for client-side polling

**[`api/generation/status.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generation/status.js)** handles GET requests to check the current state of a generation job by querying the Supabase database for the associated metadata and status.

**[`api/generation/callback.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generation/callback.js)** serves as a webhook receiver that accepts asynchronous updates from the Apimart service when image generation completes, updating the job record with the final image URL.

### Favorites and Community Features

User content management operates through **[`api/favorites.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/favorites.js)**, which provides CRUD operations for saved images. This endpoint validates the session cookie, then performs database operations to add or remove images from the user's favorites collection.

Community-related functionality resides in `api/community/*`, handling QR-code generation, status endpoints, and Alipay integration for community transactions.

### Billing and Subscription Management

The payment infrastructure under `api/billing/*` supports dual payment processors:

- **Stripe integration** – Handles subscription creation, customer portal management, and checkout sessions
- **Alipay integration** – Processes Chinese payment flows through [`api/billing/alipay/notify.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/billing/alipay/notify.js), which validates signatures and updates user credit balances

The [`api/_lib/billing.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/billing.js) helper centralizes credit adjustment logic, while [`api/_lib/alipay.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/alipay.js) manages SDK interactions and signature verification for webhook security.

### Administrative Endpoints

Administrative oversight is provided by `api/admin/*` routes, including:
- **[`api/admin/users.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/admin/users.js)** – Lists and manages user accounts
- **[`api/admin/metrics.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/admin/metrics.js)** – Retrieves platform usage statistics
- Credit adjustment endpoints for manual balance corrections
- Community refund management tools

## Shared Utility Libraries (`api/_lib`)

The `api/_lib/` directory contains service wrappers that abstract external dependencies:

- **[`api/_lib/supabase.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/supabase.js)** – Creates authenticated Supabase clients using request cookies, enabling row-level security and user identification
- **[`api/_lib/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/apimart.js)** – Wraps the external image-generation API with retry logic and error normalization
- **[`api/_lib/generation.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/generation.js)** – Manages job lifecycle states, metadata persistence, and polling coordination
- **[`api/_lib/watcha.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/watcha.js)** – Handles OAuth token exchange and user profile retrieval from the Watcha service
- **[`api/_lib/alipay.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/alipay.js)** – Builds payment requests and verifies webhook signatures using Alipay's SDK
- **[`api/_lib/ga4.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/ga4.js)** – Tracks events to Google Analytics for usage monitoring

## Request Lifecycle and Data Flow

Every request traverses a standardized pipeline:

1. **Request Entry** – Client sends HTTP request to `/api/[route]`
2. **Auth & Session** – Route imports [`api/_lib/supabase.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/supabase.js) to validate cookies and extract `user.id`
3. **Business Logic** – Handler invokes specialized libraries (e.g., [`api/_lib/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/apimart.js) for generation)
4. **External Services** – Libraries communicate with Apimart, Supabase, or payment processors
5. **Response** – Endpoint returns JSON payloads or HTTP redirects; long-running jobs utilize the status endpoint or webhook callbacks for async updates

## Practical API Usage Examples

Generate a new image using the generation endpoint:

```bash
curl -X POST https://your-domain.com/api/generate-image \
  -H "Content-Type: application/json" \
  -d '{
        "prompt": "A futuristic cityscape at sunset",
        "size": "1024x1024",
        "model": "stable-diffusion-v2"
      }'

```

Check the status of an asynchronous generation job:

```bash
curl https://your-domain.com/api/generation/status?id=12345

```

Add an image to the authenticated user's favorites:

```bash
curl -X POST https://your-domain.com/api/favorites \
  -H "Content-Type: application/json" \
  -d '{"imageId":"12345"}' \
  -b "next-auth.session-token=YOUR_SESSION_COOKIE"

```

Initiate the Watcha OAuth authentication flow:

```bash
curl https://your-domain.com/api/auth/watcha/start

```

Process an Alipay payment webhook (payload structure):

```json
{
  "out_trade_no": "order_9876",
  "trade_status": "TRADE_SUCCESS",
  "total_amount": "9.99"
}

```

The webhook endpoint [`api/billing/alipay/notify.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/billing/alipay/notify.js) validates this payload, updates the user's credit balance via [`api/_lib/billing.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/billing.js), and returns a `200 OK` response.

## Summary

- **Serverless Architecture** – Each `api/` file represents an independent Next.js API route handling specific functionality
- **External Integrations** – Apimart powers AI generation, Supabase manages persistence, and Stripe/Alipay handle payments
- **Async Workflow** – Image generation uses a polling/status endpoint pattern plus webhooks ([`api/generation/callback.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generation/callback.js)) for completion notifications
- **Modular Libraries** – `api/_lib/` utilities centralize database connections, payment processing, and OAuth flows
- **Security** – Session validation via Supabase cookies enforces authentication across all protected endpoints

## Frequently Asked Questions

### What technology stack powers the awesome-gpt-image-2 backend API?

The backend is built on **Next.js API routes** running as serverless functions, with **Supabase** providing PostgreSQL database functionality and real-time subscriptions. External AI capabilities come from the **Apimart** image generation service, while payment processing supports both **Stripe** (international) and **Alipay** (Chinese markets). All authentication relies on Supabase Auth with cookie-based session management.

### How does the image generation workflow handle asynchronous processing?

When a client posts to [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js), the system immediately returns a job ID while delegating the actual generation to Apimart via [`api/_lib/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/apimart.js). Clients poll [`api/generation/status.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generation/status.js) to check progress, or the system receives webhook notifications at [`api/generation/callback.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generation/callback.js) when Apimart completes the task. The [`api/_lib/generation.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/generation.js) utility tracks all job states in Supabase, bridging the gap between the synchronous API and the asynchronous AI service.

### Which payment providers are supported by the billing system?

The billing module supports **Stripe** for credit card subscriptions and customer portal management, plus **Alipay** for Chinese payment processing. The [`api/billing/checkout.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/billing/checkout.js) route creates payment sessions for both providers, while [`api/billing/alipay/notify.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/billing/alipay/notify.js) handles Alipay's asynchronous webhook notifications. Credit balances are managed atomically through [`api/_lib/billing.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/billing.js) to prevent race conditions during concurrent top-ups.

### How is user authentication implemented across endpoints?

All protected routes import [`api/_lib/supabase.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/supabase.js) to create an authenticated Supabase client using the request's session cookie. This client provides the current `user.id` and enforces row-level security policies defined in Supabase. For OAuth flows, [`api/_lib/watcha.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/watcha.js) manages the token exchange, while the standard email/password or magic link flows use Supabase Auth's native methods.