How to Construct the APIMart Generation Payload for GPT-Image-2

The APIMart generation payload is built by the buildApimartGenerationPayload helper function in shared/apimart.js, which assembles a plain object with fixed model parameters and configurable fields for the prompt, webhook URL, and language settings.

The freestylefly/awesome-gpt-image-2 repository implements a Node.js client for the APIMart image generation API. Constructing a valid APIMart generation payload requires using the specific helper function that enforces the API's strict schema for the gpt-image-2 model.

The Core Payload Builder in shared/apimart.js

The buildApimartGenerationPayload function defined in shared/apimart.js serves as the single source of truth for payload construction. This function accepts a prompt string and an options object, then returns a plain JavaScript object formatted for the APIMart API endpoint.

Fixed Model Parameters

According to the source code analysis, the following properties are hardcoded to match APIMart's contract for the GPT-Image-2 model:

• model: Fixed to 'gpt-image-2' — the only supported model identifier.
• n: Fixed to 1 — APIMart supports only a single image per request.
• size: Fixed to '1:1' — enforcing a square aspect ratio.
• resolution: Fixed to '1k' — specifying the 1K pixel resolution output.

Dynamic Input Fields

The function handles user-provided inputs with validation and normalization:

• prompt: The input value is coerced to a string and trimmed using String(prompt || '').trim().
• webhook (optional): If options.webhook exists, it is added to the payload for asynchronous callback notifications.
• language (optional): Supports 'zh' for Chinese or defaults to 'en' for English via conditional logic: options.language === 'zh' ? 'zh' : 'en'.

Sending the Payload to APIMart

Once constructed, the payload is sent to POST https://api.apimart.ai/v1/images/generations as a JSON-serialized request body. The src/apimartClient.js file demonstrates this integration in methods like submitPersonalGeneration, which calls:

body: JSON.stringify(buildApimartGenerationPayload(prompt, { language }))

Direct Payload Construction

For custom implementations, import the helper directly from shared/apimart.js:

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

const payload = buildApimartGenerationPayload(
  'A futuristic cityscape at sunset',
  { language: 'en', webhook: 'https://example.com/apimart-callback' }
);

// Result:
// {
//   model: 'gpt-image-2',
//   prompt: 'A futuristic cityscape at sunset',
//   n: 1,
//   size: '1:1',
//   resolution: '1k',
//   webhook: 'https://example.com/apimart-callback',
//   language: 'en'
// }

Using the Client Wrapper (Personal API Key)

For standard use cases, the repository provides submitPersonalGeneration in src/apimartClient.js:

import { submitPersonalGeneration } from './apimartClient.js';

const apiKey = 'YOUR_PERSONAL_APIMART_KEY';
const prompt = 'A cute robot holding a coffee mug';

submitPersonalGeneration(prompt, apiKey, 'en')
  .then(({ taskId }) => console.log('Submitted, task ID:', taskId))
  .catch(err => console.error('Generation error:', err));

Platform Token Integration

For platform-managed accounts, use submitPlatformGeneration which accepts a configuration object:

import { submitPlatformGeneration } from './apimartClient.js';

await submitPlatformGeneration(
  { caseId: 42, prompt: 'A serene mountain lake', language: 'zh' },
  fetch // optional custom fetch implementation
);

Summary

• The buildApimartGenerationPayload function in shared/apimart.js is the authoritative constructor for APIMart requests.
• The payload enforces fixed values for model (gpt-image-2), image count (1), aspect ratio (1:1), and resolution (1k).
• Optional parameters include webhook for async callbacks and language for localized generation (zh or en).
• The client wrappers in src/apimartClient.js handle the HTTP transport to api.apimart.ai/v1/images/generations.

Frequently Asked Questions

What is the default image resolution for APIMart generation?

The default resolution is fixed to '1k' as defined in shared/apimart.js. This value is hardcoded in the payload builder and cannot be overridden through standard function parameters.

Can I request multiple images in a single APIMart payload?

No. The n parameter is hardcoded to 1 in the payload construction logic. The APIMart API only supports generating one image per request when using the gpt-image-2 model through this client.

How do I receive asynchronous results from APIMart?

Include a webhook URL in the options object when calling buildApimartGenerationPayload or the client wrapper methods. When the generation task completes, APIMart will POST the results to your specified endpoint.

Where is the payload construction logic located in the repository?

The primary logic resides in shared/apimart.js, specifically within the buildApimartGenerationPayload function. Validation and testing for this logic can be found in src/apimartClient.test.js, while src/apimartClient.js contains the HTTP client that utilizes this payload builder.

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