# How to Use JSON Prompt Templates for Agent Calling in Awesome‑GPT‑Image‑2

> Learn to use JSON prompt templates for agent calling in Awesome-GPT-Image-2. Generate specific visual outputs by serializing templates via APIMart client utilities.

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

---

**Awesome‑GPT‑Image‑2 provides structured JSON prompt templates that enable autonomous agents to generate specific visual outputs by serializing template objects and submitting them via the APIMart client utilities.**

Awesome‑GPT‑Image‑2 ships with a comprehensive library of **JSON-based prompt templates** designed specifically for programmatic agent integration. These templates define concrete visual outputs—ranging from UI screenshots to infographics and product hero images—using a structured schema documented in the repository. By leveraging the client utilities in [`src/apimartClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js), autonomous agents can execute the entire image generation workflow without manual intervention.

## Understanding the JSON Template Structure

The repository stores all agent-optimized templates in **[`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)**, specifically within sections labeled **"JSON 进阶模板（推荐给 Agent 调用）"**. Each template follows a strict schema that describes a concrete visual output type, such as `UI Screenshot`, `Infographic`, or `Poster`.

Key fields within these templates include:

- **type**: The visual category (e.g., `UI Screenshot`)
- **platform**: Target operating system or environment
- **product**: Name or description of the subject
- **layout**: Structural composition details
- **style**: Theme, color palettes, and typography specifications
- **content**: Nested objects defining headers, cards, text elements, or data visualizations
- **constraints**: Aspect ratios, fidelity requirements, or readability guidelines

These structured fields ensure consistency across agent-generated requests and eliminate ambiguity in the prompt engineering process.

## Configuring the APIMart Client

Before initiating agent calls, import the high-level client functions from **[`src/apimartClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js)**. The repository provides secure key management through `getStoredApimartKey()` and `saveStoredApimartKey()`, which interact with the browser's storage using the constant `APIMART_KEY_STORAGE_KEY`.

For programmatic workflows, you will primarily use:

- `submitPersonalGeneration()` – For individual API key authentication
- `submitPlatformGeneration()` – For platform-level access token authentication
- `pollApimartTask()` – For asynchronous status monitoring

Both submission functions internally utilize **`buildApimartGenerationPayload`** from [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js) to construct the standardized HTTP request payload sent to the APIMart generation API.

## Implementing the Agent Calling Workflow

### Selecting and Populating Templates

Agents select a template from [`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md) and populate the required fields with context-specific values. For example, a **UI Screenshot** template requires platform specifications, layout descriptions, and content hierarchies.

The populated JavaScript object must include all mandatory keys documented in the template schema. Missing fields may result in generation failures or unpredictable visual outputs.

### Serializing and Submitting Requests

Once populated, the agent serializes the JSON object using `JSON.stringify()` and passes the resulting string as the prompt argument. The client functions handle the underlying HTTP communication:

```javascript
import {
  submitPersonalGeneration,
  pollApimartTask,
  fetchPersonalTask,
} from './src/apimartClient.js';

// Populate the UI Screenshot template
const uiPrompt = {
  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',
};

// Serialize and submit
const promptString = JSON.stringify(uiPrompt);
const myApiKey = 'sk-your-personal-apimart-key';

const { taskId } = await submitPersonalGeneration(
  promptString,
  myApiKey,
  'en'
);

```

The `submitPersonalGeneration` function returns a `taskId` immediately, allowing the agent to proceed with asynchronous polling while the generation process executes server-side.

## Polling for Task Completion

Image generation is asynchronous. Use **`pollApimartTask`** to monitor the task status until it reaches a terminal state (`succeeded`, `failed`, etc.). This function accepts a fetch wrapper (such as `fetchPersonalTask`) and configurable polling parameters:

```javascript
const fetchTask = () => fetchPersonalTask(taskId, myApiKey, 'en');

const finalTask = await pollApimartTask(fetchTask, {
  onProgress: (t) => console.log('Progress:', t.status),
  maxAttempts: 60,
  intervalMs: 2000,
});

console.log('Image URL:', finalTask.image?.url);

```

The polling mechanism handles transient network states and provides progress callbacks, ensuring robust agent operation without manual status checks.

## Summary

- **JSON prompt templates** in [`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md) provide structured schemas for visual outputs, explicitly designed for agent consumption
- **`submitPersonalGeneration`** and **`submitPlatformGeneration`** in [`src/apimartClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js) handle authentication and request submission
- **`pollApimartTask`** manages asynchronous completion checking with configurable retry logic
- **[`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js)** contains core utilities like `buildApimartGenerationPayload` that normalize API interactions
- All API key handling uses secure storage patterns via `getStoredApimartKey` to prevent credential leakage

## Frequently Asked Questions

### What file contains the JSON prompt templates for agent calling?

The templates are defined in **[`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)** within sections marked "JSON 进阶模板（推荐给 Agent 调用）". This file contains structured schemas for various visual categories including UI screenshots, infographics, posters, and product hero images, each with documented field requirements and example values.

### How does authentication work when using agent calling functions?

Authentication is handled through the helper functions `getStoredApimartKey()` and `saveStoredApimartKey()` located in [`src/apimartClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js). Pass your personal API key to `submitPersonalGeneration()` for individual usage, or provide a platform access token to `submitPlatformGeneration()` for enterprise deployments. The client never exposes keys in error messages or logs.

### What is the difference between personal and platform generation submission?

`submitPersonalGeneration` accepts a personal API key (`sk-...`) for single-user scenarios, while `submitPlatformGeneration` accepts a platform-issued access token for multi-tenant or organizational environments. Both functions utilize `buildApimartGenerationPayload` from [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js) to construct identical HTTP request structures, differing only in the authorization header construction.

### How does the polling mechanism handle generation failures?

The `pollApimartTask` function repeatedly invokes the provided fetch wrapper (e.g., `fetchPersonalTask`) until the task status indicates a terminal state such as `succeeded` or `failed`. It supports `maxAttempts` and `intervalMs` configuration to prevent infinite loops, and the `onProgress` callback allows agents to log intermediate statuses or trigger timeout logic based on business requirements.