# How to Construct JSON Templates for Agent Workflows vs. Plain Text in awesome-gpt-image-2

> Learn to construct JSON templates for agent workflows vs. plain text in awesome-gpt-image-2. Use JSON for deterministic schemas and plain text for ad-hoc experiments.

- Repository: [苍何/awesome-gpt-image-2](https://github.com/freestylefly/awesome-gpt-image-2)
- Tags: how-to-guide
- Published: 2026-08-26

---

**Use JSON templates to provide deterministic schemas for automated agents, while plain-text prompts work best for quick ad-hoc experiments, with both formats being serialized into the same `prompt` string field in the API request.**

The **awesome-gpt-image-2** repository implements a flexible prompt architecture that accepts both free-form strings and structured JSON objects for its image-generation agents. Understanding how to construct JSON templates for Agent workflows versus plain text prompts is essential for building reliable, repeatable automation pipelines. The repository's API endpoint treats both formats uniformly as request body strings, but the internal structure determines how precisely the model interprets constraints like platform, aspect ratio, and layout requirements.

## Plain-Text Prompts vs. JSON Templates

The repository distinguishes between these two input methods based on structure and determinism.

### Plain-Text Prompts

**Plain-text prompts** are free-form strings that the model parses directly without enforced schema validation. While convenient for rapid prototyping, the repository's documentation explicitly warns against vague instructions with the guideline "不要给模糊指令" (do not give ambiguous instructions) and stresses locking parameters like platform, aspect-ratio, and layout to prevent nonsense results【/cache/repos/github.com/freestylefly/awesome-gpt-image-2/main/docs/templates.md#L87-L90】.

This format relies entirely on natural language clarity, which can lead to omitted required fields or ambiguous constraints when driving automated Agent workflows.

### JSON Templates

**JSON templates** provide a deterministic schema that Agent workflows can populate programmatically. According to [`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md), a complete template includes explicit keys such as `type`, `platform`, `product`, `layout`, `style`, `content`, and `constraints`, ensuring the model receives all necessary parameters without guessing【/cache/repos/github.com/freestylefly/awesome-gpt-image-2/main/docs/templates.md#L24-L46】.

For example, a UI Screenshot template enforces constraints like "输出：高保真UI截图，文字清晰可读，比例[9:16/16:9]" (Output: high-fidelity UI screenshot, readable text, 9:16 or 16:9 aspect ratio)【/cache/repos/github.com/freestylefly/awesome-gpt-image-2/main/docs/templates.md#L20-L22】.

## How the API Processes Both Formats

The backend implementation in [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js) handles both formats through a unified interface. The handler expects a **plain-text** `prompt` field in the POST request body, validates the string length against `MAX_PROMPT_LENGTH = 6000`【/cache/repos/github.com/freestylefly/awesome-gpt-image-2/main/api/generate-image.js#L7】, and forwards the string to the external image-generation service (`ciyuan.today`)【/cache/repos/github.com/freestylefly/awesome-gpt-image-2/main/api/generate-image.js#L26-L42】.

Because the API accepts only strings, **JSON templates must be serialized** before transmission. This design keeps the server simple while allowing clients to choose between human-readable text and machine-readable JSON structures.

## Constructing JSON Templates for Agent Workflows

To implement an Agent workflow using JSON templates, compose an object conforming to one of the repository's documented schemas (UI Screenshot, Infographic, Movie Poster, etc.) and serialize it to a string.

### Required JSON Structure

Based on the UI Screenshot template in [`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md), a valid JSON object includes:

- **type**: The template category (e.g., "UI Screenshot")
- **platform**: Target platform (e.g., "iOS", "Android")
- **product**: Product or app name
- **layout**: Structural description (e.g., "Card-based feed with bottom tab bar")
- **style**: Visual aesthetics including theme, colors, and typography
- **content**: Specific UI elements and data
- **constraints**: Technical requirements like aspect ratio and fidelity

### Serialization Example

```javascript
const jsonPrompt = {
  type: "UI Screenshot",
  platform: "iOS",
  product: "Fitness App",
  layout: "Card‑based feed with bottom tab bar",
  style: {
    theme: "Dark Mode",
    primary_color: "Neon Green",
    typography: "Clean sans‑serif"
  },
  content: {
    header: "Today's Activity",
    cards: [
      { title: "Running", data: "5.2 km", button: "Start" },
      { title: "Calories", data: "340 kcal" }
    ]
  },
  constraints: "High fidelity, readable text, 9:16 aspect ratio"
};

fetch('/api/generate-image', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ 
    prompt: JSON.stringify(jsonPrompt), 
    caseId: 123 
  })
});

```

This approach follows the **JSON "进阶模板"** (advanced template) pattern shown in the documentation【/cache/repos/github.com/freestylefly/awesome-gpt-image-2/main/docs/templates.md#L24-L46】, wrapping the structured data as a string value within the request payload.

## Validation and Error Handling Differences

The two approaches differ significantly in validation capabilities and failure modes.

| Aspect | Plain-Text Prompt | JSON Template Prompt |
|--------|------------------|----------------------|
| **Clarity** | Relies on natural language; may omit required fields. | All required fields are explicit keys. |
| **Validation** | Simple length check (`MAX_PROMPT_LENGTH = 6000`). | Client-side schema validation possible before sending. |
| **Agent Compatibility** | Works for ad-hoc calls. | Preferred for automated agents because the schema is deterministic. |
| **Error-Handling** | Errors come from malformed text or API failures. | Errors can be tied to missing keys or invalid values. |

For production Agent workflows, JSON templates enable **pre-flight validation** against the schema defined in [`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md), catching missing `platform` or `constraints` fields before the API call occurs.

## Plain-Text Implementation for Quick Tests

For rapid experimentation without structured data requirements, send natural language directly:

```javascript
fetch('/api/generate-image', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ 
    prompt: '为 iOS 平台生成一张 Fitness App 的 UI 截图，比例 9:16，输出高保真 UI 截图', 
    caseId: 123 
  })
});

```

This format suits manual testing but lacks the guarantees necessary for automated pipelines where consistency is critical.

## Summary

- **JSON templates** provide deterministic schemas for Agent workflows, ensuring all required parameters (platform, layout, constraints) are explicitly defined according to [`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md).
- **Plain-text prompts** offer speed for manual testing but risk ambiguous instructions that produce inconsistent results.
- The [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js) endpoint accepts both formats as serialized strings in the `prompt` field, validating only length (`MAX_PROMPT_LENGTH = 6000`).
- Agent implementations should serialize JSON objects before transmission and implement client-side schema validation against the templates documented in the repository.

## Frequently Asked Questions

### When should I use JSON templates instead of plain text?

Use JSON templates for any automated Agent workflow where reproducibility matters. The structured format prevents the model from omitting critical fields like aspect ratio or platform constraints, whereas plain text suits only quick manual experiments where precision is less critical.

### Does the API natively parse JSON, or do I need to stringify it?

The API in [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js) expects a string in the `prompt` field. You must `JSON.stringify()` your template object before sending it. The server forwards this string directly to the image generation service without additional parsing.

### What is the maximum prompt length?

The server enforces a `MAX_PROMPT_LENGTH` of 6000 characters in [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js)【/cache/repos/github.com/freestylefly/awesome-gpt-image-2/main/api/generate-image.js#L7】. Both plain-text and serialized JSON templates must fit within this limit.

### Which template types support JSON structure?

The repository documents JSON structures for multiple formats in [`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md), including **UI Screenshot** (lines 24-46), **Infographic** (lines 107-128), and **Movie Poster** templates. Each defines specific required keys like `type`, `platform`, `style`, and `constraints`.