Docs › Image Gen

Image Generation Gateway

Payment wires: every paid endpoint accepts x402 and MPP (Machine Payments Protocol) on the same 402 - see Paying with x402 and Paying with MPP. Agent402 is the applied layer of Agentic Finance: agents that pay and get paid on their own.

Acceptable use. Hosted-instance traffic is governed by the Terms of Service - including a generative-content acceptable-use policy - and by the upstream model providers' usage policies. Wallets used for prohibited content are blocked before settlement. Outputs are generated by third-party models from your inputs; you are responsible for how you use them.

Three tiers of text-to-image generation, paywalled via x402. An agent sends a prompt and pays per call over x402 (USDC on Base and the other rails its 402 lists, or USDG on Robinhood Chain) or over MPP. No model API key is needed on the caller's side needed on the caller's side, no signup, no account. The operator's own OPENAI_API_KEY handles upstream auth; per-tier prompt caps and locked quality and size settings bound what one call can ask for.

Tiers

Endpoint	Price	Model	Quality	Size	Prompt cap
`POST /api/image-gen`	$0.03	`gpt-image-2`	low	1024x1024	1,000 chars
`POST /api/image-gen-hd`	$0.10	`gpt-image-2`	medium	1024x1024	2,000 chars
`POST /api/image-gen-premium`	$0.15	`gpt-image-2`	medium	1536x1024 (landscape), 1024x1536 (portrait) or 1024x1024	4,000 chars

All three tiers are wallet-only: there is no proof-of-work free tier because every call burns real upstream inference credit. See Security Model for the wallet-only rationale.

Request format

Every tier accepts the same JSON body:

{
  "prompt": "A photorealistic red apple on a white background, studio lighting"
}

Field	Required	Notes
`prompt`	yes	Text description of the desired image; max length varies by tier

Response format

Every tier returns the same envelope:

{
  "model": "gpt-image-2",
  "provider": "openai",
  "quality": "low",
  "size": "1024x1024",
  "image": "<base64-encoded PNG>",
  "revised_prompt": "A photorealistic red apple on a white background, studio lighting"
}

Field	Description
`model`	The model that generated the image
`provider`	Always `openai`
`quality`	The quality setting used (`low` or `medium`)
`size`	The image dimensions
`image`	Base64-encoded PNG image data
`revised_prompt`	The prompt as interpreted by the model (may differ from input)

Curl examples

Standard tier ($0.03: GPT Image 2, low quality)

curl -X POST https://agent402.tools/api/image-gen \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "A single red apple on a white background"
  }'

HD tier ($0.10: GPT Image 2, medium quality)

curl -X POST https://agent402.tools/api/image-gen-hd \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "A detailed watercolor painting of a mountain village at sunset"
  }'

Premium tier ($0.15: GPT Image 2, medium quality, larger frame)

curl -X POST https://agent402.tools/api/image-gen-premium \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "An isometric 3D render of a futuristic city block with neon signs and flying cars, cyberpunk aesthetic",
    "orientation": "landscape"
  }'

orientation is premium-only: landscape (1536x1024, the default), portrait (1024x1536) or square (1024x1024).

A render takes 10 to 30 s on the base tier, 20 to 45 s on hd and 25 to 50 s on premium, so set a client timeout of at least 60 s (75 s on premium).

All three return 402 without a valid x402 payment header: the same flow as every other paid tool. See Paying with x402 for how to sign and attach payment.

Per-tier caps

Each tier bounds what a single call can ask for:

Prompt cap (chars) limits how much text the caller can send, bounding input-token cost.
Quality lock per tier: each tier renders at the quality in the table above.
Size lock: the base and hd tiers render 1024x1024 only; premium renders one of the three sizes its orientation field names.
Model lock: every tier renders with the model in the table above.

These caps are enforced server-side before the upstream call is made.

Environment gating

The kit reads OPENAI_API_KEY at call time, not at boot. If the key is missing or empty, calls return 503 Service Unavailable and the rest of the server continues running normally. Self-hosters who don't want to offer image generation simply omit the env var: no code change needed.