Create an image

curl https://api.pipellm.ai/v1/images/generations \
  -H "Authorization: Bearer $PIPELLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "A red bicycle leaning against a cafe window, morning light",
    "size": "1024x1024",
    "quality": "medium",
    "n": 1
  }'

import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PIPELLM_API_KEY"],
    base_url="https://api.pipellm.ai/v1",
)

result = client.images.generate(
    model="gpt-image-2.5-sunburst",
    prompt="A red bicycle leaning against a cafe window, morning light",
    size="1024x1024",
    quality="medium",
)

with open("bicycle.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))

import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.PIPELLM_API_KEY,
  baseURL: "https://api.pipellm.ai/v1",
});

const result = await client.images.generate({
  model: "gpt-image-2.5-sunburst",
  prompt: "A red bicycle leaning against a cafe window, morning light",
  size: "1024x1024",
  quality: "medium",
});

fs.writeFileSync("bicycle.png", Buffer.from(result.data[0].b64_json, "base64"));

{
  "created": 1726400000,
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png",
  "background": "opaque",
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." }
  ],
  "usage": {
    "input_tokens": 18,
    "input_tokens_details": { "text_tokens": 18, "image_tokens": 0 },
    "output_tokens": 1056,
    "output_tokens_details": { "image_tokens": 1056 }
  }
}

POST

images

generations

curl https://api.pipellm.ai/v1/images/generations \
  -H "Authorization: Bearer $PIPELLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "A red bicycle leaning against a cafe window, morning light",
    "size": "1024x1024",
    "quality": "medium",
    "n": 1
  }'

import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PIPELLM_API_KEY"],
    base_url="https://api.pipellm.ai/v1",
)

result = client.images.generate(
    model="gpt-image-2.5-sunburst",
    prompt="A red bicycle leaning against a cafe window, morning light",
    size="1024x1024",
    quality="medium",
)

with open("bicycle.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))

import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.PIPELLM_API_KEY,
  baseURL: "https://api.pipellm.ai/v1",
});

const result = await client.images.generate({
  model: "gpt-image-2.5-sunburst",
  prompt: "A red bicycle leaning against a cafe window, morning light",
  size: "1024x1024",
  quality: "medium",
});

fs.writeFileSync("bicycle.png", Buffer.from(result.data[0].b64_json, "base64"));

{
  "created": 1726400000,
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png",
  "background": "opaque",
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." }
  ],
  "usage": {
    "input_tokens": 18,
    "input_tokens_details": { "text_tokens": 18, "image_tokens": 0 },
    "output_tokens": 1056,
    "output_tokens_details": { "image_tokens": 1056 }
  }
}

OpenAI-compatible image generation. Point the OpenAI SDK at https://api.pipellm.ai/v1 and the request works unchanged. For Gemini image models, use generateContent instead — the two families take different request shapes.

Model IDs change over time. List the ones available to your account with GET /v1/models.

string

required

Text description of the image. Up to 32,000 characters on GPT image models.

string

Image model ID, for example gpt-image-2.5-sunburst. Defaults to dall-e-2 upstream, so set it explicitly.

integer

default:"1"

Number of images to generate, 1–10.

string

default:"auto"

auto, 1024x1024, 1536x1024, or 1024x1536 on GPT image models. A custom WIDTHxHEIGHT is accepted when both sides divide by 16 and the aspect ratio stays between 1:3 and 3:1.

string

default:"auto"

low, medium, high, or auto. The gpt-image-2.5 variants add xhigh and max. Higher quality costs more output tokens.

string

default:"auto"

transparent, opaque, or auto. Transparent requires output_format of png or webp.

string

default:"png"

png, jpeg, or webp.

integer

default:"100"

Compression level 0–100, for jpeg and webp only.

string

default:"auto"

low or auto.

string

Stable end-user identifier, passed through for abuse monitoring.

curl https://api.pipellm.ai/v1/images/generations \
  -H "Authorization: Bearer $PIPELLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "A red bicycle leaning against a cafe window, morning light",
    "size": "1024x1024",
    "quality": "medium",
    "n": 1
  }'

import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PIPELLM_API_KEY"],
    base_url="https://api.pipellm.ai/v1",
)

result = client.images.generate(
    model="gpt-image-2.5-sunburst",
    prompt="A red bicycle leaning against a cafe window, morning light",
    size="1024x1024",
    quality="medium",
)

with open("bicycle.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))

import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.PIPELLM_API_KEY,
  baseURL: "https://api.pipellm.ai/v1",
});

const result = await client.images.generate({
  model: "gpt-image-2.5-sunburst",
  prompt: "A red bicycle leaning against a cafe window, morning light",
  size: "1024x1024",
  quality: "medium",
});

fs.writeFileSync("bicycle.png", Buffer.from(result.data[0].b64_json, "base64"));

{
  "created": 1726400000,
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png",
  "background": "opaque",
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." }
  ],
  "usage": {
    "input_tokens": 18,
    "input_tokens_details": { "text_tokens": 18, "image_tokens": 0 },
    "output_tokens": 1056,
    "output_tokens_details": { "image_tokens": 1056 }
  }
}

integer

Unix timestamp of the generation.

array

One entry per generated image.

Show data[]

string

Base64-encoded image bytes. GPT image models always return the image this way — there is no URL to fetch.

string

The rewritten prompt. DALL-E 3 only.

string

Resolved output size, useful when the request asked for auto.

string

Resolved quality.

string

png, jpeg, or webp.

string

transparent or opaque.

object

Token counts that back the charge. output_tokens_details.image_tokens is the part that scales with size and quality.

Long requests

Image generation can run for minutes. On a non-streaming request PipeLLM holds the connection open: if the upstream has not answered after 90 seconds, the gateway writes a padding chunk every 30 seconds until the real body arrives. The padding is whitespace before the JSON document, so any standard JSON parser handles it. Two things to watch:

Do not assume the first bytes on the wire are {.
Set a generous client read timeout. The default in most HTTP clients is shorter than a slow high-quality generation.

Errors

Same envelope as Errors.

400 invalid_request_error

Missing prompt, a size the model does not accept, or background: transparent with output_format: jpeg.

{
  "error": {
    "type": "invalid_request_error",
    "code": "400",
    "message": "Invalid value for 'size'"
  }
}

401 authentication_error

{
  "error": {
    "type": "authentication_error",
    "code": "401",
    "message": "Incorrect API key provided. Please visit https://console.pipellm.ai/account/api-keys to find your API key."
  }
}

402 insufficient_balance

{
  "error": {
    "type": "insufficient_balance",
    "code": "402",
    "message": "Insufficient balance. Please recharge your account at https://console.pipellm.ai/billing."
  }
}

429 rate_limit_error

See Rate Limits.

{
  "error": {
    "type": "rate_limit_error",
    "code": "429",
    "message": "Rate limit exceeded. Your current limit is 120 requests per minute (approximately 2.00 requests per second). Please visit https://console.pipellm.ai/billing to upgrade your plan for higher limits."
  }
}

API Guides

API Reference

Create an image

Long requests

Errors

​Long requests

​Errors

Long requests

Errors