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

# 图片通用说明

> 用 OpenAI 兼容的 Images 接口调用 GPT Image、Nano Banana、可灵图片：文生图、参考图生图、各系列参数与计费。

## 接口

```text theme={null}
POST https://token.poryf.com/v1/images/generations
POST https://token.poryf.com/v1/images/edits
```

使用 `Authorization: Bearer YOUR_API_KEY` 认证，与 [对话接口](/api/chat) 使用同一把密钥。

* `/v1/images/generations`：文生图；带 `image` 参考图时为图生图。
* `/v1/images/edits`：图片编辑，`image` 必填。

图片接口是**同步**的：请求会等到图片生成完才返回。出图通常需要 20 秒到 2 分钟，4K 高画质更久，请把客户端超时设为 **5 分钟以上**，不要因为超时重复提交，否则会重复扣费。

## 请求字段

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | 模型 ID，例如 `gpt-image-2`、`nano-banana-2`、`kling-image-3.0` |
| `prompt` | string | 是 | 画面描述 |
| `size` | string | 否 | 输出尺寸，如 `1024x1024`、`1536x1024`；Nano Banana、可灵也接受 `1K` / `2K` / `4K` |
| `resolution` | string | 否 | 输出档位 `1K` / `2K` / `4K`（Nano Banana、可灵）；不传时按 `size` 推断，都不传为 `1K` |
| `aspect_ratio` | string | 否 | 画面比例，如 `1:1`、`16:9`、`9:16`（Nano Banana、可灵）；不传时按 `size` 取最接近的比例 |
| `quality` | string | 否 | 画质（GPT Image），见下方各系列说明 |
| `n` | integer | 否 | 生成张数，默认 1；只有可灵图片支持一次多张 |
| `image` | string / array | 否 | 参考图 **URL**，可传一个或数组；`/v1/images/edits` 必填。GPT Image 的传法不同，见下方提示 |
| `output_format` | string | 否 | `png` 或 `jpeg` |
| `negative_prompt` | string | 否 | 不希望出现的内容（Nano Banana、可灵） |
| `seed` | integer | 否 | 随机种子（Nano Banana、可灵） |

<Warning>
  Nano Banana 与可灵的参考图只接受公网可访问的 `http(s)` URL，不支持上传文件，也不支持 Base64。请先把图片放到对象存储或图床，再传链接。
</Warning>

不支持 `stream`。

<Note>
  GPT Image 的图片编辑用 OpenAI 原生格式：multipart 上传图片文件（字段名 `image`），或 JSON 传 `images: [{"image_url": "图片 URL"}]`。示例见 [GPT Image 2](/api/images/gpt-image-2#示例：图片编辑)。
</Note>

## 各系列参数

| 系列 | 模型 ID | 分辨率 / 尺寸 | 单次张数 | 参考图上限 |
| - | - | - | - | - |
| GPT Image | `gpt-image-2` | 用 `size` 指定，如 `1024x1024` | 1 | 支持图片编辑 |
| GPT Image | `gpt-image-2.5-flare`、`gpt-image-2.5-sunburst` | 用 `size` 指定，最大 3840 px（4K） | 1 | 支持图片编辑 |
| Nano Banana | `nano-banana` | 1K / 2K / 4K | 1 | 3 |
| Nano Banana | `nano-banana-2`、`nano-banana-2-lite`、`nano-banana-pro` | 1K / 2K / 4K | 1 | 14 |
| 可灵图片 | `kling-image-3.0` | 1K / 2K | 最多 9 | 1 |
| 可灵图片 | `kling-image-2.1` | 1K / 2K | 最多 9 | 4 |
| 可灵图片 | `kling-image-3.0-omni`、`kling-image-o1` | 1K / 2K / 4K | 最多 9 | 10 |

**画面比例**

* Nano Banana：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`。`nano-banana-2` 和 `nano-banana-2-lite` 另外支持 `1:4`、`4:1`、`1:8`、`8:1` 超宽比例。
* 可灵图片：`16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`3:2`、`2:3`、`21:9`。

**GPT Image 画质**

* `quality` 可选 `low`、`medium`、`high`。GPT Image 2.5 另有 `xhigh`、`max`。
* 画质越高、尺寸越大，消耗的 token 越多，出图也越慢。

## 示例：文生图

<CodeGroup>
  ```bash curl theme={null}
  curl https://token.poryf.com/v1/images/generations \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "nano-banana-2",
      "prompt": "秋日咖啡店的拿铁海报，暖色调，留出标题位置",
      "resolution": "2K",
      "aspect_ratio": "3:4"
    }'
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="YOUR_API_KEY",
      base_url="https://token.poryf.com/v1",
      timeout=300,
  )

  result = client.images.generate(
      model="gpt-image-2",
      prompt="秋日咖啡店的拿铁海报，暖色调，留出标题位置",
      size="1024x1024",
      quality="low",
  )
  print(result.data[0].url or result.data[0].b64_json[:32])
  ```
</CodeGroup>

`resolution`、`aspect_ratio` 等非 OpenAI 标准字段，在 OpenAI SDK 中可以通过 `extra_body` 传入。

## 示例：参考图生图

```bash theme={null}
curl https://token.poryf.com/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "把这张产品图换成纯白背景，保持商品不变",
    "image": ["https://example.com/product.jpg"]
  }'
```

多张参考图时，`image` 传数组，数量不超过上表的参考图上限。

## 响应

以下为示例结构，不代表真实生成结果：

```json theme={null}
{
  "data": [
    { "url": "https://example.com/generated/xxxx.png" }
  ]
}
```

* Nano Banana 与可灵返回 `url`。可灵一次生成多张时，`data` 中有多项。
* GPT Image 实测返回 `url`，同时带一个空的 `b64_json` 字段，读取时取非空的那个。

<Warning>
  生成结果是**临时链接**：GPT Image 约 24 小时失效，Nano Banana 与可灵约 7 天失效。请在拿到结果后及时下载，转存到自己的存储。
</Warning>

## 计费

* **GPT Image**：按 token 计费，包括输入文本、输入图片和输出图片的 token。尺寸越大、画质越高越贵。参考价格：1024 低画质约 ¥0.03 / 张，中画质约 ¥0.06 / 张，4K 最高画质约 ¥1.9 / 张。图片编辑另计输入图片的 token，带一张 1024 参考图、低画质约 ¥0.07 / 张。
* **Nano Banana**：按张计费，按 1K / 2K / 4K 分档。
* **可灵图片**：按张计费。`kling-image-2.1` 按文生图、单图参考、多图参考分档。

按张计费的模型按**实际生成的张数**结算，生成失败不扣费。各模型的实时单价见 [模型广场](https://token.poryf.com/pricing)，更多说明见 [价格说明](/usage)。

## 常见错误

| 错误信息 | 原因 |
| - | - |
| `prompt is required` | 缺少 `prompt` |
| `image must be an HTTP(S) URL ...` | 参考图不是 URL，或传了文件 / Base64 |
| `file uploads are not supported; pass image URLs instead` | 用 multipart 上传了文件 |
| `at most N input images are supported by this model` | 参考图数量超过该模型上限 |
| `this model generates one image per request` | 对只支持单张的模型传了 `n > 1` |
| `resolution must be one of ...` | 该模型不支持所选分辨率 |
| `aspect_ratio must be one of ...` | 该模型不支持所选比例 |
| `stream is not supported` | 图片接口不支持流式 |

其他错误见 [排错指南](/errors)。


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