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

# GPT Image 2

> OpenAI GPT Image 2 图像生成，支持文生图、多图参考与 1K / 2K / 4K 输出。

* 异步接口：提交后立即返回 `task_id`，再调用 [查询图片任务](/api-reference/images/task-status) 获取结果。
* 不传 `image_urls` 为文生图；传入 `image_urls` 自动切换为图生图 / 参考图编辑。
* 按张计费，单价由分辨率档位决定，见 [模型价格](https://nodylink.com/pricing)。任务失败自动退款。

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.nodylink.com/v1/images/generations \
    -H "Authorization: Bearer sk-你的密钥" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2",
      "prompt": "一只橘猫坐在窗台上看夕阳，水彩画风格",
      "size": "16:9",
      "resolution": "2k"
    }'
  ```

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

  API_KEY = "sk-你的密钥"
  BASE = "https://api.nodylink.com"
  headers = {"Authorization": f"Bearer {API_KEY}"}

  submit = requests.post(
      f"{BASE}/v1/images/generations",
      headers=headers,
      json={
          "model": "gpt-image-2",
          "prompt": "一只橘猫坐在窗台上看夕阳，水彩画风格",
          "size": "16:9",
          "resolution": "2k",
      },
  ).json()
  task_id = submit["task_id"]

  while True:
      task = requests.get(f"{BASE}/v1/images/tasks/{task_id}", headers=headers).json()
      if task["status"] == "SUCCESS":
          print(task["data"][0]["url"])
          break
      if task["status"] == "FAILED":
          raise RuntimeError(task["fail_reason"])
      time.sleep(5)
  ```

  ```javascript Node.js theme={null}
  const API_KEY = "sk-你的密钥";
  const BASE = "https://api.nodylink.com";
  const headers = {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  };

  const submit = await fetch(`${BASE}/v1/images/generations`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      model: "gpt-image-2",
      prompt: "一只橘猫坐在窗台上看夕阳，水彩画风格",
      size: "16:9",
      resolution: "2k",
    }),
  }).then((r) => r.json());

  while (true) {
    const task = await fetch(`${BASE}/v1/images/tasks/${submit.task_id}`, { headers })
      .then((r) => r.json());
    if (task.status === "SUCCESS") {
      console.log(task.data[0].url);
      break;
    }
    if (task.status === "FAILED") throw new Error(task.fail_reason);
    await new Promise((r) => setTimeout(r, 5000));
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "status": "submitted",
    "task_id": "3f6c1b2a-8d4e-4f7a-9c21-5b0e7d9a1c34",
    "id": "3f6c1b2a-8d4e-4f7a-9c21-5b0e7d9a1c34"
  }
  ```

  ```json 400 theme={null}
  {
    "code": "invalid_request",
    "message": "prompt is required",
    "data": null
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "message": "用户额度不足, 剩余额度: ¥0.012 (request id: 2026101412000012345678)",
      "type": "new_api_error",
      "param": "",
      "code": "insufficient_user_quota"
    }
  }
  ```
</ResponseExample>

## 鉴权

<ParamField header="Authorization" type="string" required>
  `Bearer <API Key>`。在 [API 密钥](https://nodylink.com/dashboard/keys) 页面创建。
</ParamField>

## 请求参数

<ParamField body="model" type="string" required default="gpt-image-2">
  模型 ID，填 `gpt-image-2`。其他变体以 [模型广场](https://nodylink.com/market) 为准。
</ParamField>

<ParamField body="prompt" type="string" required>
  图像描述，支持中英文。建议写清主体、场景、构图、风格和光线。
</ParamField>

<ParamField body="size" type="string" default="1:1">
  输出比例，或精确像素尺寸。

  支持 15 种比例：`1:1`、`3:2`、`2:3`、`4:3`、`3:4`、`5:4`、`4:5`、`16:9`、`9:16`、`2:1`、`1:2`、`21:9`、`9:21`、`3:1`、`1:3`。

  也可以直接传像素尺寸，例如 `2048x1152`，此时忽略 `resolution`。
</ParamField>

<ParamField body="resolution" type="string" default="1k">
  分辨率档位：`1k`、`2k` 或 `4k`，大小写均可。与比例形式的 `size` 一起决定实际像素，见下方对照表。
</ParamField>

<ParamField body="image_urls" type="string[]">
  参考图列表，传入后为图生图 / 参考图编辑模式。

  <Expandable title="详细说明">
    * 每项可以是公网可访问的图片 URL，也可以是 `data:image/png;base64,...` 格式的 Data URL，二者可以混填。
    * 建议不超过 15 张，单张不超过 20 MB。
    * 图片 URL 需要无需登录即可直接下载，签名链接的有效期要覆盖任务执行时间。
  </Expandable>
</ParamField>

## 尺寸对照表

`size` 与 `resolution` 组合后的实际输出像素：

| `size` | `1k` | `2k` | `4k` |
| - | - | - | - |
| `1:1` | 1248×1248 | 2048×2048 | 2880×2880 |
| `16:9` | 1680×944 | 2048×1152 | 3840×2160 |
| `9:16` | 944×1680 | 1152×2048 | 2160×3840 |
| `4:3` | 1024×768 | 2048×1536 | 3312×2480 |
| `3:4` | 768×1024 | 1536×2048 | 2480×3312 |
| `3:2` | 1536×1024 | 2048×1360 | 3520×2336 |
| `2:3` | 1024×1536 | 1360×2048 | 2336×3520 |
| `5:4` | 1440×1088 | 2560×2048 | 3216×2576 |
| `4:5` | 1120×1408 | 2048×2560 | 2576×3216 |
| `21:9` | 1920×816 | 2688×1152 | 3840×1648 |
| `9:21` | 816×1920 | 1152×2688 | 1648×3840 |
| `2:1` | 1776×880 | 2688×1344 | 3840×1920 |
| `1:2` | 880×1776 | 1344×2688 | 1920×3840 |
| `3:1` | 1536×512 | 3072×1024 | 3840×1280 |
| `1:3` | 512×1536 | 1024×3072 | 1280×3840 |

<Note>
  直接传像素尺寸时，计费档位按总像素数确定：不超过 1680×944 记为 1K，不超过 2560×2048 记为 2K，其余记为 4K。
</Note>

## 提交响应

<ResponseField name="code" type="integer">
  固定为 `200`。
</ResponseField>

<ResponseField name="status" type="string">
  固定为 `submitted`。
</ResponseField>

<ResponseField name="task_id" type="string">
  任务 ID，用于 [查询图片任务](/api-reference/images/task-status)。
</ResponseField>

<ResponseField name="id" type="string">
  与 `task_id` 相同。
</ResponseField>

## 使用示例

**文生图（最简请求）**

```json theme={null}
{
  "model": "gpt-image-2",
  "prompt": "一只橘猫坐在窗台上看夕阳，水彩画风格"
}
```

**4K 横版海报**

```json theme={null}
{
  "model": "gpt-image-2",
  "prompt": "星空下的古老城堡，电影感光影",
  "size": "16:9",
  "resolution": "4k"
}
```

**图生图（参考图 URL）**

```json theme={null}
{
  "model": "gpt-image-2",
  "prompt": "把这张照片变成水彩画风格",
  "image_urls": ["https://example.com/photo.jpg"]
}
```

**多图融合（URL 与 Base64 混填）**

```json theme={null}
{
  "model": "gpt-image-2",
  "prompt": "把这两张照片融合成一张海报",
  "size": "4:3",
  "resolution": "2k",
  "image_urls": [
    "https://example.com/photo-a.jpg",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ]
}
```

## 查询结果

```bash theme={null}
curl https://api.nodylink.com/v1/images/tasks/3f6c1b2a-8d4e-4f7a-9c21-5b0e7d9a1c34 \
  -H "Authorization: Bearer sk-你的密钥"
```

```json theme={null}
{
  "status": "SUCCESS",
  "task_id": "3f6c1b2a-8d4e-4f7a-9c21-5b0e7d9a1c34",
  "progress": "100%",
  "created": 1792000060,
  "data": [
    {"url": "https://example.com/generated/3f6c1b2a.png"}
  ]
}
```

取图方式：`data[0].url`。状态说明见 [查询图片任务](/api-reference/images/task-status)。


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