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

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, 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 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, 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

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, 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:

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.
• Plain-text prompts offer speed for manual testing but risk ambiguous instructions that produce inconsistent results.
• The 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 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【/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, 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.

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