GPT image generation

Use POST /v1/images/generations as the unified GPT image generation endpoint; see Available models below for selectable models.

POST /v1/images/generations

• Choose the target model with .
• Supports and response formats.
• You may attach in JSON as a reference image; whether it takes effect depends on the image channel that is hit.
• If is omitted or explicitly set to , the unified layer falls back to .

Available models

Model	Description
	Current selectable model for the GPT image generation unified endpoint

Headers

Name	Type	Required	Description
	string	Yes	Request authentication. Use a Bearer Token, for example:
	string	Yes	Request content type; must be

Request body

Name	Type	Required	Description
	string	Yes	Model ID; see Available models above
	string	No	Generation prompt. Treat as required for text-to-image
	integer	No	Number of images. If omitted or explicitly set to , the unified layer falls back to
	string	No	Output size. Supports (default) and any : width and height must be multiples of 16, aspect ratio between –, longest side ≤ , total pixels – (above is experimental). Common presets are listed below
	string | array | object	No	Optional reference image. Common forms are a Base64 string or a Base64 array
	string	No	Response format: /
	string	No	Quality: / / / (default). Whether it takes effect depends on the channel that is hit
	string | object	No	Style field; passed through as-is to supporting upstreams
	string | object	No	Background control. Official support is / (default) only; is not supported
	string	No	Output format: (default) / /
	integer	No	Compression level –; only applies to /
	string	No	Content moderation strength: (default) /
	boolean	No	Explicit watermark switch. differs from omitting the field

Aspect ratio and size presets

Preset	Target size

If the actual channel does not natively accept the target size, the gateway or plugin falls back to a closer official size and appends the aspect-ratio intent to the prompt.

Request example

curl -X POST https://octopusx.ai/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A modern API platform homepage illustration, white background, teal-blue blocks, clean whitespace",
    "n": 1,
    "size": "1536x1024",
    "response_format": "url"
  }'

Response example

200 - URL

{
  "created": 1735689600,
  "data": [
    {
      "url": "https://example.com/images/img-abc123.png",
      "revised_prompt": "A modern API platform homepage illustration, white background, teal-blue blocks, clean whitespace"
    }
  ]
}

200 - Base64

{
  "created": 1735689600,
  "data": [
    {
      "b64_json": "<BASE64_IMAGE_DATA>",
      "revised_prompt": "A modern API platform homepage illustration, white background, teal-blue blocks, clean whitespace"
    }
  ]
}

Response fields

Name	Type	Description
	integer	Generation timestamp
	array	Array of generation results
	string	Image URL when is
	string	Image Base64 data when is
	string	Some upstreams rewrite the prompt and return it in this field

Related endpoints

• Image APIs overview
• Error codes