# 生成图片API文档

本文件介绍本平台图片生成、图片编辑、异步任务查询、完成通知和图片下载，可交给 AI 编程助手完成接入。

## 接入前准备

- API 接入地址：`https://geekapi.net`，本文中的接口地址已按下载站点填写。
- 接入密钥：将示例中的 `sk-你的令牌` 替换为“接入密钥”页面显示的完整密钥。
- 模型值：示例使用 `aik-image-2`；请从模型列表复制当前可用的 `name`，不要使用显示名称。
- 图片比例、尺寸、数量和参考图限制以所选模型及线路的有效规则为准。

可查看当前模型目录：

```bash
curl 'https://geekapi.net/api/platform/model-catalog?scope=enabled' \
  -H 'Authorization: Bearer sk-你的令牌'
```

交给 AI 编程助手时，请它先阅读你的项目，再完成提交、保存任务 ID、等待结果、失败提示和结果保存。真实密钥应由接入方配置，不要写入源码、日志或公开网页。

## 文生图

```http
POST /v1/images/generations
Authorization: Bearer sk-你的令牌
Content-Type: application/json
```

```bash
curl https://geekapi.net/v1/images/generations \
  -H 'Authorization: Bearer sk-你的令牌' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "aik-image-2",
    "prompt": "未来城市夜景，电影感，高细节",
    "size": "1024x1024",
    "quality": "medium",
    "n": 1
  }'
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `model` | string | 必填，平台公开模型值。 |
| `prompt` | string | 必填，图片描述或编辑要求。 |
| `size` | string | 输出尺寸，如 `1024x1024`；支持范围由模型决定。 |
| `quality` | string | 画质参数，与输出尺寸独立；支持范围由模型决定。 |
| `n` | number | 生成数量，不能超过模型限制。 |
| `image` | string | 参考图 URL，是否支持由模型决定。 |
| `callback_url` | string | 可选，接收图片任务终态通知的公网 HTTPS 地址。 |

费用会根据实际模型、线路和输出尺寸计算。已配置分辨率价格表却没有匹配尺寸价格时，请求会被拒绝；不要把 `quality` 当作尺寸字段。

## 图片编辑

支持图片编辑的模型可通过生成接口传入参考图：

```bash
curl https://geekapi.net/v1/images/generations \
  -H 'Authorization: Bearer sk-你的令牌' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "aik-image-2",
    "prompt": "保持主体不变，改成清晨自然光",
    "image": "https://your-service.example/input.png",
    "size": "1024x1024"
  }'
```

需要兼容 OpenAI 图片编辑客户端时，也可使用 `POST /v1/images/edits`。参考图必须可供平台读取；图片编辑、多图和蒙版能力以当前模型规则为准。

## 判断同步结果或异步任务

部分模型直接返回 OpenAI 图片结果：

```json
{
  "data": [{ "url": "https://your-service.example/result.png" }]
}
```

读取 `data[].url`；如果返回 `data[].b64_json`，先解码 Base64 再保存图片。

异步创建可能返回 HTTP `202`：

```json
{
  "task_id": "task_image_xxx",
  "status": "QUEUED",
  "client_request_id": "request_xxx"
}
```

先持久化 `task_id` 和 `client_request_id`，再查询任务；创建响应不代表图片已经生成。

## 查询任务

```bash
curl https://geekapi.net/v1/images/tasks/task_image_xxx \
  -H 'Authorization: Bearer sk-你的令牌'
```

任务状态使用大写值：`QUEUED`、`IN_PROGRESS`、`SUCCESS`、`FAILURE`。

- `SUCCESS`：读取响应中的 `data.data[].url` 或 `result_url`，保存最终图片。
- `FAILURE`：显示 `fail_reason` 并停止等待。
- 其他非终态：每 60 秒查询一次；应用回到前台或网络恢复后可立即查询。
- 有 `client_request_id` 但未拿到任务 ID 时，可请求 `GET /v1/images/tasks?client_request_id={client_request_id}` 找回。

## 任务完成通知（可选）

有自己的服务器时，可在创建 JSON 中加入：

```json
{
  "callback_url": "https://your-service.example/image-callback"
}
```

平台在终态后向该地址发送 JSON `POST`，通知包含 `task_id`、`status`、`client_request_id`，不包含完整图片。请求头 `X-Image-Event-Id` 是稳定通知编号，可据此去重。接收接口尽快返回 `2xx`；发送失败最多尝试 5 次。

通知没有签名或密钥。先确认任务属于自己，再用接入密钥调用任务查询接口核实结果。没有公网 HTTPS 接收服务的客户端可以省略 `callback_url`，继续每 60 秒查询。

## 下载图片与错误处理

取得最终图片 URL 后，可将其作为文件下载地址：

```bash
curl --fail --location 'https://your-service.example/result.png' -o result.png
```

结果地址来自任务响应，不能用本示例占位符；下载结果文件时不要把平台接入密钥发送到素材域名。签名链接过期时重新查询任务，取得可用地址后及时保存。

`400` 应检查模型和参数，`401` 应检查完整密钥，`402` 应检查余额，`429` 应降低频率。超时、网络错误或 `5xx` 不代表生成失败；已有任务 ID 时继续查询，不要重新创建同一任务。