POST
https://octopusx.ai
/
v1
/
images
/
generations
OpenAI Images Compatible Image Generation
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>",
  "quality": "<string>",
  "response_format": "<string>",
  "style": {},
  "background": {},
  "watermark": true
}
'
{
  "created": 1735689600,
  "data": [
    {
      "url": "https://.../images/img-abc123.png",
      "revised_prompt": "A minimalist illustration for an API platform homepage, white background with teal accents"
    }
  ]
}

​
OpenAI Images Compatible Image Generation

Submit text-to-image requests through the unified image generation entry point, and return an OpenAI Images-style response.
  • A unified image generation API that selects different image models through model.
  • Preserves the OpenAI Images response structure: created + data[].
  • Supports both url and b64_json response formats.
  • Size restrictions for dall-e-2 and dall-e-3 are validated directly by the unified layer.
  • When n is omitted or explicitly set to 0, the unified layer automatically defaults it 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-1",
    "prompt": "A minimalist illustration for an API platform homepage, white background with teal accents",
    "n": 1,
    "size": "1024x1024",
    "quality": "auto",
    "response_format": "url"
  }'

​
Response Example

{
  "created": 1735689600,
  "data": [
    {
      "url": "https://.../images/img-abc123.png",
      "revised_prompt": "A minimalist illustration for an API platform homepage, white background with teal accents"
    }
  ]
}

​
Authentication

Authorization: Bearer YOUR_API_KEY

​
Body

​
model
string
required
Model name. The unified layer requires this field to be present.
​
prompt
string
Generation prompt. For image generation, it should be treated as required semantically; whether the request is ultimately blocked is determined jointly by the unified layer and the upstream provider.
​
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. dall-e-2 accepts only 256x256, 512x512, and 1024x1024; dall-e-3 accepts only 1024x1024, 1024x1792, and 1792x1024.
If you are actually using gpt-image-2-pro, the plugin layer also exposes high-tier options such as 1:1(2K), 4:3(2K), 3:2(2K), 2:3(2K), 16:9(2K), 9:16(2K), 1:1(4K), 4:3(4K), 3:2(4K), 2:3(4K), 16:9(4K), and 9:16(4K). See the full mapping in Image Model Support Matrix.
​
quality
string
Image quality. dall-e-3 defaults to standard; gpt-image-1 defaults to auto.
​
response_format
string
Response format. Common values are url and b64_json. When b64_json or base64 is requested, the unified layer returns Base64 image data.
​
style
string | object
Style field, passed through unchanged to supported upstream providers.
​
background
string | object
Background control field, passed through unchanged to supported upstream providers.
​
watermark
boolean
Explicit watermark switch. false is semantically different from omitting it: omission means the default strategy is used, while false explicitly disables it.

​
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 upstream providers rewrite the prompt and return it in this field.
​
metadata
object
Additional metadata. Whether it exists depends on the specific channel.

​
Use Cases

​
Basic Image Generation

curl -X POST https://octopusx.ai/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1",
    "prompt": "Generate a clean product poster"
  }'

​
High-Quality DALL·E 3

curl -X POST https://octopusx.ai/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type": "application/json" \
  -d '{
    "model": "dall-e-3",
    "prompt": "A sci-fi city nightscape illustration",
    "size": "1792x1024",
    "quality": "hd",
    "response_format": "url"
  }'

​
Base64 Output

curl -X POST https://octopusx.ai/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type": "application/json" \
  -d '{
    "model": "gpt-image-1",
    "prompt": "Generate a clean poster of an icon set",
    "response_format": "b64_json"
  }'

​
Notes

This page describes only the common semantics of the unified entry point, and does not mean that all image channels support exactly the same fields. Whether fields such as style, background, and watermark actually take effect depends on the final channel that is hit.