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

# 概览

> 在 API Playground 中查看当前 GPT-image-2 接口，并为后续异步模式预留独立分组。

SmewAI 提供 OpenAI 兼容的图片 API，服务端点为 `https://smew.ai`。

这一组参考文档会刻意拆成两层：

* 同步模式：`gpt-image-2`
* 异步模式：后续补充

你现在可以直接在本节的 API Playground 中调用当前的 `gpt-image-2` 模型。

## 适合怎么使用这一页

这一页更适合作为一份**整合说明**来使用，尤其适合下面几种场景：

* 直接复制给 AI，让它帮你生成第三方系统接入代码
* 复制给研发同事，快速说明当前图片接口怎么调用
* 先用 `POST` 接口做调试，再接入你自己的服务端

如果你的目标是把 SmewAI 的生图和编辑图能力接到外部系统里，通常复制这一页会比只给单个接口页更方便。

## 调用前准备

1. 前往 [https://smew.ai/keys](https://smew.ai/keys) 创建 API Key。
2. 在 Playground 中点击 **Authorize**，以 Bearer Token 方式填入你的 Key。
3. 直接调用 `POST /v1/images/generations` 获取同步返回结果。

<Tip>
  新接入请优先使用 `/v1/images/generations`。`/images/generations` 只是兼容别名。
</Tip>

## 当前同步模式包含什么

当前同步模式主要包含两个 `POST` 接口：

### 1. `POST /v1/images/generations`

适合做：

* 文生图
* 基于提示词直接生成图片
* 接入网站、机器人、工作流系统后做同步返回

调用特点：

* 结果同步返回
* 非常适合先在 Playground、curl、Postman 里调试
* 调通后很方便让 AI 改写成 Python、Node.js、Java、Go 或第三方系统代码

### 2. `POST /v1/images/edits`

适合做：

* 编辑图片
* 图生图
* 遮罩修改
* 背景替换

调用特点：

* 同样使用 `POST`
* 支持 JSON 的 `image_url` 方式
* 也支持 multipart form-data 上传本地文件

## 可直接复制给 AI 的接入说明

如果你要对接第三方系统，可以先把下面这段直接复制给 AI：

```text theme={null}
请基于 SmewAI 的 OpenAI 兼容图片接口，帮我接入第三方系统。

服务端点：
https://smew.ai

鉴权方式：
Authorization: Bearer <API_KEY>

当前同步接口：
1. POST /v1/images/generations
   - 用于文生图
   - 模型名固定使用 gpt-image-2
   - 同步返回结果

2. POST /v1/images/edits
   - 用于编辑图片、图生图、遮罩修改、背景替换
   - 支持 JSON 请求中的 image_url
   - 也支持 multipart form-data 文件上传

请优先给我服务端集成示例代码，并保留 curl 调试版本。
```

## 当前已整理的最小调试工作流

先用下面这份请求体调试 `POST /v1/images/generations`：

```json theme={null}
{
  "model": "gpt-image-2",
  "prompt": "一只干净风格的橘猫宇航员贴纸，背景为柔和粉彩色。",
  "n": 1,
  "size": "1:1",
  "resolution": "2k"
}
```

## 为什么 `POST` 方式也适合正式集成

对接第三方系统时，`POST` 方式有两个好处：

* 可以先在 Playground、curl、Postman 中验证请求是否正确
* 验证通过后，再把同样的请求结构迁移到你自己的后端逻辑

也就是说，**`POST` 方式既适合调试，也适合真实集成。**

## 当前返回结果说明

* `POST /v1/images/generations` 在同步模式下直接返回图片结果。
* `POST /v1/images/edits` 同时支持 JSON 的 `image_url` 方式和 multipart 文件上传。

## 后续异步模式

后续会单独补充异步模式文档，避免当前 `gpt-image-2` 的请求结构和未来异步工作流混在同一层导航里。

<Card title="中文快速指南" icon="languages" href="/gpt-image-quickstart">
  查看 curl 和 Python 的中文示例
</Card>