POST/v1/images/generations

Create image

Creates an image from a text prompt using supported GPT Image models. OpenGateway currently supports non-stream image generation only.

Current support

This endpoint supports non-stream requests. Omit stream or set it to false. Streaming image generation and partial_images are planned for a later phase.

Headers

AuthorizationstringRequired
Bearer token for authentication. Format: Bearer YOUR_API_KEY
x-opengateway-user-idstringOptional
User identifier for analytics and tracking.
x-opengateway-session-idstringOptional
Session identifier for analytics and tracking.

Request body

modelstringRequired
ID of the image model to use. Use the owner/model format, such as openai/gpt-image-2, openai/gpt-image-1.5, or openai/gpt-image-1-mini.
promptstringRequired
Text prompt describing the image to generate.
nintegerOptional
Number of images to generate. Accepted range is 1 to 10. Provider/model limits may be narrower.
sizestringOptional
Output image size. Common values are auto, 1024x1024, 1024x1536, and 1536x1024.
qualitystringOptional
Rendering quality. Supported values are auto, low, medium, and high.
backgroundstringOptional
Background mode. Supported values are auto, transparent, and opaque.
output_formatstringOptional
Output image format. Supported values are png, jpeg, and webp.
output_compressionintegerOptional
Compression level from 0 to 100. Applies to jpeg and webp output.
moderationstringOptional
Moderation strictness. Supported values are auto and low.
userstringOptional
End-user identifier forwarded to the provider when supported.
streambooleanOptional
Current support is non-stream only. Omit this field or set it to false.
partial_imagesintegerOptional
Streaming-only parameter. Not supported for current non-stream requests.
extraobjectOptional🔌
OpenGateway-specific extension parameters.
fallbacksarray🔌

List of fallback model IDs to try if the primary target fails.

response_formatstringOptionalDeprecated
OpenAI supports this only for dall-e-2 and dall-e-3. GPT Image responses use base64 image payloads.
stylestringOptionalDeprecated
DALL-E 3 only parameter. Deprecated image models are outside the current OpenGateway images_generations scope.

Returns

Returns an OpenAI-compatible image generation response. OpenGateway does not convert image results into Chat Completions choices.

createdinteger
Unix timestamp for the image generation response.
dataarray
Generated image results. GPT Image responses include b64_json by default.
data[].b64_jsonstring
Base64-encoded image data.
data[].urlstringDeprecated
URL image responses are only available for OpenAI DALL-E 2/3 models.
data[].revised_promptstringDeprecated
DALL-E 3 only field in the OpenAI spec.
usageobject
Token usage for image generation. Usage may include text and image token details for input and output.
extra.routing.attemptsarray🔌
OpenGateway routing attempts. Each attempt includes provider, region, and status.

Request

curl https://apis.opengateway.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "A small red cube on a white background.",
    "size": "1024x1024",
    "quality": "medium"
  }'

Response

{
  "created": 1734567890,
  "data": [
    {
      "b64_json": "iVBORw0KGgo..."
    }
  ],
  "quality": "medium",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 20,
    "output_tokens": 1056,
    "total_tokens": 1076,
    "input_tokens_details": {
      "text_tokens": 20
    },
    "output_tokens_details": {
      "image_tokens": 1056
    }
  },
  "extra": {
    "routing": {
      "attempts": [
        {
          "provider": "openai",
          "region": "global",
          "status": "succeeded"
        }
      ]
    }
  }
}