How to Construct the APIMart Generation Payload for GPT-Image2

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.

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, 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 (lines 7-19), this utility constructs the final payload object:

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:

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:

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 validates the exact structure.

For personal submissions, the payload includes all fields:

// 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 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 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 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 at lines 7-19. This shared utility is imported by both the personal submission flow and the platform generation handlers located in api/generation/.

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