Skip to content
smallPict
免费开始

图片优化处理接口

核心图片处理接口 POST /v1/optimize 的权威技术参考文档。

用于图片优化、转码、下采样缩放与尺寸调整的核心接口为：

POST https://api.smallpict.app/v1/optimize
(别名：POST https://api.smallpict.app/v1/convert)

请求格式（JSON 载荷）

HTTP
POST /v1/optimize HTTP/1.1Host: api.smallpict.appX-API-Key: sp_sdk_9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0bX-Timestamp: 1716301234X-Signature: 3a9f8b2c4d6e8a0f1b3c5d7e9f2a4b6c8d0e1f3a5b7c9d1e3f5a7b9c1d3e5f7aContent-Type: application/jsonIdempotency-Key: c9b8a7f6-e5d4-4c3b-2a1f-0e9d8c7b6a5f

请求体结构规范

JSON
{  "filename": "hero-banner.jpg",  "mime_type": "image/jpeg",  "filesize": 1654200,  "options": {    "format": "avif",    "quality": 80,    "max_dimension": 1600,    "max_width": 1920,    "max_height": 1080,    "lossless": false,    "strip_metadata": true  }}
字段类型必填说明
filenamestring是图片原始文件名（例如 banner.png）
mime_typestring是MIME 类型（例如 image/jpeg、image/png、image/webp）
filesizeinteger是文件总字节数（必须大于 0）
options.formatstring否目标格式：avif、webp、original / keep、jpg、png（默认：webp）
options.qualityinteger否压缩质量，介于 1 至 100（默认：80）
options.max_dimensioninteger否长边最大像素等比例约束阈值（例如 1600、1920、2048、2560）
options.max_widthinteger否最大宽度像素约束
options.max_heightinteger否最大高度像素约束
options.losslessboolean否开启 100% 逐像素无损压缩（默认：false）
options.strip_metadataboolean否剔除相机 EXIF 信息与色彩配置文件（默认：true）

实时图片变换查询参数

云端图片直转路由支持通过 URL 查询参数实现即时转换与缩放：

GET https://api.smallpict.app/v1/transform?url=...&format=webp&quality=80&max_dimension=1600

  • ?format=avif|webp|original
  • ?quality=1..100
  • ?max_dimension=1600
  • ?max_width=1920
  • ?max_height=1080

响应结果（200 OK）

初始化成功后，SmallPict 将返回安全的预签名直传 URL 以及异步任务跟踪标识符：

Response · 200 OK
{  "upload_url": "https://upload.smallpict.app/uploads/a1b2c3d4/hero-banner.jpg?signature=...",  "job_id": "job-a1b2c3d4",  "object_key": "uploads/a1b2c3d4/hero-banner.jpg",  "status": "queued"}

使用 HTTP PUT 请求将图片数据上传到 upload_url，然后查询任务状态。请完全按照响应返回的值使用该安全上传链接：它会在短时间内过期，且仅适用于本次上传。

查询任务处理状态

通过以下接口查询转换进度与结果：

GET https://api.smallpict.app/v1/optimize/status?job_id=job-a1b2c3d4

处理完成响应（200 OK）

Response · 200 OK
{  "job_id": "job-a1b2c3d4",  "status": "completed",  "url": "https://cdn.smallpict.app/opt/hero-banner.avif",  "format": "avif",  "bytes_saved": 1456200,  "savings_percentage": 88.03,  "created_at": "2026-08-23T08:00:00Z",  "updated_at": "2026-08-23T08:00:01Z"}