# How to Use the Pitfalls Guide in GPT-Image-2 Templates: A Complete Developer Reference

> Master GPT-Image2 templates with the Pitfalls Guide. Learn to append constraints to your prompt for precise guardrails, eliminating ambiguity and ensuring strict visual fidelity.

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

---

**The Pitfalls Guide (避坑指南) embedded throughout [`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md) provides explicit "avoid-pitfall" constraints that you append directly to your prompt or JSON payload, giving the model concrete guardrails that eliminate ambiguous outputs and enforce strict visual fidelity.**

The **pitfalls guide in GPT-Image-2 templates** serves as a critical safety net within the `freestylefly/awesome-gpt-image-2` repository. Each template in the master catalog terminates with a curated list of common failure modes—ranging from vague platform specifications to unreadable text—paired with imperative constraints that prevent the model from generating low-quality or inconsistent visuals. By integrating these guardrails into your generation workflow, you transform natural language descriptions into machine-readable directives that dramatically improve output reliability.

## Where the Pitfalls Guide Lives in the Repository

The master template file **[[`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)** houses the complete Pitfalls Guide. Every template section in this file concludes with a dedicated **避坑指南** subsection containing bullet-pointed constraints. This proximity ensures that the safeguards remain synchronized with their corresponding base prompts, allowing you to copy-paste the entire block—template plus pitfalls—without hunting through separate documentation.

## Anatomy of the Pitfalls Guide

The guide operates through three distinct mechanisms that convert human intent into model constraints.

### Contextual Safety Net

Each pitfalls section enumerates the most frequent failure modes for a specific visual style. For example, UI screenshot templates warn against mixing platform features (such as combining Twitter’s blue verification checkmark with TikTok’s music disc animation), while infographic templates guard against information hierarchy collapse.

### Explicit Constraint Syntax

Every bullet point utilizes strong imperative phrasing—typically starting with **不要…** (Do not…) or **强制…** (Mandatory…)—to create unambiguous machine-readable instructions. When you copy these clauses into your prompt, they function as negative constraints that override the model’s tendency to hallucinate generic or conflicting visual elements.

### Template-Level Integration

The pitfalls live immediately adjacent to the base template (whether plain-text or JSON). This structural decision, implemented in [[`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md), guarantees that every template modification automatically carries its corresponding safety constraints, preventing version drift between the prompt logic and its guardrails.

## Step-by-Step Workflow for Using the Pitfalls Guide

Follow this four-step process to leverage the guide in your image generation pipeline:

1. **Select a template** from the visual category you need (UI screenshot, infographic, poster, etc.) in **[[`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)**.
2. **Copy the base prompt**—either the plain-text description or the JSON schema—for your chosen style.
3. **Append the "avoid-pitfall" bullet list** from the **避坑指南** section directly beneath your primary prompt content.
4. **Submit the combined payload** to the **`/api/generate-image`** endpoint or invoke the skill’s **`generate`** function to produce the final image.

## Code Implementation Examples

### Plain-Text Prompt with Pitfalls

When submitting natural language prompts, append the pitfalls section as a markdown list at the end of your text block:

```text
为[产品类型]生成一张[平台，如 iOS/Android/Web]界面图。
核心功能：[功能点A]、[功能点B]、[功能点C]。
视觉风格：[极简/科技/拟物]，主色[颜色]，强调色[颜色]。
布局：[顶部导航/双栏/卡片流]，信息层级清晰，留白充足。
输出：高保真UI截图，文字清晰可读，比例[9:16/16:9]。

# 避坑指南

- **不要给模糊指令**：明确 "平台 + 比例 + 布局"，否则模型会像个实习生一样乱排版。
- **强制文字锁定**：要求 "文字绝对可读，必须显示指定的中文"，避免出现乱码按钮和毫无意义的火星文。
- **截图区分平台特征**：X（Twitter）有蓝勾认证、转发/引用区分；抖音有音乐碟片和点赞动画；小红书有双列瀑布流特征。生成前指定平台，否则模型会混搭。

```

The two “avoid-pitfall” items provide strict directives that resolve the most common ambiguities for UI generation, specifically targeting platform fidelity and text legibility.

### JSON Payload with avoid_pitfalls Array

For programmatic interfaces, structure the constraints within a dedicated array that the skill layer merges into the final prompt:

```json
{
  "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",
  "avoid_pitfalls": [
    "不要给模糊指令：明确平台、比例和布局",
    "强制文字锁定：文字必须可读且显示指定的中文"
  ]
}

```

Pass this JSON to the **`generate`** function defined in **[[`agents/skills/gpt-image-2-style-library/SKILL.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/agents/skills/gpt-image-2-style-library/SKILL.md)](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/agents/skills/gpt-image-2-style-library/SKILL.md)**. The skill internally concatenates the `avoid_pitfalls` array into the prompt string before forwarding the request to the image generation API.

### Programmatic Integration in Node.js

When building agents that consume the style library, use the `generateImage` helper to automatically merge templates with their pitfalls:

```javascript
import { generateImage } from '@gpt-image-2/style-library';

// Build a UI prompt with pitfalls
const prompt = {
  type: 'UI Screenshot',
  platform: 'Web',
  product: 'Project Management Tool',
  layout: 'Two‑column dashboard',
  style: { theme: 'Minimal', primary_color: '#0066FF' },
  constraints: 'High fidelity, readable text, 16:9 aspect ratio',
  avoid_pitfalls: [
    '不要给模糊指令：明确平台、比例和布局',
    '强制文字锁定：文字必须可读且显示指定的中文'
  ]
};

generateImage(prompt)
  .then(url => console.log('Generated image URL:', url))
  .catch(err => console.error('Generation failed:', err));

```

The **`generateImage`** utility guarantees that every request respects the safety constraints by prepending the `avoid_pitfalls` content to the generation context before calling the back-end endpoint.

## Critical Source Files for Developers

Understanding the repository architecture helps you locate and extend the pitfalls logic:

- **[[`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)** — Master catalog of all industrial-level prompt templates and their accompanying Pitfalls Guide sections.
- **[[`agents/skills/gpt-image-2-style-library/SKILL.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/agents/skills/gpt-image-2-style-library/SKILL.md)](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/agents/skills/gpt-image-2-style-library/SKILL.md)** — Defines the skill-level interface, including the **`generate`** function that merges `avoid_pitfalls` arrays into final prompt strings.
- **[[`agents/skills/gpt-image-2-style-library/references/style-library.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/agents/skills/gpt-image-2-style-library/references/style-library.md)](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/agents/skills/gpt-image-2-style-library/references/style-library.md)** — Developer reference for prompt construction, JSON formatting, and embedding avoid-pitfall clauses.
- **[[`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js)](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js)** — Back-end endpoint that receives the finalized prompt (text or JSON) and forwards it to the underlying image model.
- **[[`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json)](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json)** — JSON catalog of all templates for programmatic lookup of template IDs and their associated pitfalls.

## Summary

- The **Pitfalls Guide (避坑指南)** lives in **[[`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)** as a curated list of negative constraints appended to each template.
- **Explicit imperatives** ("不要…", "强制…") prevent the model from generating ambiguous platform features, unreadable text, or mixed visual styles.
- You can inject pitfalls via **plain-text markdown lists** appended to prompts or through the **`avoid_pitfalls`** JSON array consumed by the skill’s **`generate`** function.
- The **[`agents/skills/gpt-image-2-style-library/`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/agents/skills/gpt-image-2-style-library/)** module handles automatic merging of pitfalls with base templates before API submission.
- Using the guide transforms vague natural-language instructions into **machine-readable guardrails**, significantly improving the reliability and visual fidelity of GPT-Image-2 outputs.

## Frequently Asked Questions

### What is the Pitfalls Guide in GPT-Image-2 templates?

The Pitfalls Guide is a set of **negative constraints** (labeled **避坑指南** in the source) documented in **[[`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)**. It lists specific mistakes to avoid—such as mixing iOS and Android UI elements or generating illegible text—providing imperative commands that override the model’s default behavior and enforce strict adherence to the intended visual style.

### How do I add pitfalls to a JSON prompt payload?

Include an **`avoid_pitfalls`** array as a top-level key in your JSON object, populated with string values copied from the **避坑指南** section of your chosen template. When you pass this payload to the **`generate`** function in **[[`SKILL.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/SKILL.md)](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/agents/skills/gpt-image-2-style-library/SKILL.md)**, the skill automatically concatenates these constraints into the final prompt sent to the image generation API.

### Where are the pitfalls definitions stored?

All pitfalls definitions reside in **[[`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)** at the repository root. Each template section concludes with its specific **避坑指南** subsection. Additionally, structured metadata for programmatic access exists in **[[`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json)](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json)**, which catalogs template IDs and their associated constraint sets.

### Can I customize the pitfalls for my own templates?

Yes. The repository structure allows you to append custom **避坑指南** sections to any new template you create in **[[`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)**. Ensure your custom pitfalls follow the imperative syntax ("不要…" for prohibitions, "强制…" for requirements) so that the **[`agents/skills/gpt-image-2-style-library/`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/agents/skills/gpt-image-2-style-library/)** skill layer can parse and merge them correctly during generation workflows.