Skip to content
Numes

API reference · Generate images

Media

Generate images

Generate one or more images from a prompt, returned as base64 data.

POSThttps://api.numes.ai/api/v1/images

Images are always returned inline as base64 (b64_json); URL responses are not offered. Controls you set (size, quality, output_format, background, n) are forwarded; add provider.require_parameters: true to route only to endpoints that declare every one of them. With stream: true the response is a stream of image_generation.* events. Your account's request policy applies to prompt; reference images aren't inspected. Guide: Image generation.

Authorization

AuthorizationheaderRequired

Bearer inference key. Charges settle in the key's billing currency. Authorization: Bearer $NUMES_API_KEY

Headers

X-Request-Idstring

Correlation ID, not an idempotency key. Inference request IDs recorded with a generation are unique per account. A traffic-admitted request reusing a recorded ID returns 400 invalid_request. Traffic admission rejection takes precedence over this conflict, including for reused IDs; it performs no generation lookup and writes no generation, result or attempt. Rate-limit rejection returns 429 rate_limited with Retry-After; an inference limiter outage retains 500 server.

Length1–128

Request body

application/json

The contract declares a 10 MiB body limit. The size the service enforces is listed in Limits.

modelstringRequired
Length≤ 393
Pattern^[a-z0-9][a-z0-9._-]{0,99}/[A-Za-z0-9][A-Za-z0-9._:-]{0,291}$
promptstringRequired
Length1–1 Mi
ninteger
Default1
Range1–10
sizestring
resolutionstring
Length≤ 16
aspect_ratiostring
Length≤ 16
qualityenum<string>
One ofautolowmediumhigh
output_formatenum<string>
One ofpngjpegwebp
backgroundenum<string>
One ofautoopaquetransparent
output_compressioninteger
Range0–100
seedinteger<int64>
streamboolean
Defaultfalse
input_referencesarray<string | object>
Items≤ 16

One of 2 shapes

ShowOption 1string

A string value.

ShowOption 2object
image_urlstringRequired
providerobject
Show11 child attributes
orderarray<string>
Items≤ 100
Itemlength 1–256
allow_fallbacksboolean
Defaulttrue
require_parametersboolean
Defaultfalse
data_collectionenum<string>
One ofallowdeny
zdrboolean
onlyarray<string>
Items≤ 100
Itemlength 1–256
ignorearray<string>
Items≤ 100
Itemlength 1–256
quantizationsarray<string>
Items≤ 100
Itemlength 1–256
regionsarray<string>

Numes extension filtering endpoint-declared country or region identifiers.

Items≤ 64
Uniqueitems
Itempattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
sortenum<string>

Deterministic provider sort. `quality` is a deliberate Numes compatibility extension that ranks endpoints by exact task-scoped content-free validation evidence; it is opt-in and never changes the default routing order.

One ofpricethroughputlatencyquality
max_priceobject
Show2 child attributes
promptnumber
Range≥ 0
completionnumber
Range≥ 0

Responses

200Image generation resultapplication/jsontext/event-stream

Headers

X-Request-Idstring

Correlation identifier assigned or accepted by the service.

BodyImageResponseapplication/json

createdinteger<int64>Required
dataarray<object>Required
Show3 child attributes
b64_jsonstringRequired
Encodingbase64
media_typestringRequired
revised_promptstring
usageobjectRequired
Show9 child attributes
input_imagesintegerRequired
Range≥ 0
output_imagesintegerRequired
Range≥ 0
input_audio_secondsnumberRequired
Range≥ 0
output_audio_secondsnumberRequired
Range≥ 0
input_charactersintegerRequired
Range≥ 0
prompt_tokensintegerRequired
Range≥ 0
completion_tokensintegerRequired
Range≥ 0
total_tokensintegerRequired
Range≥ 0
costnumberRequired
Range≥ 0

text/event-stream

503No eligible provider can serve the request. Unknown, unpublished, currency-mismatched and unauthorized shared model IDs receive the same bounded response (`error.code` 503, `error.metadata.error_type` "provider_unavailable", message "no provider is available"). Inference and encrypted resolution do not classify model existence after routing fails. Earlier validation and authorization errors remain unchanged. An interrupted server execution while the original HTTP caller remains connected also uses 503 provider_unavailable with the fixed message "service temporarily unavailable". Once streaming has started, the error is in-band and the HTTP status remains 200. If an otherwise eligible USD-indexed Bitcoin offer is blocked by an unavailable market reference, or its reference expires before dispatch, the response instead uses 503 with error_type "bitcoin_reference_price_unavailable" and message "Bitcoin pricing is unavailable. Try again shortly."application/json

Headers

X-Request-Idstring

Correlation identifier assigned or accepted by the service.

BodyErrorResponseapplication/json

errorobjectRequired
Show3 child attributes
codeintegerRequired
messagestringRequired
metadataobject
openrouter_metadataobject
ErrorCompatible error envelopeapplication/json

Headers

X-Request-Idstring

Correlation identifier assigned or accepted by the service.

Retry-Afterinteger

Optional delay in seconds for retryable rate or availability errors.

Range≥ 1

BodyErrorResponseapplication/json

errorobjectRequired
Show3 child attributes
codeintegerRequired
messagestringRequired
metadataobject
openrouter_metadataobject