Generate images from a text prompt

POST

/v1/images/generations

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.ai.wpengine.com/v1/images/generations', [
  'body' => '{ "model": "google/gemini-2.5-flash-image", "prompt": "example", "n": 1, "size": "1024x1024" }',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();

• Current environment

Requires a valid WP Engine bearer token. API keys must carry the “image:write” permission.

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

object

model

required

Model identifier in “provider/model-name” format (e.g. “google/gemini-2.5-flash-image”).

string

Example

google/gemini-2.5-flash-image

prompt

required

Text prompt describing the desired image.

string

n

Number of images to generate (1-4).

integer

default: 1 >= 1 <= 4

size

Image dimensions (e.g. “1024x1024”, “1024x1792”, “1792x1024”).

string

Example

1024x1024

Responses

200

Generated images

Media typeapplication/json

object

created

required

Unix timestamp.

integer format: int64

data

required

Array<object>

object

b64_json

required

Base64-encoded image data.

string

revised_prompt

The prompt as revised by the model (may differ from the input).

string

Example^generated

{
  "created": 1,
  "data": [
    {
      "b64_json": "example",
      "revised_prompt": "example"
    }
  ]
}

400

Invalid request body or parameters

Media typeapplication/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

401

Missing or invalid bearer token

Media typeapplication/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

Headers

WWW-Authenticate

string

Example

Bearer realm="ai-services"

402

The account’s credit balance is exhausted. Grant or top up credits before retrying. Distinct from 429, which is edge rate limiting.

Media typeapplication/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

403

The token is valid, but the caller is not permitted to perform this action — either its scope/permission is insufficient or the authenticated user is not authorized for the target account (error type “permission_error”). On /v1/chat/completions specifically, a 403 with error type “content_policy_violation” instead means the request content was blocked by content moderation policy; that response never identifies which filter or category matched.

Media typeapplication/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

429

Rate limit exceeded. The request was throttled at the edge; wait and retry later. The response body is a short HTML page generated by the load balancer, not a structured JSON error — clients should rely on the 429 status code rather than parsing the body.

Media typetext/html

string

502

Upstream provider returned an error

Media typeapplication/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

503

A required dependency is temporarily unavailable. Retry after a short delay with exponential back-off.

Media typeapplication/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

default

Upstream provider error passed through with its original status code and response body. The shape may vary by provider.

Media typeapplication/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}