How to Generate Historical and Classical Themes with GPT-Image2: A Complete API Guide

To generate historical and classical themes with GPT-Image2, use the history-classical-themes template from data/style-library.json, reference a specific case ID (e.g., 375 or 338), and POST your prompt to the /api/generate-image endpoint to receive a base-64 encoded JPEG.

The freestylefly/awesome-gpt-image-2 repository provides a dedicated History & Classical Themes prompt family designed to encode conventions for ancient Chinese and classical visual styles. By leveraging the structured templates in the style library and the provided Vercel API endpoint, developers can programmatically generate historically accurate imagery with period-specific vocabulary and layout controls.

Understanding the History & Classical Themes Template

GPT-Image2 organizes visual styles into discrete prompt families stored in data/style-library.json. The History & Classical Themes entry (lines 738–764) defines the constraints, tags, and reference cases needed to anchor the model to historical aesthetics.

According to the source code, this template includes:

• Tags: History, Classical, and Scroll (lines 749–751) to focus generation on period-accurate visuals.
• Scenes: History and Story fields (lines 749–751) that encourage narrative depth in the composition.
• Guidance: Explicit instructions to "Specify dynasty, clothing system, object references" (lines 755–756) and to "Use scroll, album page, or poster format deliberately" (lines 755–756).
• Pitfalls: Warnings against "mixing dynasties" and "random modern props" (lines 759–760).

Required API Parameters

To successfully generate historical images, the request body must include two critical fields that the api/generate-image.js handler validates (lines 27–34).

The Prompt Field

The prompt parameter contains the full textual description of your scene. For historical accuracy, this should include the dynasty, clothing details, material references, and artistic format (e.g., ink-wash, scroll).

The Case ID Anchor

The caseId parameter is a numeric reference to a specific example case from the gallery (e.g., 375 or 338). According to the style library (lines 738–762), this ID anchors the model to the historic style-specific vocabulary and layout patterns, ensuring the output adheres to the template's conventions rather than generic generation.

Implementation: Calling the Generation Endpoint

The generation flow runs through api/generate-image.js, a Vercel serverless function that validates credentials, reserves credit usage (lines 27–34), forwards the request to the upstream Ciyuan GPT-Image2 service, and returns the result (lines 59–66). On success, the endpoint returns a JSON object with the structure { ok: true, image: "data:image/jpeg;base64,…", user: … }.

The following JavaScript example demonstrates how to call this endpoint from a browser or Node.js environment:

async function generateHistoricalImage(prompt, caseId) {
  const response = await fetch('/api/generate-image', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ prompt, caseId })
  });

  const result = await response.json();
  if (!result.ok) throw new Error(result.error);
  return result.image; // data:image/jpeg;base64,...
}

// Usage
const prompt = `
  Tang dynasty palace garden at night, moonlight reflecting on a pond,
  scholars in silk hanfu reading poetry on a stone bench,
  delicate willow branches swaying, traditional ink‑wash style,
  no modern elements, scroll format.
`;
generateHistoricalImage(prompt.trim(), 375)   // 375 = “History & Classical Themes” example case
  .then(imgSrc => document.getElementById('out').src = imgSrc)
  .catch(err => console.error(err));

Crafting Historically Accurate Prompts

To maximize fidelity when you generate historical and classical themes with GPT-Image2, structure your prompts according to the template's specific guidance.

Specify Dynasty and Period

Explicitly name the era (e.g., Tang dynasty, Ming period) at the beginning of your prompt. The template guidance stresses that specifying the dynasty maintains visual coherence and prevents anachronistic blending.

Detail Clothing and Props

List traditional garments, accessories, and materials (e.g., silk hanfu with embroidered collar, jade pendant, bamboo scroll). The style library's tags ensure the model prioritizes period-accurate attire over modern approximations.

Select Composition Format

Choose a format that matches your intended output: scroll for vertical hanging compositions, album page for book-style layouts, or poster for framed scenes. The template explicitly recommends deliberate format selection (lines 755–756) to control the aspect ratio and framing.

Apply Negative Constraints

Exclude modern objects explicitly (e.g., no smartphones, no cars, no electric lights). The pitfalls section (lines 759–760) warns that the model may inject random modern props unless explicitly constrained.

Establish Scene and Mood

Add poetic or storytelling cues (e.g., a moonlit garden with a scholar reading poetry) to leverage the Story scene type defined in the template. This encourages the model to compose narrative depth rather than isolated portraits.

Alternative: Using the Agent Skill

For developers using Claude-Code or Cursor, the repository provides a packaged skill at agents/skills/gpt-image-2-style-library/SKILL.md that abstracts the API calls. This skill looks up the History & Classical Themes template by ID (history-classical-themes) and automatically injects the appropriate tags and styles.

Install and use the skill as follows:

# Install the skill (once)

npx skills add freestylefly/awesome-gpt-image-2 --skill gpt-image-2-style-library --global --yes

# In a Claude‑Code session

Use gpt-image-2-style-library to create an illustration of a Ming‑era imperial banquet
with lanterns, silk robes, and a scroll‑style layout.

Summary

• The history-classical-themes template in data/style-library.json (lines 738–764) provides the structured constraints needed for ancient Chinese and classical visual styles.
• Valid caseId values (e.g., 375, 338) anchor the generation to specific historical reference cases defined in the style library.
• The api/generate-image.js endpoint validates requests, forwards them to the GPT-Image2 service, and returns base-64 JPEG data.
• Effective prompts specify dynasty, detail period-accurate clothing, declare a composition format (scroll/album/poster), and explicitly exclude modern objects.
• The gpt-image-2-style-library skill offers a natural-language interface for agent-based workflows.

Frequently Asked Questions

What is the correct case ID for History & Classical Themes in GPT-Image2?

According to the style library definition in data/style-library.json (lines 738–762), reference case IDs 375 and 338 are associated with the History & Classical Themes template. Passing these values in the caseId parameter ensures the model uses the correct historical vocabulary and layout patterns.

How does the API handle credit usage and validation?

The api/generate-image.js function validates the incoming JSON body (lines 27–34) to ensure both prompt and caseId are present. It then reserves a credit usage quota before forwarding the request to the upstream Ciyuan GPT-Image2 service (lines 59–66). If validation fails or credits are exhausted, the function returns an error before reaching the generation stage.

Can I use HTML to display the generated image directly?

Yes. The API returns a data URI in the image field with the format data:image/jpeg;base64,…. You can assign this string directly to the src attribute of an HTML <img> tag or use it as the source for canvas rendering without additional decoding steps.

Where can I find human-readable documentation for these templates?

The repository includes docs/templates.md, which expands the JSON entries from data/style-library.json into markdown documentation. This file provides detailed explanations of each template's guidance, pitfalls, and example use cases, serving as a companion reference to the machine-readable style library.

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