POST /v1/images/

An OpenAI Images-compatible API for generating images or editing images based on references with GPT Image models. Usage is largely the same as with the OpenAI SDK: point base_url to 4AICode and replace api_key with your sk-4ai-... token.

Image generation is charged per request against your wallet balance. The Image Generation page in the console is suitable for manual use, while the API is designed for integration into your own applications, workflows, and automation scripts.

For new projects, prefer GPT Image 2.5: gpt-image-2.5-sunburst is the most capable option for high-quality generation and precise editing, while gpt-image-2.5-flare is the fastest choice for high-quality everyday image generation. Existing integrations can continue using gpt-image-2.

Endpoints

POST https://relay.4aicode.com/v1/images/generations
POST https://relay.4aicode.com/v1/images/edits

Supported Models

Model	Use Case	Billing
`gpt-image-2.5-sunburst`	The most capable GPT Image 2.5 model for high-quality generation and precise editing	Charged per request against your wallet balance
`gpt-image-2.5-flare`	The fast GPT Image 2.5 model for high-quality everyday image generation	Charged per request against your wallet balance
`gpt-image-2`	Text-to-image generation and reference-based image editing	Charged per request against your wallet balance

Each model is available after an administrator configures and enables its per-use price and selects it in an upstream model list. If the model is not enabled, the API returns 503 model_unavailable.

Text-to-Image Generation

curl

curl https://relay.4aicode.com/v1/images/generations \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "A clean product shot of a black mechanical keyboard on a white desk",
    "size": "1024x1024",
    "quality": "medium",
    "response_format": "b64_json"
  }'

Python

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://relay.4aicode.com/v1",
    api_key="sk-4ai-xxxxxxxxxxxxxxxx",
)

resp = client.images.generate(
    model="gpt-image-2.5-sunburst",
    prompt="A clean product shot of a black mechanical keyboard on a white desk",
    size="1024x1024",
    quality="medium",
    response_format="b64_json",
)

image_base64 = resp.data[0].b64_json
with open("keyboard.png", "wb") as f:
    f.write(base64.b64decode(image_base64))

TypeScript

import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://relay.4aicode.com/v1",
  apiKey: process.env.OPENAI_API_KEY,
});

const resp = await client.images.generate({
  model: "gpt-image-2.5-sunburst",
  prompt: "A clean product shot of a black mechanical keyboard on a white desk",
  size: "1024x1024",
  quality: "medium",
  response_format: "b64_json",
});

const image = resp.data[0]?.b64_json;
if (!image) throw new Error("image generation failed");
fs.writeFileSync("keyboard.png", Buffer.from(image, "base64"));

Reference-Based Image Editing

/v1/images/edits supports two input methods:

multipart/form-data: Upload files using the image or image[] field. The maximum size of each file is 20 MB.
application/json: Pass a base64 data URL or an accessible image URL in images[].image_url.

multipart curl

curl https://relay.4aicode.com/v1/images/edits \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -F model="gpt-image-2.5-sunburst" \
  -F prompt="Keep the product, replace the background with a bright studio setup" \
  -F size="1024x1024" \
  -F quality="medium" \
  -F response_format="b64_json" \
  -F image="@./product.png"

Multiple reference images:

curl https://relay.4aicode.com/v1/images/edits \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -F model="gpt-image-2.5-sunburst" \
  -F prompt="Combine these references into one cohesive hero image" \
  -F image[]="@./subject.png" \
  -F image[]="@./style.png"

JSON Data URL

IMAGE_B64="$(base64 < product.png | tr -d '\n')"

curl https://relay.4aicode.com/v1/images/edits \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"gpt-image-2.5-sunburst\",
    \"prompt\": \"Put this product in a premium ecommerce scene\",
    \"size\": \"1024x1024\",
    \"quality\": \"medium\",
    \"response_format\": \"b64_json\",
    \"images\": [
      { \"image_url\": \"data:image/png;base64,${IMAGE_B64}\" }
    ]
  }"

file_id currently returns an explicit error. To use a mask, provide it through the mask file field or pass mask.image_url in JSON.

Parameters

Parameter	Applicable Endpoints	Description
`model`	All	An enabled model ID from the table above
`prompt`	All	Required generation or editing instructions
`size`	All	`auto`, `1024x1024`, `1536x1024`, or `1024x1536`
`quality`	All	`auto`, `low`, `medium`, or `high`; GPT Image 2.5 also supports `xhigh` and `max`
`response_format`	All	`b64_json` or `url`; `url` returns a data URL
`output_format`	All	`png`, `jpeg`, or `webp`
`background`	All	Passed through to the upstream image tool
`output_compression`	All	Output compression ratio for formats that support compression
`stream`	All	Returns SSE when set to `true`
`partial_images`	All	Requests partial-image events in streaming mode
`image` / `image[]`	edits	Reference images provided via multipart
`images[].image_url`	edits	Reference image URL or data URL provided via JSON
`mask` / `mask.image_url`	edits	Optional mask
`input_fidelity`	edits	Reference-image fidelity, passed through to the upstream image tool

Response

Non-streaming requests return an OpenAI Images-style response:

{
  "created": 1770000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgo...",
      "revised_prompt": "..."
    }
  ],
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png",
  "usage": {
    "images": 1
  }
}

When response_format=url, data[].url contains a data:image/png;base64,... URL, with the image content returned directly in the response.

Streaming Responses

Set "stream": true to return SSE.

Text-to-image generation events:

event: image_generation.partial_image
data: {"type":"image_generation.partial_image","partial_image_index":0,"b64_json":"..."}

event: image_generation.completed
data: {"type":"image_generation.completed","b64_json":"...","usage":{"images":1}}

Reference-based image editing events use the image_edit prefix:

event: image_edit.completed
data: {"type":"image_edit.completed","b64_json":"...","usage":{"images":1}}

Billing and Records

Each successful generation is charged at the current per-request price for the selected model. The usage page, wallet transaction history, and backend usage log record the model, request count, cost, status, and trace ID. By default, the platform does not store your prompts or image content.

Common Errors

HTTP	code	Resolution
400	`invalid_request_error`	Check `prompt`, `model`, image fields, and multipart formatting
401	`unauthorized`	Check `Authorization: Bearer sk-4ai-...`
429	`insufficient_quota` / `rate_limit`	Add funds to your wallet or reduce concurrency
503	`model_unavailable`	Contact an administrator to enable per-request pricing for the selected image model
502	`upstream_error`	Retry later; if the issue persists, contact support with the trace ID