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

> Learn to migrate from prose prompts to structured JSON protocols in Awesome-GPT-Image-2. Extract strings, create JSON files, and update your client for efficient payload assembly.

- Repository: [苍何/awesome-gpt-image-2](https://github.com/freestylefly/awesome-gpt-image-2)
- Tags: migration-guide
- Published: 2026-09-13

---

**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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/image25/cases.js) and [`src/image25/realCases.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/image25/cases.js) and [`src/image25/realCases.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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:

```json
{
  "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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/prompt-schema.json) to enforce data integrity. Reference [`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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:

```javascript
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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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:

```javascript
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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/image25/cases.js)**: Contains original prose-style prompts requiring migration
- **[`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js)**: Exports `buildApimartGenerationPayload` for constructing API-compatible JSON bodies
- **[`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js)**: Server endpoint that receives and validates the `prompt` field from the JSON payload
- **[`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js) to ensure the backend in [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js).

### How does the backend handle the migration to JSON payloads?

The existing server implementation in [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js) accepts the prompt string as its first argument. You can refactor one case at a time in [`src/image25/cases.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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.