How to Use the awesome-gpt-image-2 Library for Prompt Engineering: A Complete Guide

The awesome-gpt-image-2 library combines a React gallery interface, an APIMart API client, and a reusable style-library skill to streamline prompt engineering for GPT-Image-2 generation.

The awesome-gpt-image-2 repository provides a full-stack solution for creating, testing, and refining image generation prompts. Whether you are browsing visual case studies through the web interface or programmatically assembling structured prompts via the agent skill, this toolkit bridges visual exploration with code-driven automation.

Architecture of the Prompt Engineering Stack

The library organizes functionality into three cohesive layers that work together to handle everything from template selection to final image generation.

• UI / Gallery Layer: Handles the presentation of case studies, prompt editing, and test generation workflows. Implemented primarily in [src/main.jsx](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx).
• API Client Layer: Manages communication with the APIMart backend (the official GPT-Image-2 service), including authentication, payload construction, and asynchronous task polling. Implemented in [src/apimartClient.js](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js) and [shared/apimart.js](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js).
• Prompt-Template Skill Layer: Exposes industrial-grade prompt templates as a reusable npm package that integrates with Claude Code and Codex agents. Located in agents/skills/gpt-image-2-style-library/.

Prompt Engineering Flow in the UI

The web interface provides an end-to-end workflow for refining prompts through direct interaction with the APIMart API.

Browsing and Copying Prompts

The gallery loads case data and displays real-world examples with their original prompts. When you click Copy Prompt, the application invokes the copyPrompt() helper (defined around line 94 in [src/main.jsx](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx)) to save the raw prompt string to your clipboard for immediate reuse or modification.

Generating Test Images

After editing a prompt in the Editable Prompt field, you can trigger generation using either submitPersonalGeneration (for users with an APIMart API key) or submitPlatformGeneration (for authenticated platform users). Both functions are exported from [src/apimartClient.js](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js).

The client automatically handles task polling via pollApimartTask() (lines 15-52), which repeatedly queries the APIMart endpoint until the status resolves to completed or failed. Error states—such as rate limiting, insufficient balance, or content moderation flags—are mapped to user-friendly messages through generationErrorMessage in the UI layer.

Payload Construction and Normalization

Behind the scenes, [shared/apimart.js](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js) provides the low-level utilities that make the API client work:

• buildApimartGenerationPayload() (lines 7-19) constructs the JSON body required by APIMart, including the prompt text, aspect ratio, and other parameters.
• normalizeApimartTask() (lines 31-53) transforms the raw API response into a standardized object containing taskId, status, progress, and image URL.

Using the Style-Library Skill for Structured Prompts

Beyond the web UI, the library exposes its prompt engineering expertise as a reusable skill that AI agents can invoke programmatically.

Template Structure and Catalog

The skill sources its knowledge from [data/style-library.json](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json), which contains over 20 industrial-grade templates. Each template defines:

• Metadata: Title, description, use cases, and pitfalls to avoid.
• Taxonomy: Categories, visual styles, scenes, and custom tags for filtering.
• Localization Support: Bilingual definitions (English and Chinese) for global usability.

The Prompt Formatting Engine

The core function formatTemplatePrompt() (located around line 49 in [src/main.jsx](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx)) converts a template object into a production-ready GPT-Image-2 prompt. It assembles a structured instruction block covering:

1. Subject and Scene definition
2. Composition and Style guidelines
3. Text overlay specifications
4. Technical details and Output format requirements
5. Constraints and Avoid lists to prevent common errors

Agent Integration

The skill package includes an agents/openai.yaml file that defines a function interface for Claude Code or Codex agents:

name: generate_gpt_image2_prompt
description: Returns a ready-to-use GPT-Image-2 prompt from a chosen template.
parameters:
  type: object
  properties:
    templateId:
      type: string
      description: ID of the template from the style-library.
  required: [templateId]

When an agent calls this function, the skill runtime (installed via scripts/install-style-skill.mjs) loads the template and executes formatTemplatePrompt(), returning a finalized prompt string that requires no further editing.

Practical Code Examples

Generate an Image with a Personal APIMart Key

To programmatically generate images outside the web UI, use the API client with your personal key:

import {
  submitPersonalGeneration,
  pollApimartTask,
  fetchPersonalTask,
  getStoredApimartKey,
  saveStoredApimartKey
} from './src/apimartClient';

// Store your API key securely
saveStoredApimartKey('sk-your-apimart-key-here');

const apiKey = getStoredApimartKey();
const prompt = 'A futuristic city skyline at sunset, hyper-realistic, 8K';

// Submit the generation task
const { taskId } = await submitPersonalGeneration(prompt, apiKey, 'en');

// Poll until completion
const result = await pollApimartTask(
  () => fetchPersonalTask(taskId, apiKey, 'en')
);

console.log('Generated image URL:', result.image);

Implementation reference: [src/apimartClient.js](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js) (lines 103-122 for submission, lines 15-52 for polling).

Build a Prompt from a Template

To leverage the style library for consistent prompt engineering:

import { formatTemplatePrompt } from './src/main.jsx';
import styleLibrary from './data/style-library.json';

// Select a template by index or ID
const template = styleLibrary.templates[0];

// Generate the prompt in English
const prompt = formatTemplatePrompt(template, 'en', styleLibrary);
console.log(prompt);

Implementation reference: [src/main.jsx](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx) (lines 49-106), [data/style-library.json](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json).

Integrate with an AI Agent

Install the skill locally to enable agent-based prompt generation:

# Run the installation script

npm run install:skill

Then, within a Claude Code or Codex session, invoke the skill:

Use the "gpt-image-2-style-library" skill to generate a prompt for the "city-life-system-map" template.

The agent will receive a fully formatted prompt ready for immediate submission to the GPT-Image-2 model.

Implementation reference: scripts/install-style-skill.mjs, [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).

Key Files and Implementation Details

Understanding these source files is essential for advanced customization:

• [src/apimartClient.js](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js) – High-level API wrapper handling personal key storage, platform authentication, task submission, and polling logic.
• [shared/apimart.js](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js) – Utility functions for payload construction (buildApimartGenerationPayload), task ID extraction, status normalization (normalizeApimartTask), and cost calculation.
• [src/main.jsx](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx) – React 19 application entry point containing the gallery UI, prompt editor, copy utilities, and the formatTemplatePrompt engine.
• agents/skills/gpt-image-2-style-library/ – Complete npm package including package.json, skill manifest, and agent configuration (agents/openai.yaml).
• [data/style-library.json](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json) – Canonical source of prompt templates, category definitions, and localization strings.
• [package.json](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/package.json) – Dependency manifest specifying React 19, Vite build tools, Supabase client, and Stripe integration.

Summary

• The UI layer in [src/main.jsx](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx) provides an interactive environment for browsing cases, copying prompts, and testing generations via real-time APIMart integration.
• The API client layer ([src/apimartClient.js](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js) and [shared/apimart.js](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js)) abstracts credential management, payload formatting, and asynchronous task polling into reusable JavaScript functions.
• The style-library skill packages industrial prompt templates as a distributable npm module, enabling AI agents to perform automated prompt engineering through the formatTemplatePrompt function and standardized YAML interfaces.

Frequently Asked Questions

What is the primary purpose of the awesome-gpt-image-2 library?

The library serves as a comprehensive toolkit for prompt engineering with GPT-Image-2, combining a visual case-study browser, a production-ready API client for the APIMart service, and a reusable skill system for generating structured prompts through AI agents.

How does the style-library skill improve prompt consistency?

The skill enforces consistency by exposing curated templates from [data/style-library.json](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json) through the formatTemplatePrompt function. This ensures every generated prompt includes mandatory sections (Subject, Scene, Style, Constraints) and avoids common pitfalls defined in the template metadata.

Can I use my own APIMart API key with this library?

Yes. The submitPersonalGeneration function in src/apimartClient.js is specifically designed for personal API key authentication. Store your key using saveStoredApimartKey() and pass it to the submission function for direct access to the GPT-Image-2 backend without platform credits.

Where are the prompt templates defined?

All template definitions, categories, and localization mappings reside in [data/style-library.json](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json). The agents/skills/gpt-image-2-style-library/ directory packages these definitions as an installable skill for agent integration.

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