POST
https://octopusx.ai
/
v1
/
images
/
generations
gpt-image-2 Image Generation API
curl --request POST \
  --url https://octopusx.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "prompt": "<string>",
  "n": 123,
  "size": "<string>",
  "image": [
    "<string>"
  ],
  "response_format": "<string>",
  "quality": "<string>",
  "style": {},
  "background": {},
  "watermark": true
}
'
{
  "created": 1735689600,
  "data": [
    {
      "url": "https://.../images/img-abc123.png",
      "revised_prompt": "A modern homepage illustration for an API platform, white background, teal-blue blocks, clean whitespace"
    }
  ]
}

​
gpt-image-2 Image Generation API

gpt-image-2 uses a unified image generation entry, suitable for text-to-image requests based on standard ratios and size tiers.
  • The unified entry is POST /v1/images/generations.
  • Select the target model by setting model = "gpt-image-2".
  • Supports both url and b64_json response formats.
  • You can include image in JSON as a reference image; whether it takes effect depends on the actual image channel that is matched.
  • If n is omitted or explicitly set to 0, the unified layer falls back to 1.

​
Method and Path

POST /v1/images/generations

​
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 homepage illustration for an API platform, white background, teal-blue blocks, clean whitespace",
    "n": 1,
    "size": "1536x1024",
    "response_format": "url"
  }'

​
Response Example

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

​
Authentication

Authorization: Bearer YOUR_API_KEY

​
Body

​
model
string
required
Must be set to gpt-image-2.
​
prompt
string
Generation prompt. For text-to-image semantics, this should be treated as required.
​
n
integer
Number of images to generate. If omitted or explicitly set to 0, the unified layer falls back to 1.
​
size
string
Output size. Common base tiers are 1024x1024、1536x1152、1536x1024、1024x1536、1920x1080、1080x1920.
​
image
string | array<string> | object
Optional reference image input. Commonly written as a Base64 string or Base64 array, suitable for channels that require image style reference.
​
response_format
string
Response format. Common values are url and b64_json.
​
quality
string
Quality field. Whether it actually takes effect depends on the final matched channel.
​
style
string | object
Style field, passed through as-is to supported upstreams.
​
background
string | object
Background control field, passed through as-is to supported upstreams.
​
watermark
boolean
Explicit watermark switch. false and omission have different semantics.

​
Base Ratios and Size Tiers

PresetActual Target Size
1:11024x1024
4:31536x1152
3:21536x1024
2:31024x1536
16:91920x1080
9:161080x1920
If the actual channel does not natively accept the target size, the gateway or plugin will fall back to a closer official size and append the ratio intent to the prompt.

​
Response

​
created
integer
Generation timestamp.
​
data[].url
string
The image URL returned when response_format = url.
​
data[].b64_json
string
The Base64 image data returned when response_format = b64_json.
​
data[].revised_prompt
string
Some upstreams rewrite the prompt and return it in this field.