<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 九宫格切图

> 上传一张图片（multipart 文件 / base64 / URL 三选一），自动居中裁切为正方形后均分为 N×N 宫格小图，按朋友圈发图顺序返回（左到右、上到下编号 1..N²）。支持 2×2 / 3×3 / 4×4，可设置切片间留白，输出 base64 数组或直接下载 zip。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `nine-grid-cutter` |
| 接口名称 | 九宫格切图 |
| 接口地址 | `https://v1.apizero.cn/api/nine-grid-cutter` |
| 请求方法 | `POST` |
| 分类 | dev |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 2 req/s |
| 每日免费额度 | 50 次（已认证用户） |
| 匿名每日额度 | 20 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

匿名可调用：QPS 1 / 每日 20 次。登录用户：QPS 2 / 每日 50 次。图像处理消耗资源较大。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `file` | `file` | 否 | 图片文件（multipart 上传，三选一之一），支持 jpg/png/webp/gif | — |
| `image_base64` | `string` | 否 | 图片 base64（dataURL 或纯 base64，三选一） | — |
| `image_url` | `string` | 否 | 公网图片 URL（http/https，三选一） | — |
| `grid` | `number` | 否 | 宫格数：2 / 3 / 4，默认 3 | `3` |
| `gap` | `number` | 否 | 切片间留白像素 0-20，默认 0 | `0` |
| `output` | `string` | 否 | 输出格式：base64（默认，JSON）/ zip（直接返回 application/zip） | `base64` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | — | — |

## 5. 请求示例 (cURL)

```bash
curl -X POST "https://v1.apizero.cn/api/nine-grid-cutter" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "file": "<file>",
  "image_base64": "<image_base64>",
  "image_url": "<image_url>",
  "grid": "3",
  "gap": "0",
  "output": "base64"
}'
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `grid` | `string` | 实际宫格规格，如 "3x3" | — |
| `total` | `number` | 切片总数（grid×grid） | — |
| `gap` | `number` | 切片间留白像素 | — |
| `original_size` | `string` | 原图尺寸 W×H | — |
| `square_side` | `number` | 居中裁切的正方形边长 | — |
| `cell_size` | `string` | 每张切片尺寸（含 gap 后的实际像素） | — |
| `source` | `string` | 输入来源：multipart / base64 / url | — |
| `pieces` | `array` | 切片数组，每项含 index / size / base64 / data_url（可直接 <img src=> 用） | — |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "grid": "3x3",
        "total": 9,
        "gap": 0,
        "original_size": "1080x1920",
        "square_side": 1080,
        "cell_size": "360x360",
        "source": "multipart",
        "pieces": [
            {
                "index": 1,
                "size": "360x360",
                "base64": "iVBORw0K...",
                "data_url": "data:image\/png;base64,iVBORw0K..."
            },
            {
                "index": 2,
                "size": "360x360",
                "base64": "...",
                "data_url": "..."
            }
        ]
    },
    "request_id": "abc123"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `—` | 未上传图片 / 图片格式不支持 / 文件超大 / grid 或 gap 越界 |
| `4029` | `—` | 调用过快（QPS 超限） |
| `4030` | `—` | 今日额度用完 |
| `5020` | `—` | image_url 下载失败 |
| `5000` | `—` | 服务端 Imagick 处理失败 |

## 9. 变更日志

- **1.0.0** (2026-05-10)
  - 首次上线，支持 multipart/base64/url 三种输入，输出 base64 或 zip

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/nine-grid-cutter`

Source: `https://apizero.cn/aidocs/nine-grid-cutter/raw.md`
Last updated: 2026-05-11T16:15:07+08:00