> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipellm.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an image

> Generate images from a text prompt with GPT image models.

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`](/api-reference/image/gemini) instead — the two families take different request shapes.

<Info>
  Model IDs change over time. List the ones available to your account with [`GET /v1/models`](/api-reference/list-models).
</Info>

<ParamField body="prompt" type="string" required>
  Text description of the image. Up to 32,000 characters on GPT image models.
</ParamField>

<ParamField body="model" type="string">
  Image model ID, for example `gpt-image-2.5-sunburst`. Defaults to `dall-e-2` upstream, so set it explicitly.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Number of images to generate, 1–10.
</ParamField>

<ParamField body="size" type="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.
</ParamField>

<ParamField body="quality" type="string" default="auto">
  `low`, `medium`, `high`, or `auto`. The `gpt-image-2.5` variants add `xhigh` and `max`.
  Higher quality costs more output tokens.
</ParamField>

<ParamField body="background" type="string" default="auto">
  `transparent`, `opaque`, or `auto`. Transparent requires `output_format` of `png` or `webp`.
</ParamField>

<ParamField body="output_format" type="string" default="png">
  `png`, `jpeg`, or `webp`.
</ParamField>

<ParamField body="output_compression" type="integer" default="100">
  Compression level 0–100, for `jpeg` and `webp` only.
</ParamField>

<ParamField body="moderation" type="string" default="auto">
  `low` or `auto`.
</ParamField>

<ParamField body="user" type="string">
  Stable end-user identifier, passed through for abuse monitoring.
</ParamField>

<RequestExample>
  ```bash cURL theme={"dark"}
  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
    }'
  ```

  ```python Python theme={"dark"}
  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))
  ```

  ```typescript TypeScript theme={"dark"}
  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"));
  ```
</RequestExample>

<ResponseExample>
  ```json theme={"dark"}
  {
    "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 }
    }
  }
  ```
</ResponseExample>

<ResponseField name="created" type="integer">
  Unix timestamp of the generation.
</ResponseField>

<ResponseField name="data" type="array">
  One entry per generated image.

  <Expandable title="data[]">
    <ResponseField name="b64_json" type="string">
      Base64-encoded image bytes. GPT image models always return the image this way — there is no URL to fetch.
    </ResponseField>

    <ResponseField name="revised_prompt" type="string">
      The rewritten prompt. DALL-E 3 only.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="size" type="string">
  Resolved output size, useful when the request asked for `auto`.
</ResponseField>

<ResponseField name="quality" type="string">
  Resolved quality.
</ResponseField>

<ResponseField name="output_format" type="string">
  `png`, `jpeg`, or `webp`.
</ResponseField>

<ResponseField name="background" type="string">
  `transparent` or `opaque`.
</ResponseField>

<ResponseField name="usage" type="object">
  Token counts that back the charge. `output_tokens_details.image_tokens` is the part that scales with size and quality.
</ResponseField>

## 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](/api-reference/errors).

<AccordionGroup>
  <Accordion title="400 invalid_request_error">
    Missing `prompt`, a `size` the model does not accept, or `background: transparent` with `output_format: jpeg`.

    ```json theme={"dark"}
    {
      "error": {
        "type": "invalid_request_error",
        "code": "400",
        "message": "Invalid value for 'size'"
      }
    }
    ```
  </Accordion>

  <Accordion title="401 authentication_error">
    ```json theme={"dark"}
    {
      "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."
      }
    }
    ```
  </Accordion>

  <Accordion title="402 insufficient_balance">
    ```json theme={"dark"}
    {
      "error": {
        "type": "insufficient_balance",
        "code": "402",
        "message": "Insufficient balance. Please recharge your account at https://console.pipellm.ai/billing."
      }
    }
    ```
  </Accordion>

  <Accordion title="429 rate_limit_error">
    See [Rate Limits](/api-reference/rate-limits).

    ```json theme={"dark"}
    {
      "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."
      }
    }
    ```
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.