Complete Guide to API Endpoints for awesome-gpt-image-2: Reference with Code Examples

The awesome-gpt-image-2 platform exposes REST API endpoints through Vercel serverless functions located in the api/ directory, covering image generation, user management, favorites, billing, and administrative operations.

All API routes in awesome-gpt-image-2 are implemented as JavaScript files in the api/ folder, each exporting a default handler that processes HTTP requests. This architecture enables seamless serverless deployment while maintaining clean separation of concerns across authentication, quota management, and third-party service integrations.

---

Core Image Generation Endpoints

POST /api/generate-image

The primary endpoint for creating AI-generated images. Located in api/generate-image.js, this handler performs quota reservation, calls the external CiiYuan image service, and releases the reservation upon success or failure.

Required parameters:

• prompt — text description of the desired image
• caseId — identifier for the generation case

fetch('/api/generate-image', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ 
    prompt: 'A futuristic city at sunset', 
    caseId: 42 
  })
})
  .then(r => r.json())
  .then(res => {
    if (res.ok) {
      const img = document.createElement('img');
      img.src = res.image;   // data:image/jpeg;base64,...
      document.body.append(img);
    } else {
      console.error('Generation error:', res.error);
    }
  });

The same endpoint supports GET for checking authentication status.

---

User Profile Endpoints

GET /api/me and PATCH /api/me

Implemented in api/me.js, these endpoints handle user profile retrieval and updates. The GET method returns the logged-in user profile enriched with usage statistics and recent credit transactions. The PATCH method accepts fullName (or full_name) to update the display name.

Retrieve current user:

fetch('/api/me')
  .then(r => r.json())
  .then(res => {
    if (res.ok) {
      console.log('User profile:', res.user);
    } else {
      console.warn('Not logged in');
    }
  });

Update display name:

fetch('/api/me', {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ fullName: 'Alex Johnson' })
})
  .then(r => r.json())
  .then(res => console.log(res.ok ? 'Updated' : 'Failed', res));

---

Favorites Management Endpoints

GET, POST, DELETE /api/favorites

The api/favorites.js file implements full CRUD operations for user favorites. All methods require authentication.

Method	Action	Details
GET	List favorites	Returns all saved case IDs for the user
POST	Add favorite	Body requires caseId, validated against data/cases.json
DELETE	Remove favorite	Query parameter caseId specifies which to remove

// Add a favorite
fetch('/api/favorites', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ caseId: 12 })
})
  .then(r => r.json())
  .then(console.log);

// List favorites
fetch('/api/favorites')
  .then(r => r.json())
  .then(res => console.log('Favorites:', res.favorites));

// Remove a favorite
fetch('/api/favorites?caseId=12', { method: 'DELETE' })
  .then(r => r.json())
  .then(console.log);

---

Community Feature Endpoints

Three read-only endpoints support community features in the api/community/ subdirectory:

• GET /api/community/status (status.js) — returns feature availability status including QR code accessibility
• GET /api/community/qr (qr.js) — generates QR code URL pointing to the community page
• GET /api/community/config (config.js) — supplies static frontend configuration values such as social links

---

Billing and Payment Endpoints

The api/billing/ directory contains multiple endpoints handling Stripe and Alipay integrations:

Endpoint	Purpose
api/billing/checkout.js	Initiates payment checkout sessions
api/billing/webhook.js	Receives async payment notifications
api/billing/alipay/checkout.js	Alipay-specific checkout flow
Additional refund and query endpoints	Status checks and refund processing

These routes interact with Supabase RPCs and third-party payment SDKs. The checkout.js handler creates payment sessions, while webhook.js processes asynchronous confirmations from payment providers.

---

Administrative Endpoints

Restricted to super-admin users, endpoints in api/admin/ perform privileged operations:

Endpoint	Function
api/admin/users.js	User management (list, modify, delete accounts)
api/admin/metrics.js	Platform analytics and usage statistics
api/admin/credits/adjust.js	Manual credit balance modifications
api/admin/community/revoke.js	Revoke community access
api/admin/community/refund.js	Process community-related refunds

All admin endpoints verify super-admin status before executing operations against Supabase tables and RPCs.

---

Authentication and Architecture

Shared Infrastructure

Every endpoint in awesome-gpt-image-2 relies on common utilities in api/_lib/:

• api/_lib/supabase.js — central Supabase client for authentication, sessions, and database operations
• getAuthContext function — determines if requests are anonymous or authenticated
• Rate limiting and quota enforcement — implemented via stored procedures including reserve_generation_usage, complete_generation_reservation, and release_generation_reservation

Error Handling Format

All endpoints return uniform JSON error responses:

{ "ok": false, "error": "ERROR_CODE" }

HTTP status codes follow standard conventions: 401 for unauthorized, 402 for payment/quota issues, 500 for server errors.

---

Summary

The API endpoints for awesome-gpt-image-2 are organized into functional groups within the api/ directory:

• Image generation via api/generate-image.js with quota management and CiiYuan API integration
• User profiles via api/me.js supporting read operations and display name updates
• Favorites system via api/favorites.js with full CRUD and case validation
• Community features via api/community/ subdirectory for status, QR codes, and configuration
• Billing infrastructure via api/billing/ with dual Stripe/Alipay support
• Administrative tools via api/admin/ restricted to super-admin access

All endpoints leverage the shared api/_lib/supabase.js client for authentication and database operations, with consistent error formatting and rate limiting through Supabase stored procedures.

---

Frequently Asked Questions

What external services do the API endpoints integrate with?

The API endpoints integrate with Supabase for authentication and data persistence, CiiYuan for AI image generation services, and Stripe/Alipay for payment processing. According to the awesome-gpt-image-2 source code, these integrations are centralized in api/_lib/supabase.js and the respective billing handler files.

Do I need authentication for all API endpoints?

No — some endpoints like GET /api/community/config are publicly accessible. However, image generation (/api/generate-image), user profiles (/api/me), favorites (/api/favorites), and all billing/administrative endpoints require valid authentication. The getAuthContext helper in api/_lib/supabase.js enforces these requirements per endpoint.

How does quota management work for image generation?

Before calling the CiiYuan API, the api/generate-image.js handler calls the reserve_generation_usage Supabase RPC to check and reserve quota. Upon completion or failure, it calls either complete_generation_reservation or releases the reservation, ensuring atomic quota accounting even during external service failures.

Where are the API endpoint files deployed?

All files in the api/ directory deploy as Vercel serverless functions. The vercel.json configuration maps /api/* paths to these handlers automatically. This enables the project to run without maintaining dedicated server infrastructure while scaling individual endpoints independently.

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