# img2svg API 文档

## 概述

img2svg 提供图片转 SVG 的 HTTP API，支持两种调用方式：

1. **Web 转换**：`POST /api/convert`，可选登录，登录后记录历史
2. **API 转换**：`POST /api/v1/convert`，需 API Key 鉴权，按次数计费

## 认证

### API Key 认证

调用 `/api/v1/convert` 时，需在请求头中携带 API Key：

```
Authorization: Bearer imgsk-xxxxxxxx
```

API Key 通过 Web 控制台创建，创建后仅显示一次，请妥善保存。

## 接口说明

### POST /api/v1/convert

将图片转换为 SVG，需 API Key 认证。

**请求**

- **Content-Type**：`multipart/form-data`
- **Headers**：`Authorization: Bearer <your-api-key>`

| 参数 | 类型 | 必填 | 默认 | 说明 |
|------|------|------|------|------|
| file | File | 是 | - | 图片文件（PNG/JPG/WebP/BMP），最大 20MB |
| keep_dark | string | 否 | true | 是否提取黑色轮廓叠加 |
| dark_threshold | string | 否 | 60 | 黑色判定阈值 (0-255)，值越大线越粗 |
| layering | string | 否 | true | 是否按颜色分层 |

**响应**

- **200 OK**：成功，返回 `Content-Type: image/svg+xml` 的 SVG 内容
- **401 Unauthorized**：API Key 无效或未提供
- **429 Too Many Requests**：配额不足
- **400 Bad Request**：缺少文件或参数错误

**示例**

```bash
curl -X POST 'https://your-domain.com/api/v1/convert' \
  -H 'Authorization: Bearer imgsk-your-api-key' \
  -F 'file=@input.png' \
  -F 'keep_dark=true' \
  -F 'dark_threshold=60' \
  -o output.svg
```

## 错误码

| HTTP 状态码 | 说明 |
|-------------|------|
| 200 | 成功 |
| 400 | 请求参数错误（如缺少 file） |
| 401 | 未认证或 API Key 无效 |
| 413 | 文件过大（最大 20MB） |
| 429 | API 配额不足，请充值 |
| 503 | 服务暂不可用（如数据库未配置） |