How to Migrate from Prose-Style Prompts to Structured JSON Protocols in Awesome-GPT-Image-2

Migrate from prose-style prompts to structured JSON protocols by extracting hard-coded strings from JavaScript modules into schema-validated JSON files, then updating the client to assemble payloads using buildApimartGenerationPayload in shared/apimart.js.

The Awesome-GPT-Image-2 repository currently stores image-generation instructions as free-form prose strings inside JavaScript objects, primarily within src/image25/cases.js. While this approach works for rapid prototyping, it blocks programmatic validation, complicates localization, and prevents type-safe extensions. Migrating from prose-style prompts to structured JSON protocols transforms these ephemeral strings into durable, versionable data contracts that integrate seamlessly with the existing api/generate-image.js endpoint while maintaining backward compatibility.

Why Migrate from Prose-Style Prompts to JSON?

Hard-coding prompts as raw strings in src/image25/cases.js and src/image25/realCases.js prevents automated validation of critical fields like caseId or language before runtime. A structured JSON protocol enforces schema compliance through required fields including caseId, prompt, language, and optional webhook parameters, enabling:

• Runtime validation using libraries like ajv before the payload reaches the network layer
• Internationalization support by storing multiple language variants in the same JSON structure without duplicating JavaScript logic
• Extensibility via optional metadata objects that can carry style presets, seed values, or layout specifications without modifying consumer code
• Cleaner API contracts that align with api/generate-image.js, which already expects a JSON body containing a prompt field and validates input length server-side

Step-by-Step Migration Guide

Step 1: Extract Prose Prompts into JSON Files

Locate all hard-coded prompt strings in src/image25/cases.js and src/image25/realCases.js. Replace them with references to separate JSON files stored in a new directory such as data/prompts/.

Each JSON file must contain the following structure:

{
  "caseId": 532,
  "language": "en",
  "prompt": "Create a Cannes-level premium summer beverage campaign poster featuring a 2-column by 3-row grid layout with an ultra-realistic lemon drink as the hero image",
  "metadata": {
    "layout": "2-column by 3-row grid",
    "hero": "lemon drink",
    "style": "ultra-realistic"
  }
}

Store these files with descriptive names (e.g., data/prompts/case532.json) to enable direct import by the front-end components.

Step 2: Define a JSON Schema for Validation

Create a schema file at data/prompt-schema.json to enforce data integrity. Reference data/style-library.json as an existing catalog pattern within the repository that demonstrates how structured data files are organized in this codebase.

The schema should model:

• Required fields: caseId (integer), prompt (string), language (string)
• Optional fields: metadata (object), webhook (string)

Use this schema for TypeScript definitions or runtime validation checks before the prompt reaches the API layer.

Step 3: Update the API Client Implementation

Modify the front-end components—specifically src/image25/App.jsx—to import the JSON definitions and construct payloads using the existing helper function.

Replace direct string usage with the following pattern:

import case532 from '../../data/prompts/case532.json';
import { buildApimartGenerationPayload } from '../../shared/apimart.js';

// Construct the structured payload
const payload = buildApimartGenerationPayload(case532.prompt, {
  caseId: case532.caseId,
  language: case532.language,
  webhook: optionalWebhookUrl,
  metadata: case532.metadata
});

The buildApimartGenerationPayload function in shared/apimart.js handles the correct nesting of parameters expected by the backend endpoint.

Implementation Details and Code Examples

Server-Side Compatibility

The existing server endpoint in api/generate-image.js already parses body.prompt and validates string length. Because the JSON protocol preserves the prompt field as a string within the larger object, the server-side validation remains transparent and backwards-compatible. The backend receives the same prompt value, just wrapped in a more structured envelope that includes additional metadata fields.

Runtime Validation Example

Before dispatching to the API, validate the JSON structure using a lightweight validator:

import Ajv from 'ajv';
import schema from '../../data/prompt-schema.json';
import caseData from '../../data/prompts/case532.json';

const ajv = new Ajv();
const validate = ajv.compile(schema);

if (!validate(caseData)) {
  console.error('Schema validation errors:', validate.errors);
  throw new Error('Invalid prompt definition');
}

// Safe to proceed with API call
submitPlatformGeneration(caseData);

Reference File Locations

• src/image25/cases.js: Contains original prose-style prompts requiring migration
• shared/apimart.js: Exports buildApimartGenerationPayload for constructing API-compatible JSON bodies
• api/generate-image.js: Server endpoint that receives and validates the prompt field from the JSON payload
• data/style-library.json: Existing structured data file demonstrating the repository's catalog patterns

Summary

• Extract all hard-coded prompt strings from src/image25/cases.js into individual JSON files in data/prompts/ with mandatory caseId, language, and prompt fields.
• Validate every prompt against a formal JSON schema before runtime to catch missing fields or type mismatches.
• Integrate using buildApimartGenerationPayload from shared/apimart.js to ensure the backend in api/generate-image.js receives correctly formatted requests.
• Extend functionality by adding optional metadata objects for style presets, layout grids, or localization variants without modifying core API logic.

Frequently Asked Questions

What specific fields are required in the structured JSON protocol?

The protocol requires three mandatory fields: caseId (unique integer identifier), prompt (the actual image generation instruction as a string), and language (ISO language code). Optional fields include metadata (an object containing style or layout specifications) and webhook (URL for asynchronous callbacks). This structure matches the parameter expectations in api/generate-image.js.

How does the backend handle the migration to JSON payloads?

The existing server implementation in api/generate-image.js extracts body.prompt as a string and validates its length, regardless of whether the request originates from a prose string or a JSON object. Because the JSON protocol nests the prompt text within a prompt field, the server processes it identically, making the migration transparent to the backend infrastructure.

Can I migrate existing prose prompts incrementally without breaking the application?

Yes. The migration supports incremental adoption because buildApimartGenerationPayload in shared/apimart.js accepts the prompt string as its first argument. You can refactor one case at a time in src/image25/cases.js, converting individual entries to JSON files while leaving others as inline strings until you complete the full migration.

Which validation library works best with the JSON schema in this repository?

The codebase uses standard JavaScript module patterns, making it compatible with ajv (Another JSON Schema Validator), which compiles schemas into efficient validation functions. Import your data/prompt-schema.json into an ajv.compile() instance to validate imported prompt objects before passing them to the API client, ensuring type safety and required field compliance.

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