Generate an image

POST

/images/generations

const url = 'https://api.bayle.ai/images/generations';
const options = {
  method: 'POST',
  headers: {
    'Accept-Language': 'pt-BR',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"model":"z-image-turbo","prompt":"A watercolor painting of a lighthouse at sunset","n":1,"size":"1024x1024","response_format":"b64_json","moderation":"auto","quality":"standard","style":"natural","background":"auto","output_compression":100}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.bayle.ai/images/generations \
  --header 'Accept-Language: pt-BR' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "model": "z-image-turbo", "prompt": "A watercolor painting of a lighthouse at sunset", "n": 1, "size": "1024x1024", "response_format": "b64_json", "moderation": "auto", "quality": "standard", "style": "natural", "background": "auto", "output_compression": 100 }'

Generates an image from a prompt. model and prompt are required. Fields Bayle does not name below are forwarded as sent.

Three behaviours differ from OpenAI’s image API, and a client written against OpenAI’s defaults will notice all three.

A request generates at most one image. Asking for more through n is rejected rather than silently truncated.

Sending response_format: "url" returns a url field holding a base64 data: URI, such as data:image/png;base64,iVBORw0KG..., not a fetchable https:// link. A client expecting a downloadable URL must decode this field instead.

Omitting response_format does not default to "url" the way OpenAI’s API does. A request that leaves it out receives a b64_json field carrying the bare base64 bytes, with no data: prefix and no url key present at all. To get the url shape you must ask for it explicitly.

Some models take over a minute to produce an image. Bayle waits up to four minutes for a generation, so set your client’s own timeout above that. A generation still running after four minutes is reported as 504 with the request_timeout code.

Authorizations

BearerAuth

Parameters

Header Parameters

Accept-Language

string

Example

pt-BR

Chooses the language of any error message in this request’s response. A tag beginning with the two letters pt, in any case, selects Brazilian Portuguese; anything else, including an absent header, selects English. The tag may appear anywhere in a multi-tag header, for example fr-FR;q=0.9,pt;q=0.5,en;q=0.3. Quality values are accepted but ignored, since this is a presence check rather than weighted negotiation.

Request Body^required

application/json

The image request. Any field not listed here is forwarded as sent.

object

model

required

The image model to use, as returned by GET /models.

string

prompt

required

What to generate.

string

Number of images to generate. Only 1 is accepted; a higher value is rejected.

integer

default: 1

response_format

How the image comes back. url yields a base64 data: URI in a url field. Omitting this field yields b64_json instead, not url.

string

Allowed values: url b64_json

size

Requested image dimensions. Only the values listed are accepted — any other string is rejected rather than rounded to the nearest supported size. auto lets the model choose, which for most models means 1024x1024.

string

default: auto

Allowed values: auto 256x256 512x512 1024x1024 1536x1024 1024x1536 1792x1024 1024x1792

moderation

How strictly the generated image is filtered. auto keeps the safety filter on, which obscures adult content. low turns that filter off. Omitting the field leaves the filter on.

string

default: auto

Allowed values: auto low

quality

Accepted for OpenAI-client compatibility. Bayle does not act on this field; use size to influence the result.

string

style

Accepted for OpenAI-client compatibility. Bayle does not act on this field.

string

background

Accepted for OpenAI-client compatibility. Bayle does not act on this field.

string

output_compression

Accepted for OpenAI-client compatibility. Bayle does not act on this field.

integer

key

additional properties

any

Examples

Every option, image returned as bare base64

{
  "model": "z-image-turbo",
  "prompt": "A watercolor painting of a lighthouse at sunset",
  "n": 1,
  "size": "1024x1024",
  "response_format": "b64_json",
  "moderation": "auto",
  "quality": "standard",
  "style": "natural",
  "background": "auto",
  "output_compression": 100
}

Image returned as a `data:` URI in `url`

{
  "model": "z-image-turbo",
  "prompt": "A watercolor painting of a lighthouse at sunset",
  "size": "256x256",
  "response_format": "url",
  "moderation": "low"
}

Responses

200

The generated image. When the request set response_format: "url", each result’s url field holds a base64 data: URI rather than a fetchable link. When response_format was omitted, each result instead carries b64_json and no url field at all.

application/json

object

created

integer

data

Array<object>

object

url

Present only when the request asked for response_format: "url". Holds a base64 data: URI, not a fetchable link.

string

b64_json

The bare base64 image bytes. Present when response_format was b64_json or omitted.

string

key

additional properties

any

key

additional properties

any

Examples

`response_format` was `b64_json` or omitted (a placeholder image)

{
  "created": 1793364376,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAIAAAD8LEBqAAAAIElEQVR4nGNgYGD4z0AEYBxVSJIYNRhVOKoQXQoAf5oDBc0ZAAAAAElFTkSuQmCC"
    }
  ]
}

`response_format` was `url` (a placeholder image)

{
  "created": 1793364376,
  "data": [
    {
      "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAIAAAD8LEBqAAAAIElEQVR4nGNgYGD4z0AEYBxVSJIYNRhVOKoQXQoAf5oDBc0ZAAAAAElFTkSuQmCC"
    }
  ]
}

Headers

Content-Language

string

Allowed values: en pt-BR

Confirms which of the two supported locales, en or pt-BR, this response was rendered in, so a caller can detect it without reading the message text. Present on every response, success and error alike. On a chat completions stream it is committed together with the initial 200, so it appears whichever way the stream ends.

401

No credential was supplied, or the credential supplied is not valid. The request is rejected before any generation work begins. The body uses the shared error envelope, rendered in the negotiated locale.

application/json

Bayle’s OpenAI-shaped error envelope, shared by every error response this API returns.

object

error

required

object

message

required

A human-readable description of the failure, in the negotiated locale. See the Accept-Language request parameter for how that locale is chosen, and the Content-Language response header for which one was served.

string

type

required

OpenAI’s error type vocabulary, for example api_error, authentication_error, invalid_request_error, or rate_limit_error, matching the class of failure so an OpenAI SDK’s exception mapping keeps working.

string

param

required

The request field the failure names, when it names one. Null when the failure is not field-specific, as with authentication or rate limiting.

string

nullable

code

required

Bayle’s semantic error code, reusing OpenAI’s vocabulary where an equivalent exists, for example invalid_api_key or rate_limit_exceeded. Null when Bayle could not identify the specific failure; the envelope is still valid and carries a generic message. The full list lives in Bayle’s error reference rather than being enumerated here.

string

nullable

Examples

English (default)

{
  "error": {
    "message": "Your Bayle API key is missing or could not be verified.",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Brazilian Portuguese (`Accept-Language: pt-BR`)

{
  "error": {
    "message": "Sua chave de API da Bayle está ausente ou não pôde ser verificada.",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Headers

Content-Language

string

Allowed values: en pt-BR

default

The request failed. The body uses the shared error envelope, rendered in the locale negotiated through Accept-Language. type and code identify the specific failure when Bayle recognizes it, and fall back to type: api_error with a null code when it does not. Where a failure carries a meaningful status code, Bayle preserves it; a transport failure, such as a timeout or a refused connection, is reported as 502. The exception is an operation that documents its own time limit, which reports running past it as 504 with the request_timeout code.

application/json

Bayle’s OpenAI-shaped error envelope, shared by every error response this API returns.

object

error

required

object

message

required

string

type

required

string

param

required

The request field the failure names, when it names one. Null when the failure is not field-specific, as with authentication or rate limiting.

string

nullable

code

required

string

nullable

Examples

400: a missing or invalid parameter, for example an unknown `type` on `GET /models`, no `input` on `POST /embeddings`, `n` above 1 or an unlisted `size` on `POST /images/generations`, a numeric or unlisted `duration` on the video endpoints, or no `queue_id`

{
  "error": {
    "message": "Bayle could not process this request because one or more parameters are invalid.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_request"
  }
}

404: a `model` that does not exist

{
  "error": {
    "message": "The upstream model provider could not complete this request. Please try again.",
    "type": "api_error",
    "param": null,
    "code": null
  }
}

400: `POST /video/retrieve` or `POST /video/complete` with a `queue_id` that matches no job

{
  "error": {
    "message": "Bayle could not find a request matching the given request ID.",
    "type": "invalid_request_error",
    "param": "request_id",
    "code": "request_id_not_found"
  }
}

402: the key's balance is exhausted

{
  "error": {
    "message": "Your Bayle account does not have enough balance to complete this request.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_quota"
  }
}

422: a prompt the content policy does not permit

{
  "error": {
    "message": "Bayle's content policy does not permit this prompt.",
    "type": "invalid_request_error",
    "param": null,
    "code": "content_policy_violation"
  }
}

429: too many requests

{
  "error": {
    "message": "You have exceeded the rate limit for Bayle's API.",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}

500: the model could not complete the request, for example an embedding `dimensions` the model cannot produce

{
  "error": {
    "message": "Bayle could not complete inference for this request.",
    "type": "api_error",
    "param": null,
    "code": "inference_failed"
  }
}

504: an image generation still running after four minutes

{
  "error": {
    "message": "This request took too long to complete on Bayle and was timed out. For long-running requests, use streaming.",
    "type": "api_error",
    "param": null,
    "code": "request_timeout"
  }
}

Headers

Content-Language

string

Allowed values: en pt-BR

Generate an image

Authorizations

Parameters

Header Parameters

Example

Request Bodyrequired

Examples

Responses

200

Examples

Headers

401

Examples

Headers

default

Examples

Headers

Request Body^required