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

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) 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) 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), credit tracking, and profile management (api/_lib/supabase.js), while a JSON style library (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, 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.

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.

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 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:

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:

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

This response format is defined in 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:

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.

Using the Agent Skill

Install the skill globally for your AI agent:

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:

/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 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: React entry point containing UI components, localization logic, and the AuthModal implementation.

• api/generate-image.js: Serverless function handling request validation, credit reservation via reserveGeneration, and CIYUAN service proxying.

• src/supabaseClient.js: Client-side Supabase initialization for authentication and database queries.

• api/_lib/supabase.js: Server-side helpers including getAuthContext and getProfileById for session validation and user data retrieval.

• 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: 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.
• 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 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. The API endpoints validate sessions using getAuthContext from 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, 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}