REST API 架构与接口概览
OpenAPI 3.1 权威接口规范、接入地址基准以及 SmallPict API 的核心架构原则。
SmallPict REST API 是一个完全遵循 OpenAPI 3.1 标准的高性能云服务，使开发者能够接入分布式图片压缩、格式转码与 CDN 边缘交付管线。
接口接入地址 (Base URLs)
| 运行环境 | 接入根地址 | 环境说明 |
|---|---|---|
| 正式生产环境 (Production) | https://api.smallpict.app/v1 | 全球 Anycast 加速的生产网关 |
| 本地模拟服务 (Mock Server) | http://localhost:8080/v1 | 本地单元测试与开发沙箱环境 |
核心 API 端点一览
所有受保护接口均需要携带标准 HMAC-SHA256 签名鉴权请求头（详见 鉴权规范指南）。
1. 图像压缩与转码
- 端点：
POST /v1/optimize(别名接口:POST /v1/convert) - 描述： 提交图片元数据或二进制流，执行有损/无损压缩与格式转换（AVIF, WebP, JPEG, PNG）。
2. 异步转码任务状态轮询
- 端点：
GET /v1/optimize/status?job_id={job_id} - 描述： 查询大体积图片异步转码任务的进度、节省比例与最终 CDN 下载 URL。
3. 账户配额与用量统计
- 端点：
GET /v1/quota - 描述： 实时查询当月已处理字节数、套餐限额与 CDN 边缘下行流量用量。
4. 边缘 CDN 缓存即时清除
- 端点：
POST /v1/purge - 描述： 在全球 300+ 边缘节点广播失效指定图片资源缓存。
请求与响应设计准则
- 所有接口的请求体默认采用
application/json规范（或直接二进制上传使用multipart/form-data）。 - 所有响应体均返回结构化 JSON，时间戳均遵循 RFC3339 国际标准格式。
- 所有会产生状态变更的接口（
POST,DELETE,PATCH）原生支持Idempotency-Key（UUID v4）幂等控制，网络超时重试绝不产生重复扣费。