Skip to content
AderraAderraAderra DocsBeta

Generate an image

POST
/v1/images/generations
curl --request POST \
  --url https://api.aderra.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "prompt": "A lighthouse in a storm, oil painting" }'

Generate one image from a prompt. Synchronous: the image is returned in the response, as b64_json or url depending on the model.

If the model’s content filter refuses the prompt, Aderra may retry once with the prompt reworded (then the response says prompt_rewritten: true) or on an unfiltered model. A refused or blank image is not charged.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
prompt
required

What to draw, or for an edit, what to change.

string
model

An image model id from GET /v1/usage/prices (all models at https://aderra.ai/docs/api/models/#image-models). Absent, or a name Aderra does not know, uses the default image model, flux-schnell (unless maxPriceMicro is set, when an unknown name is refused).

string
size

One of the sizes the model is sold at, for example 1024x1024. Absent: the model’s first size. Another size is refused with unsupported_size, which lists the allowed ones.

string
maxPriceMicro

Optional price ceiling in micro-credits (1 credit = 1,000,000 micro-credits; 1,000 credits = $1), as a string of digits. A model that costs more is refused with price_limit_exceeded before anything is charged.

string
/^\d{1,18}$/

Example 

{
  "prompt": "A lighthouse in a storm, oil painting"
}

Responses

Section titled “Responses”

200

Section titled “200”

The image.

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

One of b64_json (PNG data) or url, depending on the model.

object
b64_json
string
url
string format: uri
included

Always false for an API key.

boolean
billed_micro

What this image cost, in micro-credits, as a string.

string
prompt_rewritten

Present and true when the prompt was reworded after a content refusal.

boolean

Example 

{
  "billed_micro": "160000000"
}

400

Section titled “400”

invalid_json, missing_prompt, invalid_size, unsupported_size (with the allowed sizes), invalid_price_limit, unknown_model, and for edits no_reference_image.

Media typeapplication/json
One of:

Media and a few early refusals send error as a plain string, sometimes with a message for a person.

object
error
required
string
message
string

Example 

{
  "error": "missing_prompt"
}

401

Section titled “401”

The key is missing, unknown or revoked: {"error": "unauthorized"}.

Media typeapplication/json

Media and a few early refusals send error as a plain string, sometimes with a message for a person.

object
error
required
string
message
string

Example 

{
  "error": "unauthorized"
}

402

Section titled “402”

api_wallet_empty or key_spend_cap_reached in the OpenAI error shape, or a flat price_limit_exceeded when the image costs more than your maxPriceMicro.

Media typeapplication/json
One of:
object
error
required
object
type
string
param

The request field at fault, when there is one (speech).

string | null
code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:
string
message
string

Example 

{
  "error": {
    "type": "billing_error"
  }
}

403

Section titled “403”

account_suspended: the account behind the key is suspended.

Media typeapplication/json
object
error
required
object
type
string
param

The request field at fault, when there is one (speech).

string | null
code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:
string
message
string

Example 

{
  "error": {
    "type": "billing_error"
  }
}

413

Section titled “413”

request_too_large: the body is over the size limit.

Media typeapplication/json
object
error
required
object
type
string
param

The request field at fault, when there is one (speech).

string | null
code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:
string
message
string

Example 

{
  "error": {
    "type": "billing_error"
  }
}

422

Section titled “422”

refused_blank or image_content_refused: the image model refused the prompt. Not charged; reword it.

Media typeapplication/json

Media and a few early refusals send error as a plain string, sometimes with a message for a person.

object
error
required
string
message
string

Example 

{
  "error": "missing_prompt"
}

429

Section titled “429”

rate_limited: the key passed its requests per minute. too_many_concurrent_requests: the account already has 8 requests in progress. Wait for Retry-After seconds.

Media typeapplication/json
object
error
required
object
type
string
param

The request field at fault, when there is one (speech).

string | null
code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:
string
message
string

Example 

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "This API key is limited to 60 requests a minute. Try again in 12 seconds, or raise the key's limit at https://aderra.ai/developers."
  }
}

Headers

Section titled “Headers”
Retry-After
integer
Example 
12

Whole seconds to wait before trying again.

502

Section titled “502”

image_failed: the image model failed. Not charged.

Media typeapplication/json

Media and a few early refusals send error as a plain string, sometimes with a message for a person.

object
error
required
string
message
string

Example 

{
  "error": "missing_prompt"
}