> ## 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.

# 生成图像

> 用 GPT 图像模型根据文本提示词生成图像。

OpenAI 兼容的图像生成接口。把 OpenAI SDK 的 base URL 指向 `https://api.pipellm.ai/v1`，请求无需改动。

Gemini 图像模型请改用 [`generateContent`](/zh/api-reference/image/gemini)，两族模型的请求结构不同。

<Info>
  模型 ID 会随时间变化。用 [`GET /v1/models`](/zh/api-reference/list-models) 查询你的账户当前可用的模型。
</Info>

<ParamField body="prompt" type="string" required>
  图像描述。GPT 图像模型上限 32,000 字符。
</ParamField>

<ParamField body="model" type="string">
  图像模型 ID，例如 `gpt-image-2.5-sunburst`。上游默认值是 `dall-e-2`，建议显式指定。
</ParamField>

<ParamField body="n" type="integer" default="1">
  生成数量，1–10。
</ParamField>

<ParamField body="size" type="string" default="auto">
  GPT 图像模型支持 `auto`、`1024x1024`、`1536x1024`、`1024x1536`。也接受自定义 `宽x高`，前提是两边都能被 16 整除，且宽高比在 1:3 到 3:1 之间。
</ParamField>

<ParamField body="quality" type="string" default="auto">
  `low`、`medium`、`high` 或 `auto`。`gpt-image-2.5` 系列额外支持 `xhigh` 和 `max`。
  画质越高，输出 token 越多，费用也越高。
</ParamField>

<ParamField body="background" type="string" default="auto">
  `transparent`、`opaque` 或 `auto`。透明背景要求 `output_format` 为 `png` 或 `webp`。
</ParamField>

<ParamField body="output_format" type="string" default="png">
  `png`、`jpeg` 或 `webp`。
</ParamField>

<ParamField body="output_compression" type="integer" default="100">
  压缩级别 0–100，仅对 `jpeg` 和 `webp` 生效。
</ParamField>

<ParamField body="moderation" type="string" default="auto">
  `low` 或 `auto`。
</ParamField>

<ParamField body="user" type="string">
  稳定的终端用户标识，透传给上游用于滥用监控。
</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 时间戳。
</ResponseField>

<ResponseField name="data" type="array">
  每张生成的图像一项。

  <Expandable title="data[]">
    <ResponseField name="b64_json" type="string">
      Base64 编码的图像字节。GPT 图像模型只以这种方式返回图像，没有可下载的 URL。
    </ResponseField>

    <ResponseField name="revised_prompt" type="string">
      被改写后的提示词，仅 DALL-E 3 返回。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="size" type="string">
  实际输出尺寸。请求 `auto` 时看这个字段。
</ResponseField>

<ResponseField name="quality" type="string">
  实际画质。
</ResponseField>

<ResponseField name="output_format" type="string">
  `png`、`jpeg` 或 `webp`。
</ResponseField>

<ResponseField name="background" type="string">
  `transparent` 或 `opaque`。
</ResponseField>

<ResponseField name="usage" type="object">
  计费依据的 token 数。`output_tokens_details.image_tokens` 是随尺寸和画质变化的部分。
</ResponseField>

## 长时间请求

图像生成可能耗时数分钟。非流式请求下 PipeLLM 会保持连接：上游超过 90 秒没有响应时，网关每 30 秒写入一个填充块，直到真正的响应体到达。

填充内容是 JSON 文档之前的空白字符，标准 JSON 解析器都能正常处理。有两点要注意：

* 不要假设连接上的第一个字节就是 `{`。
* 把客户端读取超时调大。多数 HTTP 客户端的默认超时短于一次高画质生成。

## 错误

错误信封与 [错误处理](/zh/api-reference/errors) 一致。

<AccordionGroup>
  <Accordion title="400 invalid_request_error">
    缺少 `prompt`、`size` 取值模型不支持，或 `background: transparent` 搭配了 `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">
    见 [速率限制](/zh/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.