Skip to content
SayGMDocs
Dashboard

Generate images

POST
/images/generations
curl --request POST \
--url https://api.saygm.com/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-GM-Routing: default' \
--data '{ "model": "example", "prompt": "example", "n": 1, "size": "1024x1024", "response_format": "b64_json", "seed": 1 }'

Create one or more images with a model that supports image generation. The response contains base64 image data and the settled charge.

X-GM-Routing
string
default: default
Allowed values: default cheapest fastest

Per-request routing mode. default (or omitting the header) follows GM’s configured routing; cheapest ranks eligible routes by predicted final charge, preferring routes with at least 95% recent reliability; fastest ranks them by measured time to first token and output speed. Predictions are not a price cap or latency guarantee. A conversation stays on its current healthy route regardless of mode. Send the header at most once. Fusion, multi-model cascade, and some multimodal requests reject cheapest and fastest with 400.

X-GM-Providers
string
>= 1 characters

Comma-separated allowlist of provider identifiers that may serve the request. Use 1 to 16 distinct case-insensitive names, each 1 to 64 letters, digits, underscores, or hyphens, starting with a letter or digit. The restriction applies under every supported routing mode and on every retry. Invalid values return 400 with code invalid_provider_restriction; a model with no route on a listed provider returns 400 with code no_allowed_provider; listed providers that cannot serve now return 503. Fusion and multi-model cascade requests reject this header with 400.

Media typeapplication/json
object
model
required

A model id that supports image generation.

string
>= 1 characters
prompt
required
string
>= 1 characters
n

Number of images to generate. Defaults to 1.

integer | null
>= 1
size
Any of:
string
Allowed values: 1024x1024 832x1248 1248x832 864x1152 1152x864 912x1136 1136x912 768x1360 1360x768 1536x656
response_format
Any of:
string
Allowed value: b64_json
seed
integer | null
<= 4294967295

The generated images.

Media typeapplication/json
object
created
integer
data
required
Array<object>
>= 1 items
object
b64_json
required

Base64-encoded image bytes.

string
>= 1 characters
key
additional properties
any
usage
required
object
cost
required

Settled buyer charge in USD.

number
cost_nano_usd
required

The same charge in integer nano-USD.

integer
key
additional properties
any
key
additional properties
any
Examplegenerated
{
"created": 1,
"data": [
{
"b64_json": "example"
}
],
"usage": {
"cost": 1,
"cost_nano_usd": 1
}
}

Invalid request or an upstream provider 400 response.

Media typeapplication/json

OpenAI-shaped gateway error. Image errors after dispatch may also include billing fields at the top level.

object
error
required
object
message
required
string
type
required
string
code
required

Machine-readable error code. Account request limits use rate_limit_exceeded.

string
param
required
string | null
request_id

Gateway request identifier.

string
charged
boolean
billing_status
string
Allowed values: settled unbilled unknown
potentially_charged
boolean
cost_ndollars

Settled charge in nano-dollars; present when billing_status is settled.

integer
Example
{
"billing_status": "settled"
}

The API key is missing or invalid.

Media typeapplication/json

OpenAI-shaped gateway error. Image errors after dispatch may also include billing fields at the top level.

object
error
required
object
message
required
string
type
required
string
code
required

Machine-readable error code. Account request limits use rate_limit_exceeded.

string
param
required
string | null
request_id

Gateway request identifier.

string
charged
boolean
billing_status
string
Allowed values: settled unbilled unknown
potentially_charged
boolean
cost_ndollars

Settled charge in nano-dollars; present when billing_status is settled.

integer
Example
{
"billing_status": "settled"
}

Insufficient prepaid balance. The error message links to the funding page; when the available balance is nonzero it also reports estimated maximum cost and request-sizing guidance.

Media typeapplication/json

OpenAI-shaped gateway error. Image errors after dispatch may also include billing fields at the top level.

object
error
required
object
message
required
string
type
required
string
code
required

Machine-readable error code. Account request limits use rate_limit_exceeded.

string
param
required
string | null
request_id

Gateway request identifier.

string
charged
boolean
billing_status
string
Allowed values: settled unbilled unknown
potentially_charged
boolean
cost_ndollars

Settled charge in nano-dollars; present when billing_status is settled.

integer
Examples

No available balance

{
"error": {
"message": "Your gm balance is empty. Add credits: https://saygm.com/topup",
"type": "insufficient_quota",
"code": "insufficient_quota",
"param": null
}
}

Guardrail block (guardrail_blocked).

Media typeapplication/json
Any of:

OpenAI-shaped gateway error. Image errors after dispatch may also include billing fields at the top level.

object
error
required
object
message
required
string
type
required
string
code
required

Machine-readable error code. Account request limits use rate_limit_exceeded.

string
param
required
string | null
request_id

Gateway request identifier.

string
charged
boolean
billing_status
string
Allowed values: settled unbilled unknown
potentially_charged
boolean
cost_ndollars

Settled charge in nano-dollars; present when billing_status is settled.

integer
Example
{
"billing_status": "settled"
}

Request body too large (request_too_large).

Media typeapplication/json
Any of:

OpenAI-shaped gateway error. Image errors after dispatch may also include billing fields at the top level.

object
error
required
object
message
required
string
type
required
string
code
required

Machine-readable error code. Account request limits use rate_limit_exceeded.

string
param
required
string | null
request_id

Gateway request identifier.

string
charged
boolean
billing_status
string
Allowed values: settled unbilled unknown
potentially_charged
boolean
cost_ndollars

Settled charge in nano-dollars; present when billing_status is settled.

integer
Example
{
"billing_status": "settled"
}

Upstream 422 response.

Media typeapplication/json
Any of:

OpenAI-shaped gateway error. Image errors after dispatch may also include billing fields at the top level.

object
error
required
object
message
required
string
type
required
string
code
required

Machine-readable error code. Account request limits use rate_limit_exceeded.

string
param
required
string | null
request_id

Gateway request identifier.

string
charged
boolean
billing_status
string
Allowed values: settled unbilled unknown
potentially_charged
boolean
cost_ndollars

Settled charge in nano-dollars; present when billing_status is settled.

integer
Example
{
"billing_status": "settled"
}

Account, model, or upstream request limit. OpenAI-shaped account-limit errors use rate_limit_exceeded.

Media typeapplication/json
Any of:

OpenAI-shaped gateway error. Image errors after dispatch may also include billing fields at the top level.

object
error
required
object
message
required
string
type
required
string
code
required

Machine-readable error code. Account request limits use rate_limit_exceeded.

string
param
required
string | null
request_id

Gateway request identifier.

string
charged
boolean
billing_status
string
Allowed values: settled unbilled unknown
potentially_charged
boolean
cost_ndollars

Settled charge in nano-dollars; present when billing_status is settled.

integer
Example
{
"billing_status": "settled"
}
Retry-After
integer
>= 1

Seconds before retrying, when a delay is available.

Gateway internal error (internal_error).

Media typeapplication/json
Any of:

OpenAI-shaped gateway error. Image errors after dispatch may also include billing fields at the top level.

object
error
required
object
message
required
string
type
required
string
code
required

Machine-readable error code. Account request limits use rate_limit_exceeded.

string
param
required
string | null
request_id

Gateway request identifier.

string
charged
boolean
billing_status
string
Allowed values: settled unbilled unknown
potentially_charged
boolean
cost_ndollars

Settled charge in nano-dollars; present when billing_status is settled.

integer
Example
{
"billing_status": "settled"
}

Upstream connection failure (upstream_connect_failed).

Media typeapplication/json
Any of:

OpenAI-shaped gateway error. Image errors after dispatch may also include billing fields at the top level.

object
error
required
object
message
required
string
type
required
string
code
required

Machine-readable error code. Account request limits use rate_limit_exceeded.

string
param
required
string | null
request_id

Gateway request identifier.

string
charged
boolean
billing_status
string
Allowed values: settled unbilled unknown
potentially_charged
boolean
cost_ndollars

Settled charge in nano-dollars; present when billing_status is settled.

integer
Example
{
"billing_status": "settled"
}

The credit service, guardrail policy, or model serving is unavailable.

Media typeapplication/json
Any of:

OpenAI-shaped gateway error. Image errors after dispatch may also include billing fields at the top level.

object
error
required
object
message
required
string
type
required
string
code
required

Machine-readable error code. Account request limits use rate_limit_exceeded.

string
param
required
string | null
request_id

Gateway request identifier.

string
charged
boolean
billing_status
string
Allowed values: settled unbilled unknown
potentially_charged
boolean
cost_ndollars

Settled charge in nano-dollars; present when billing_status is settled.

integer
Example
{
"billing_status": "settled"
}
Retry-After
integer
>= 1

Seconds before retrying, when a delay is available.

Upstream timeout (upstream_timeout) or idle stream timeout (upstream_stream_idle_timeout).

Media typeapplication/json
Any of:

OpenAI-shaped gateway error. Image errors after dispatch may also include billing fields at the top level.

object
error
required
object
message
required
string
type
required
string
code
required

Machine-readable error code. Account request limits use rate_limit_exceeded.

string
param
required
string | null
request_id

Gateway request identifier.

string
charged
boolean
billing_status
string
Allowed values: settled unbilled unknown
potentially_charged
boolean
cost_ndollars

Settled charge in nano-dollars; present when billing_status is settled.

integer
Example
{
"billing_status": "settled"
}