# How to Use the GPT-Image2 Prompt Engine: A Complete Technical Guide

> Master the GPT-Image2 prompt engine with this technical guide. Generate images via UI API or NPM agent. Learn to use this full-stack system effectively.

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

---

**The GPT-Image2 prompt engine is a full-stack system that lets you generate images via a React UI, direct API calls, or an NPM agent skill by routing requests through a Vercel serverless function to the CIYUAN service.**

The GPT-Image2 prompt engine, implemented in the `freestylefly/awesome-gpt-image-2` repository, provides a production-ready architecture for generating AI images using curated prompt templates. This system combines a React-based gallery interface, serverless API endpoints, and Supabase-backed authentication to deliver a seamless image generation workflow.

## Architecture of the GPT-Image2 Prompt Engine

The engine consists of three distinct layers working in concert:

- **Front-end UI Layer**: A React application ([`src/main.jsx`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx)) that renders the prompt gallery, handles localization, manages the `AuthModal` component for Google/Watcha sign-ins, and provides copy-to-clipboard functionality for prompt templates.

- **API Gateway Layer**: Vercel serverless functions ([`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js)) that validate incoming requests, reserve user credits via Supabase RPCs, and proxy calls to the external GPT-Image2 service.

- **Data & Authentication Layer**: Supabase handles user sessions ([`src/supabaseClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/supabaseClient.js)), credit tracking, and profile management ([`api/_lib/supabase.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/supabase.js)), while a JSON style library ([`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json)) drives the prompt categorization system.

## Request Flow and Authentication

When a user initiates image generation, the system executes this validated workflow:

1. **Authentication**: The user signs in via Google or Watcha through the `AuthModal` component in [`src/main.jsx`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx), creating a Supabase session stored as a cookie.

2. **Request Submission**: The frontend sends a POST request to `/api/generate-image` containing the JSON payload `{ prompt, caseId }`.

3. **Credit Reservation**: The API handler checks `isServerConfigured`, then calls `reserveGeneration` (or `reserveCreditGeneration` for super-admins) to lock a credit quota from the user's balance.

4. **Image Generation**: The `generateImage` function contacts `https://ciyuan.today/v1/images/generations` with the prompt parameters and receives a base64-encoded JPEG response.

5. **Response Delivery**: Upon successful generation, the reservation is finalized and the API returns the image data-URL alongside the updated user profile, including remaining `creditBalance` and `freeGenerationsUsed` counts.

## Methods to Generate Images

You can interact with the GPT-Image2 prompt engine through three primary interfaces:

### Web UI (React Frontend)

Visit the live deployment at `https://gpt-image2.canghe.ai/` to browse the curated gallery. Click "Copy Prompt" to capture a template, edit the text as needed, then click "Generate Image" to trigger the workflow. The UI handles all authentication and credit management automatically through the Supabase client initialized in [`src/supabaseClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/supabaseClient.js).

### Direct API Integration

For programmatic access, send authenticated POST requests to the `/api/generate-image` endpoint. You must include a valid Supabase session cookie or JWT token in the headers. This method bypasses the React frontend and communicates directly with the serverless handler in [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js).

### Agent Skill (NPM Package)

Install the `gpt-image-2-style-library` package to invoke the engine from within AI agent environments like Claude Code or Codex. This skill reads the same [`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json) catalog used by the web interface, ensuring consistency across platforms.

## Code Examples

### Generate Images via API (cURL)

Send a POST request with your Supabase session cookie:

```bash
curl -X POST https://gpt-image2.canghe.ai/api/generate-image \
  -H "Content-Type: application/json" \
  -H "Cookie: <your-supabase-session-cookie>" \
  -d '{
        "prompt": "A futuristic city skyline at sunset, ultra-realistic, 8k resolution",
        "caseId": 123
      }'

```

The endpoint returns a JSON payload:

```json
{
  "ok": true,
  "image": "data:image/jpeg;base64,...",
  "user": {
    "creditBalance": 9,
    "freeGenerationsUsed": 1
  }
}

```

This response format is defined in [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js), which parses the CIYUAN service response and wraps it with user metadata retrieved via `getProfileById`.

### Call CIYUAN Service Directly (Node.js)

To bypass the credit reservation system and call the underlying service directly, use this implementation mirroring the `generateImage` function:

```javascript
import fetch from 'node-fetch';

const CIYUAN_BASE_URL = process.env.CIYUAN_BASE_URL || 'https://ciyuan.today';
const CIYUAN_API_KEY = process.env.CIYUAN_API_KEY;

async function generateImage(prompt) {
  const response = await fetch(`${CIYUAN_BASE_URL}/v1/images/generations`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${CIYUAN_API_KEY}`,
      'Content-Type': 'application/json',
      Accept: 'application/json',
    },
    body: JSON.stringify({
      model: 'gpt-image-2',
      prompt,
      n: 1,
      size: '1024x1024',
      quality: 'low',
      format: 'jpeg',
    }),
  });
  
  const { data } = await response.json();
  return `data:image/jpeg;base64,${data[0].b64_json}`;
}

generateImage('A vintage travel-ticket postcard of Rio')
  .then(console.log)
  .catch(console.error);

```

Note that direct CIYUAN integration requires managing your own API credentials and does not interact with the Supabase credit system defined in [`api/_lib/supabase.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/supabase.js).

### Using the Agent Skill

Install the skill globally for your AI agent:

```bash
npx skills add freestylefly/awesome-gpt-image-2 --skill gpt-image-2-style-library --agent claude-code --global --yes --copy

```

Within a Claude Code session, activate the skill:

```bash
/plugin marketplace add freestylefly/awesome-gpt-image-2
/plugin install gpt-image-2-style-library@awesome-gpt-image-2

```

Then generate prompts using the style library:

```

Use gpt-image-2-style-library to create an infographic prompt about Codex.

```

The skill queries [`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json) to construct prompts matching the site's curated templates.

## Key Implementation Files

Understanding these core files is essential for customizing or debugging the GPT-Image2 prompt engine:

- **[`src/main.jsx`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx)**: React entry point containing UI components, localization logic, and the `AuthModal` implementation.

- **[`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js)**: Serverless function handling request validation, credit reservation via `reserveGeneration`, and CIYUAN service proxying.

- **[`src/supabaseClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/supabaseClient.js)**: Client-side Supabase initialization for authentication and database queries.

- **[`api/_lib/supabase.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/supabase.js)**: Server-side helpers including `getAuthContext` and `getProfileById` for session validation and user data retrieval.

- **[`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json)**: Structured catalog of prompt categories, styles, and tags shared between the web UI and agent skill.

- **[`agents/skills/gpt-image-2-style-library/SKILL.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/agents/skills/gpt-image-2-style-library/SKILL.md)**: Documentation for the NPM skill package.

## Summary

- The GPT-Image2 prompt engine uses a three-tier architecture: React frontend, Vercel serverless API, and Supabase backend.
- Authentication requires Supabase sessions (Google/Watcha OAuth) tracked via cookies and validated in [`api/_lib/supabase.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/supabase.js).
- Credit management uses `reserveGeneration` RPC calls to lock quotas before calling the CIYUAN generation endpoint.
- You can access the system via the web UI, direct API calls to `/api/generate-image`, or the `gpt-image-2-style-library` NPM package.
- The style library in [`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json) provides the curated prompt templates used across all interfaces.

## Frequently Asked Questions

### What authentication is required to use the GPT-Image2 prompt engine?

The engine requires Supabase authentication via Google or Watcha OAuth, handled by the `AuthModal` component in [`src/main.jsx`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx). The API endpoints validate sessions using `getAuthContext` from [`api/_lib/supabase.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/supabase.js), rejecting unauthorized requests before credit reservation occurs.

### How does credit reservation work in the GPT-Image2 system?

When a request hits [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js), the system calls `reserveGeneration` (or `reserveCreditGeneration` for super-admins) to atomically deduct a credit from the user's balance stored in Supabase. This reservation locks the quota before the expensive CIYUAN API call, preventing race conditions and ensuring accurate billing.

### Can I use the GPT-Image2 prompt engine without the web interface?

Yes. You can call the `/api/generate-image` endpoint directly with a valid Supabase session cookie, or bypass the credit system entirely by calling the CIYUAN service directly using the Node.js pattern shown in [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js). The `gpt-image-2-style-library` NPM package also provides programmatic access to the prompt templates.

### Where is the style library data stored?

The curated prompt templates and metadata reside in [`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json) at the repository root. This JSON file contains categorized styles, scenes, and tags that both the React UI and the agent skill consume to ensure consistent prompt engineering across platforms.