Images

BVE Gateway supports image generation and image editing.

Image Generation

POST https://api.bve.me/v1/images/generations

Requires Authorization: Bearer sk-bve-YOUR_KEY.

Generates images from a text prompt. Proxies directly to Fuelix.

Request body

{
  "model": "imagen-3",
  "prompt": "A photorealistic red apple on a white background",
  "n": 1
}

Field	Type	Required	Description
model	string	Yes	Image model (see below)
prompt	string	Yes	Text description of the image
n	integer	No	Number of images, 1–10. dall-e-3 only supports 1.
size	string	No	Image size (model-dependent)
quality	string	No	standard, hd, low, medium, high, or auto (model-dependent)
response_format	string	No	url or b64_json for DALL-E models. GPT image models always return base64 image data.
output_format	string	No	png, jpeg, or webp (GPT image models)
output_compression	integer	No	Compression level 0–100 for jpeg/webp GPT image outputs
stream	boolean	No	Enable image streaming mode
partial_images	integer	No	Number of partial images to emit in streaming mode, 0–3
moderation	string	No	low or auto (GPT image models)
background	string	No	transparent, opaque, or auto (GPT image models)
style	string	No	natural or vivid (dall-e-3 only)
user	string	No	End-user identifier, up to 256 characters

Available image models

Model	Description
imagen-3	Google Imagen 3 — high-quality photorealistic images
imagen-3-fast	Google Imagen 3 Fast — faster generation, similar quality
imagen-4	Google Imagen 4 — latest generation
imagen-4-ultra	Google Imagen 4 Ultra — highest quality
dall-e-3	OpenAI DALL-E 3 — high-quality images with precise prompt adherence
dall-e-2	OpenAI DALL-E 2 — faster, lower-cost image generation
gpt-image-1	OpenAI GPT Image 1 — multimodal-native image generation

Caution

DALL-E models (dall-e-2, dall-e-3, gpt-image-1) are recognized by the gateway and routed to Fuelix, but their availability depends on your Fuelix subscription. Use imagen-3 or imagen-3-fast for guaranteed availability.

Response

{
  "created": 1716288000,
  "data": [
    {
      "url": "https://..."
    }
  ]
}

cURL example

curl https://api.bve.me/v1/images/generations \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-3",
    "prompt": "A photorealistic red apple on a white background",
    "n": 1
  }'

SDK example

TypeScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-bve-YOUR_KEY',
  baseURL: 'https://api.bve.me/v1',
});

const image = await client.images.generate({
  model: 'imagen-3',
  prompt: 'A photorealistic red apple on a white background',
  n: 1,
});

console.log(image.data[0].url);

Python

from openai import OpenAI

client = OpenAI(
    api_key="sk-bve-YOUR_KEY",
    base_url="https://api.bve.me/v1",
)

image = client.images.generate(
    model="imagen-3",
    prompt="A photorealistic red apple on a white background",
    n=1,
)

print(image.data[0].url)

Saving to disk

TypeScript

import OpenAI from 'openai';
import fs from 'fs';

const client = new OpenAI({
  apiKey: 'sk-bve-YOUR_KEY',
  baseURL: 'https://api.bve.me/v1',
});

const result = await client.images.generate({
  model: 'gpt-image-1',
  prompt: 'A serene mountain lake at sunrise',
  output_format: 'webp',
  quality: 'high',
});

const imageData = result.data[0].b64_json!;
const buffer = Buffer.from(imageData, 'base64');
fs.writeFileSync('output.webp', buffer);
console.log('Saved output.webp');

Python

import base64
from openai import OpenAI

client = OpenAI(
    api_key="sk-bve-YOUR_KEY",
    base_url="https://api.bve.me/v1",
)

result = client.images.generate(
    model="gpt-image-1",
    prompt="A serene mountain lake at sunrise",
    output_format="webp",
    quality="high",
)

image_data = result.data[0].b64_json
buffer = base64.b64decode(image_data)
with open("output.webp", "wb") as f:
    f.write(buffer)

print("Saved output.webp")

Gateway validation

The gateway validates required and optional fields before forwarding to Fuelix. Invalid inputs return 400 with an OpenAI-compatible error body instead of an opaque upstream error.

Required fields:

Missing / invalid	Code	param
model absent	missing_required_parameter	"model"
model not a string	invalid_type	"model"
prompt absent	missing_required_parameter	"prompt"
prompt not a string	invalid_type	"prompt"

Optional field constraints:

Field	Constraint	Code	param
n	Not a number	invalid_type	"n"
n	Not an integer between 1 and 10	invalid_value	"n"
size	Not a string	invalid_type	"size"
quality	Not a string	invalid_type	"quality"
quality	Not one of "standard", "hd", "low", "medium", "high", "auto"	invalid_value	"quality"
response_format	Not a string	invalid_type	"response_format"
response_format	Not "url" or "b64_json"	invalid_value	"response_format"
output_format	Not a string	invalid_type	"output_format"
output_format	Not one of "png", "jpeg", "webp"	invalid_value	"output_format"
output_compression	Not a number	invalid_type	"output_compression"
output_compression	Not an integer	invalid_value	"output_compression"
output_compression	Not between 0 and 100	invalid_value	"output_compression"
stream	Not a boolean	invalid_type	"stream"
partial_images	Not a number	invalid_type	"partial_images"
partial_images	Not an integer between 0 and 3	invalid_value	"partial_images"
moderation	Not a string	invalid_type	"moderation"
moderation	Not "low" or "auto"	invalid_value	"moderation"
background	Not a string	invalid_type	"background"
background	Not one of "transparent", "opaque", "auto"	invalid_value	"background"
style	Not a string	invalid_type	"style"
style	Not "vivid" or "natural"	invalid_value	"style"
user	Not a string	invalid_type	"user"
user	More than 256 characters	invalid_value	"user"

size is model-dependent and not enumerated by the gateway — it only validates that the value is a string when provided.

---

Image Edits

POST https://api.bve.me/v1/images/edits

Requires Authorization: Bearer sk-bve-YOUR_KEY.

Edits an existing image based on a prompt. Accepts multipart/form-data.

Request (multipart/form-data)

Field	Type	Required	Description
image	binary	Yes	PNG image to edit (max 4 MB, must be square)
image[]	binary[]	No	Additional reference images. Repeating image[] fields is supported for multi-image edit/generation workflows.
prompt	string	Yes	Description of the desired edit
mask	binary	No	PNG mask (transparent areas indicate where to edit)
model	string	No	Image model to use
n	integer	No	Number of images, 1–10
size	string	No	Image size
response_format	string	No	url or b64_json
output_format	string	No	png, jpeg, or webp (GPT image models)
output_compression	integer	No	Compression level 0–100 for jpeg/webp GPT image outputs
background	string	No	transparent, opaque, or auto (GPT image models)
input_fidelity	string	No	high or low (GPT image models)
stream	boolean	No	Enable streaming edit mode
partial_images	integer	No	Number of partial images to emit in streaming mode, 0–3
quality	string	No	standard, low, medium, high, or auto
user	string	No	End-user identifier, up to 256 characters

cURL example

curl https://api.bve.me/v1/images/edits \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -F image="@image.png" \
  -F prompt="Add a rainbow in the background" \
  -F model="imagen-3"

SDK example

TypeScript

import OpenAI from 'openai';
import fs from 'fs';

const client = new OpenAI({
  apiKey: 'sk-bve-YOUR_KEY',
  baseURL: 'https://api.bve.me/v1',
});

const result = await client.images.edit({
  image: fs.createReadStream('image.png'),
  prompt: 'Add a rainbow in the background',
  model: 'imagen-3',
});

console.log(result.data[0].url);

Python

from openai import OpenAI

client = OpenAI(
    api_key="sk-bve-YOUR_KEY",
    base_url="https://api.bve.me/v1",
)

with open("image.png", "rb") as f:
    result = client.images.edit(
        image=f,
        prompt="Add a rainbow in the background",
        model="imagen-3",
    )

print(result.data[0].url)

Multi-image edit

TypeScript

import OpenAI from 'openai';
import fs from 'fs';

const client = new OpenAI({
  apiKey: 'sk-bve-YOUR_KEY',
  baseURL: 'https://api.bve.me/v1',
});

// Pass multiple images as an array for multi-image edit workflows
const result = await client.images.edit({
  image: [
    fs.createReadStream('image1.png'),
    fs.createReadStream('image2.png'),
  ],
  prompt: 'Combine these two images into one scene',
  model: 'gpt-image-1',
});

console.log(result.data[0].b64_json);

Python

from openai import OpenAI

client = OpenAI(
    api_key="sk-bve-YOUR_KEY",
    base_url="https://api.bve.me/v1",
)

with open("image1.png", "rb") as f1, open("image2.png", "rb") as f2:
    result = client.images.edit(
        image=[f1, f2],
        prompt="Combine these two images into one scene",
        model="gpt-image-1",
    )

print(result.data[0].b64_json)

Gateway validation

The gateway validates required form fields and optional constraints before forwarding the multipart request to Fuelix. Invalid inputs return 400 with an OpenAI-compatible error body instead of an opaque upstream error.

Required fields:

Missing / invalid	Code	param
image (and image[]) both absent	missing_required_parameter	"image"
prompt absent	missing_required_parameter	"prompt"
prompt empty string	invalid_value	"prompt"

Optional field constraints:

Field	Constraint	Code	param
model	Not a string	invalid_type	"model"
n	Not a parseable integer between 1 and 10	invalid_value	"n"
size	Not a string	invalid_type	"size"
response_format	Not a string	invalid_type	"response_format"
response_format	Not "url" or "b64_json"	invalid_value	"response_format"
output_format	Not a string	invalid_type	"output_format"
output_format	Not one of "png", "jpeg", "webp"	invalid_value	"output_format"
output_compression	Not a parseable integer between 0 and 100	invalid_value	"output_compression"
input_fidelity	Not a string	invalid_type	"input_fidelity"
input_fidelity	Not "high" or "low"	invalid_value	"input_fidelity"
stream	Not "true" or "false" (form strings)	invalid_value	"stream"
partial_images	Not a parseable integer between 0 and 3	invalid_value	"partial_images"
quality	Not a string	invalid_type	"quality"
quality	Not one of "standard", "low", "medium", "high", "auto"	invalid_value	"quality"
background	Not a string	invalid_type	"background"
background	Not one of "transparent", "opaque", "auto"	invalid_value	"background"
user	Not a string	invalid_type	"user"
user	More than 256 characters	invalid_value	"user"

Note

• Image variations (POST /v1/images/variations) are not supported by Fuelix and return 404.
• The multipart request is forwarded directly — no re-encoding or buffering.
• Image and mask files must be PNG format.
• Multiple input images can be sent by repeating the image[] form field (or passing an array in the SDK).

Response headers

BVE Gateway adds the following headers to every authenticated response:

Header	Example	Description
X-Request-Id	550e8400-…	UUID for this request (generated per request)
X-BVE-Client-Id	my-trace-123	Echo of the client-supplied X-Request-Id (when present and valid: alphanumeric + -_., ≤ 128 chars). Absent when not supplied or value failed validation.
X-BVE-Latency	143	Total gateway latency in milliseconds
X-BVE-Model	imagen-3	Model ID resolved for this request
X-BVE-Key-Name	prod-key	Name of the API key used for this request (redacted if it matches a provider credential pattern)

The full X-RateLimit-* header set (RPM, RPD, monthly) is also included. See Rate Limits & Quotas for details and example output.

Next steps

Models Full image model catalog — imagen-3, imagen-4, and other generation models

SDK Usage TypeScript and Python examples for every endpoint including image generation

Rate Limits & Quotas Per-key RPM/RPD limits, monthly caps, and Retry-After handling

Errors Full error code reference including model_endpoint_mismatch for image models