---
title: "生成图像"
description: "生成图像（OpenAI Images 协议）。"
canonical: "https://pirouter.ai/zh/docs/api/images"
last-updated: "2026-10-13"
lang: "zh"
---

# 生成图像

生成图像（OpenAI Images 协议）。

`POST https://api.pirouter.ai/v1/images/generations`

兼容 OpenAI 的图像生成接口。图像模型在本端点和 Gemini 协议的 `generateContent` 端点提供，不在任何对话端点提供：在对话端点调用图像模型返回 `validation_failed`（422），错误信息会列出该模型提供的端点。该端点不支持流式。平台只读取请求 schema 里列出的字段；其他字段（`size`、`n` 等）全部原样转发给上游 provider。

## 鉴权

用下面任一请求头传 API key。

| 请求头 | 值 | 说明 |
| --- | --- | --- |
| `Authorization` | `Bearer sk-pi-…` | 平台签发的 API key，以 `sk-pi-` 开头，作为 Bearer token 发送。 |
| `X-Api-Key` | `sk-pi-…` | 同一个平台签发的 `sk-pi-` key，放在 `X-Api-Key` 请求头里发送。只有 `Authorization` 缺失或为空时才读取这个请求头；两个都带时，以 `Authorization` 为准。两个请求头都接受不带 `Bearer ` 前缀的裸 key。 |

## 请求体

`application/json`

OpenAI Images 生成请求。这里只列出平台会读取或要求必填的字段；协议的其余字段原样转发给上游。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 模型 ID，格式为 "vendor/model"。必须是登记在本端点上的图像模型。 |
| `prompt` | string | 是 | 要生成的图像的文字描述。原样转发。 |

## 响应

`200` `application/json`

生成的图像，结构由 OpenAI Images 协议定义；响应体来自上游，原样透传。

## 错误

| 状态码 | 错误码 | 说明 |
| --- | --- | --- |
| `400` | `invalid_request` | 请求缺少必填字段（`invalid_request`）：请求体既没有 `model` 也没有 `models` 时，返回 `model is required`。 |
| `401` | `invalid_api_key`, `api_key_not_found`, `api_key_revoked`, `api_key_expired` | API key 缺失或格式错误（`invalid_api_key`）、不存在（`api_key_not_found`）、已吊销（`api_key_revoked`）或已过期（`api_key_expired`）。 |
| `402` | `insufficient_balance` | 钱包余额不足以支付这次调用（`insufficient_balance`）。 |
| `404` | `model_not_found`, `no_eligible_provider` | 所请求的模型 ID 不存在或未启用（`model_not_found`）；或者请求的 `provider` 偏好与工作区路由设置合并后，没有 provider 能提供该模型（`no_eligible_provider`，`error.metadata` 里带有路由筛选漏斗）。 |
| `422` | `validation_failed` | 请求未通过校验（`validation_failed`）：该模型不在本端点提供（错误信息会列出它提供的端点），或者某个路由字段（`provider`、`models`、`route`、`preset`）不符合规则。错误信息会指出原因。 |
| `429` | `rate_limited` | 请求因限流被拒绝（`rate_limited`）。 |
| `500` | `internal_error` | 其他失败：没有健康的上游可以处理请求时返回 `provider_unavailable`（503）；平台侧出现意外故障时返回 `internal_error`（500）。 |
| `503` | `provider_unavailable` | 其他失败：没有健康的上游可以处理请求时返回 `provider_unavailable`（503）；平台侧出现意外故障时返回 `internal_error`（500）。 |

错误体

```json
{
  "error": {
    "message": "No such model. Model names are vendor-qualified (vendor/model), so a name copied from a provider's own docs needs its vendor prefix added. Call GET /v1/models for the slugs this gateway serves.",
    "type": "not_found_error",
    "code": "model_not_found"
  }
}
```

## 响应头

每个响应头后面列出它会出现在哪些状态码的响应里。

| 响应头 | 出现于 | 说明 |
| --- | --- | --- |
| `X-Pi-Trace-Id` | `200`, `400`, `401`, `402`, `404`, `422`, `429`, `default` | 平台请求 id，由网关生成。推理端点的每个响应都带；反馈问题时请附上它。 |
| `Access-Control-Allow-Origin` | `200`, `400`, `401`, `402`, `404`, `422`, `429`, `default` | 恒为 `*`。凭证是携带 API key 的请求头，从不是 cookie。 |
| `Access-Control-Expose-Headers` | `200`, `400`, `401`, `402`, `404`, `422`, `429`, `default` | 列出每一个 `X-Pi-*` 响应头，外加 `Retry-After` 与 `Content-Encoding`，让浏览器里的代码能读到它们。 |
| `X-Pi-Provider` | `200`, `default` | 处理这次响应的 provider，取值与 `provider.order`、`GET /v1/models/{vendor}/{model}/endpoints` 同一套词表。只有上游 provider 作出应答时才有（一次补全或一次上游错误）；发生 fallback 后是接手的那个 provider。 |
| `X-Pi-Model` | `200`, `default` | 处理这次响应的模型 slug，与响应体里的 `model` 是同一个值。由 fallback 模型接手时就是那个模型。只有上游 provider 作出应答时才有。 |
| `X-Pi-Upstream-Model` | `200`, `default` | 上游 provider 在它自己的响应里报告的完整模型 id，原样透传（流式时取自第一个数据事件）。上游响应没有给出模型时不带这个头；不会用平台自己的记录补上。 |
| `X-Pi-Upstream-Request-Id` | `200`, `default` | 上游 provider 自己的请求 id，原样透传，用于在 provider 一侧查这次调用。provider 没有返回时不带这个头。 |

## 请求示例

cURL

```bash
curl https://api.pirouter.ai/v1/images/generations \
  -H "Authorization: Bearer $PIROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.1-flash-image",
    "prompt": "A shiba inu drinking coffee on the moon, film grain"
  }'
```

Python

```python
import os
import requests

response = requests.post(
    "https://api.pirouter.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['PIROUTER_API_KEY']}"},
    json={
        "model": "google/gemini-3.1-flash-image",
        "prompt": "A shiba inu drinking coffee on the moon, film grain",
    },
)
print(response.json())
```

TypeScript

```ts
const response = await fetch('https://api.pirouter.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PIROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'google/gemini-3.1-flash-image',
    prompt: 'A shiba inu drinking coffee on the moon, film grain',
  }),
})
console.log(await response.json())
```

## 响应示例

`200` `application/json`

```json
{
  "created": 1791795980,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUg..."
    }
  ]
}
```