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

# Images

> 在平台上使用 gpt-image-2 进行图像生成与编辑。

本平台与 OpenAI 图像接口完全兼容：把 `base_url` 指向平台域名、API Key 换成平台 token，原本跑 OpenAI 的代码无需改动即可运行。

## 快速开始

```bash theme={null}
curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A futuristic skyline at dusk",
    "size": "1024x1024"
  }'
```

官方 Python SDK：

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

client = OpenAI(base_url="$BASE_URL/v1", api_key="$TOKEN")

result = client.images.generate(
    model="gpt-image-2",
    prompt="A futuristic skyline at dusk",
    size="1024x1024",
    quality="medium",
)
print(result.data[0].b64_json)
```

## 文生图 `/v1/images/generations`

已验证稳定的请求参数：

| 参数                          | 取值                                               |
| --------------------------- | ------------------------------------------------ |
| `size`                      | `1024x1024` / `1024x1536` / `1536x1024` / `auto` |
| `quality`                   | `low` / `medium` / `high` / `auto`               |
| `background`                | `transparent` / `opaque` / `auto`                |
| `output_format`             | `png` / `jpeg`                                   |
| `output_compression`        | 0–100（仅对 `jpeg` 生效）                              |
| `moderation` / `n` / `user` | 同 OpenAI 官方                                      |

<Callout type="warning">
  `output_format=webp`、`stream=true`、`partial_images` 为官方字段，但平台尚未完成验证，使用前请自行实测。
</Callout>

## 返回格式：URL 还是 base64

平台默认返回 `b64_json`。如果你希望直接拿到图片 URL，加上 `response_format=url`：

```bash theme={null}
curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean studio product photo of a matte white ceramic mug",
    "size": "1024x1024",
    "quality": "low",
    "response_format": "url"
  }'
```

平台会按以下顺序处理：

1. 优先按 `response_format=url` 透传请求；
2. 若该参数被拒绝，自动回退为默认请求重试一次；
3. 得到 `b64_json` 后，若平台已配置对象存储，自动转存为 URL 写入 `data[0].url`；
4. 若未配置对象存储且无法直接得到 URL，返回明确错误（如 `image_url_not_available`），**不会**把 `b64_json` 当作 URL 静默降级。

## 改图 `/v1/images/edits`

推荐使用 JSON 请求体，通过 `images[].image_url` 指定底图：

```bash theme={null}
curl -X POST "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "换种风格",
    "size": "1024x1024",
    "quality": "medium",
    "images": [
      { "image_url": "https://example.com/base-image.png" }
    ]
  }'
```

同时兼容 multipart 上传，方便迁移老代码：

```bash theme={null}
curl -X POST "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gpt-image-2" \
  -F "image=@base.png" \
  -F "mask=@mask.png" \
  -F "prompt=在天空中加入热气球"
```

<Callout type="info">
  新项目建议优先使用 JSON 形态；已有 multipart 客户端可保持不变。
</Callout>

## 计费

`gpt-image-2` 按输入 / 输出 token 结算：

* text input：`$5.00 / 1M tokens`
* cached text input：`$1.25 / 1M tokens`
* image input：`$8.00 / 1M tokens`
* image output：`$30.00 / 1M tokens`

单张预估参考（便于前端展示，实际仍按 token 结算）：

| size                      | low     | medium  | high    |
| ------------------------- | ------- | ------- | ------- |
| `1024x1024`               | \$0.006 | \$0.053 | \$0.211 |
| `1024x1536` / `1536x1024` | \$0.005 | \$0.041 | \$0.165 |

平台实际售价与折扣以控制台「模型价格」页面为准。