# How to Construct the APIMart Generation Payload for GPT-Image2

> Learn how to construct the APIMart generation payload for GPT-Image2 using the buildApimartGenerationPayload function. Explore required and optional fields for effective image generation.

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

---

**The APIMart client constructs a JSON payload with required fields (model, prompt, n, size, resolution) and optional fields (language, webhook) using the `buildApimartGenerationPayload` function in [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js).**

When integrating with GPT-Image2 via the APIMart platform in the `freestylefly/awesome-gpt-image-2` repository, constructing the correct API payload is essential for successful image generation. The repository provides a dedicated utility function that formats requests according to APIMart's strict API contract, handling both mandatory parameters and optional configurations automatically.

## Required Payload Fields

Every generation request must include five core fields. According to the source code in [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js), these defaults are applied automatically:

- **model**: Hardcoded to `"gpt-image-2"` via the `APIMART_MODEL` constant
- **prompt**: The trimmed string passed to the function
- **n**: Fixed at `1` image per request
- **size**: Aspect ratio set to `"1:1"`
- **resolution**: Quality tier defaults to `"1k"`

## Optional Configuration Parameters

Developers can extend the base payload through the `options` argument:

- **language**: Supports `"en"` (default) or `"zh"`. The function normalizes any non-zh value to `"en"`.
- **webhook**: An optional URL where APIMart POSTs the generation result.

## The buildApimartGenerationPayload Function

Located in [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js) (lines 7-19), this utility constructs the final payload object:

```javascript
export function buildApimartGenerationPayload(prompt, options = {}) {
  const payload = {
    model: APIMART_MODEL,
    prompt: String(prompt || '').trim(),
    n: 1,
    size: '1:1',
    resolution: '1k'
  };

  if (options.webhook) payload.webhook = options.webhook;
  if (options.language) payload.language = options.language === 'zh' ? 'zh' : 'en';
  return payload;
}

```

The function ensures the prompt is always converted to a string and trimmed, preventing whitespace-related API errors.

## Usage Examples

### Basic Payload Construction

Import the utility and generate a minimal payload:

```javascript
import { buildApimartGenerationPayload } from './shared/apimart.js';

const payload = buildApimartGenerationPayload('draw a lighthouse');
// Result:
// {
//   model: 'gpt-image-2',
//   prompt: 'draw a lighthouse',
//   n: 1,
//   size: '1:1',
//   resolution: '1k'
// }

```

### Advanced Configuration with Webhook and Language

For production deployments requiring async callbacks and Chinese language support:

```javascript
const payload = buildApimartGenerationPayload('绘制一座灯塔', {
  language: 'zh',
  webhook: 'https://example.com/apimart-callback'
});
// Result includes:
// {
//   model: 'gpt-image-2',
//   prompt: '绘制一座灯塔',
//   language: 'zh',
//   webhook: 'https://example.com/apimart-callback',
//   ... // other defaults
// }

```

## Payload Validation and Edge Cases

The implementation handles several constraints defined in the APIMart specification:

- **Prompt Length**: APIMart enforces a maximum length of 10,000 characters (`APIMART_MAX_PROMPT_LENGTH`). While the builder doesn't truncate, the downstream API will reject oversized prompts.
- **Language Fallback**: Any value other than exactly `'zh'` defaults to `'en'`, ensuring API compatibility.
- **Conditional Fields**: The `webhook` field is omitted entirely from the JSON if not provided, keeping requests minimal.

## API Integration and Testing

Once constructed, the payload is JSON-stringified and sent to `https://api.apimart.ai/v1/images/generations`. The test suite in [`src/apimartClient.test.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.test.js) validates the exact structure.

For personal submissions, the payload includes all fields:

```javascript
// From src/apimartClient.test.js lines 76-83
assert.deepEqual(calls[0].body, {
  model: 'gpt-image-2',
  prompt: 'draw a fox',
  n: 1,
  size: '1:1',
  resolution: '1k',
  language: 'zh'
});

```

Platform submissions use an internal route (`/api/generate-image`) that consumes the same builder but sends a reduced field set to the backend.

## Summary

- The `buildApimartGenerationPayload` function in [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js) centralizes GPT-Image2 request formatting.
- Required fields (model, prompt, n, size, resolution) receive sensible defaults automatically.
- Optional `language` and `webhook` parameters extend functionality without breaking the core schema.
- The payload targets the APIMart endpoint at `https://api.apimart.ai/v1/images/generations`.
- Validation tests in [`src/apimartClient.test.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.test.js) confirm payload integrity for both personal and platform submission modes.

## Frequently Asked Questions

### What is the default resolution for GPT-Image2 APIMart payloads?

The default resolution is `"1k"`, hardcoded in the `buildApimartGenerationPayload` function. This represents the baseline quality tier for image generation requests.

### How does the APIMart client handle Chinese language prompts?

When the `options.language` parameter is set to `"zh"`, the payload includes `"language": "zh"`. Any other value (including undefined) defaults to `"en"`. This logic is implemented in [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js) using a ternary operator that normalizes inputs.

### What is the maximum prompt length allowed by APIMart?

APIMart caps prompts at 10,000 characters (`APIMART_MAX_PROMPT_LENGTH`). While the payload builder performs basic string trimming, you must ensure prompts stay within this limit before calling the function to avoid API rejection.

### Where is the payload construction function located in the repository?

The `buildApimartGenerationPayload` function is defined in [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js) at lines 7-19. This shared utility is imported by both the personal submission flow and the platform generation handlers located in `api/generation/`.