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

# gpt-image-2 模型调用教程

> 快速掌握通过 NewAPI 调用 gpt-image-2 模型的文生图与图像编辑接口

## 准备工作

在开始调用之前，请确保你已获取以下凭证：

<CardGroup cols={2}>
  <Card title="Base URL" icon="link">
    API 地址，形如：
    `https://api.onetoken.one`
  </Card>

  <Card title="API Key" icon="key">
    在 OneToken 后台生成的令牌，形如：
    `sk-xxxxxxxxxxxx`
  </Card>
</CardGroup>

***

## 1. 文生图接口 (Text to Image)

该接口用于根据你输入的文本提示词（Prompt）从零开始生成一张全新的图片。

### 请求信息

<ParamField path="POST" type="/v1/images/generations/" required>
  标准 OpenAI 兼容的图像生成路径。
</ParamField>

### 请求格式

application/json

### 请求参数

<ParamField body="model" type="string" required>
  固定填入 `gpt-image-2`。
</ParamField>

<ParamField body="prompt" type="string" required>
  描述你想要生成的图片内容，支持中英文。
</ParamField>

<ParamField body="n" type="integer" default="1">
  生成图片的数量。
</ParamField>

<ParamField body="size" type="string" default="1024x1024">
  图片分辨率，例如 `1024x1024` 或 `512x512`。宽高都要传 16 的倍数
</ParamField>

<ParamField body="quality" type="string" default="auto">
  将生成的图像的质量。`low` `medium` `high` `auto`
</ParamField>

### 代码示例

<CodeGroup>
  ```bash cURL theme={null}
  curl [https://api.onetoken.one/v1/images/generations/](https://api.onetoken.one/v1/images/generations) \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer sk-xxxxxxxxxxxx" \
    -d '{
      "model": "gpt-image-2",
      "prompt": "A futuristic city with flying cars at sunset, cyberpunk style, highly detailed",
      "n": 1,
      "size": "1024x1024"
    }'

  ```

  ```python Python theme={null}
  import requests

  url = "[https://api.onetoken.one/v1/images/generations/](https://api.onetoken.one/v1/images/generations)"
  headers = {
      "Content-Type": "application/json",
      "Authorization": "Bearer sk-xxxxxxxxxxxx"
  }
  data = {
      "model": "gpt-image-2",
      "prompt": "一只戴着墨镜在海滩度假的可爱猫咪",
      "n": 1,
      "size": "1024x1024"
  }

  response = requests.post(url, json=data, headers=headers)
  print(response.json())

  ```
</CodeGroup>

***

## 2. 图像编辑接口 (Image Edits)

该接口用于对现有的图片进行修改。你需要提供一张**原图**，以及一张**掩码图（Mask）**（掩码图中透明的区域代表需要被修改/替换的地方）。

### 请求信息

<ParamField path="POST" type="/v1/images/edits/" required>
  标准 OpenAI 兼容的图像编辑路径。
</ParamField>

### 请求格式

multipart/form-data

### 请求参数

<ParamField body="model" type="string" required>
  固定填入 `gpt-image-2`。
</ParamField>

<ParamField body="prompt" type="string" required>
  描述你想要生成的图片内容，支持中英文。
</ParamField>

<ParamField body="n" type="integer" default="1">
  生成图片的数量。
</ParamField>

<ParamField body="size" type="string" default="1024x1024">
  图片分辨率，例如 `1024x1024` 或 `512x512`。宽高都要传 16 的倍数
</ParamField>

<ParamField body="response_format" type="string" default="b64_json">
  生成的图像返回的格式。必须是url或b64\_json。
</ParamField>

<ParamField body="image" type="file" default="">
  要编辑的图像。理论支持最多 16 张
</ParamField>

### 代码示例

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.onetoken.one/v1/images/edits/" \
    -H "Authorization: Bearer " \
    -F image="cmMtdXBsb2FkLTE2ODc4MzMzNDc3NTEtMjA=/31225951_59371037e9_small.png" \
    -F prompt="A cute baby sea otter wearing a beret."

  ```

  ```python Python theme={null}
  import requests

  url = "https://api.onetoken.one/v1/images/edits/"
  body = {
    "image": "cmMtdXBsb2FkLTE2ODc4MzMzNDc3NTEtMjA=/31225951_59371037e9_small.png",
    "prompt": "A cute baby sea otter wearing a beret."
  }
  response = requests.request("POST", url, data = body, headers = {
    "Content-Type": "multipart/form-data",
    "Authorization": "Bearer "
  })

  print(response.text)

  ```

  ```javascript javascript theme={null}
  const body = new FormData();
  body.append(image, "file1.png");
  body.append(image, "file2.png");
  body.append(prompt, "A cute baby sea otter wearing a beret.");

  fetch("https://api.onetoken.one/v1/images/edits/", {
    method: "POST",
    headers: {
      "Content-Type": "multipart/form-data",
      Authorization: "Bearer ",
    },
    body,
  });
  ```
</CodeGroup>

***

## 3. 返回数据结构

接口调用成功后，会返回一个包含图片 URL 的 JSON 对象。

### 成功响应示例

```json theme={null}
{
  "created": 1718112345,
  "data": [
    {
      // 根据 response_format 字段
      // "url": "[https://cdn.your-domain.com/images/abc123xyz.png](https://cdn.your-domain.com/images/abc123xyz.png)",
      "b64_json": "xxx"
    }
  ]
}
```

## 4. 常用尺寸

1. 正方形与近正方形比例

1:1

1K: 1024 × 1024

2K: 2048 × 2048

4K: 4096 × 4096

5:4

1K: 1280 × 1024

2K: 2000 × 1600 或 2080 × 1664

4K: 4000 × 3200 或 4080 × 3264

4:5

1K: 1024 × 1280

2K: 1600 × 2000 或 1664 × 2080

4K: 3200 × 4000 或 3264 × 4080

2. 传统经典画幅比例

4:3

1K: 1024 × 768

2K: 2048 × 1536

4K: 3840 × 2880 或 4096 × 3072

3:4

1K: 768 × 1024

2K: 1536 × 2048

4K: 2880 × 3840 或 3072 × 4096

3:2

1K: 1152 × 768

2K: 2160 × 1440

4K: 3840 × 2560 或 4080 × 2720

2:3

1K: 768 × 1152

2K: 1440 × 2160

4K: 2560 × 3840 或 2720 × 4080

3. 宽屏与超宽屏比例

16:9

1K: 1024 × 576

2K: 2048 × 1152

4K: 3840 × 2160 (注：标准的 4K UHD 完美满足 16:9 且宽高均为 16 的倍数)

9:16

1K: 576 × 1024

2K: 1152 × 2048

4K: 2160 × 3840

21:9 (等同于最简整数比 7:3)

1K: 1008 × 432 或 1120 × 480

2K: 2016 × 864 或 2128 × 912

4K: 3808 × 1632 或 4032 × 1728

9:21 (等同于最简整数比 3:7)

1K: 432 × 1008 或 480 × 1120

2K: 864 × 2016 或 912 × 2128

4K: 1632 × 3808 或 1728 × 4032