山海万象 / SHANHAI OMNIFORM

快速开始 / Quickstart

接口接受 multipart/form-data。本地开发无需密钥或付费服务。 The API accepts multipart form data and needs no key for local development.

curl -X POST http://localhost:3000/api/v1/optimize \
  -F "image=@./photo.jpg" \
  -F "format=auto" \
  -F "width=2000" \
  -F "quality=82" \
  --output photo-optimized.webp

参数 / Parameters

imagefile

必填图像文件；验证 JPEG、PNG 或 WebP。Required image file; verified JPEG, PNG, or WebP.

formatstring

auto、original、jpeg、png 或 webp；默认 auto。

qualityinteger

有损格式画质 1–100；默认 82。Quality for lossy formats; default 82.

width / heightinteger

输出尺寸 1–20,000 像素。Output dimensions from 1–20,000 pixels.

fitstring

contain、cover 或 fill；默认 contain。

targetBytesinteger

搜索不超过该字节数的最接近结果。Search for the closest result under this byte count.

autoboolean

省略 format 时设为 false 可保留原格式。

metadatastring

用于兼容结构；编码输出会移除源文件元数据。Accepted for schema compatibility; output strips source metadata.

响应元数据 / Response metadata

成功请求会返回图像正文、Content-Type、Content-Disposition 以及以下可检查响应头。 A successful request returns the image body and these inspectable headers:

X-Original-Bytes: 4821340
X-Optimized-Bytes: 612804
X-Output-Format: webp
X-Output-Width: 2000
X-Output-Height: 1333
X-Quality: 76

验证失败时返回 JSON，例如 {"error":"Only verified JPEG, PNG, and WebP inputs are accepted."}。

示例 / Examples

浏览器 JavaScript / Browser JavaScript

const data = new FormData();
data.append('image', file);
data.append('format', 'webp');
data.append('targetBytes', '500000');

const response = await fetch('/api/v1/optimize', { method: 'POST', body: data });
if (!response.ok) throw new Error((await response.json()).error);
const optimized = await response.blob();

Node.js 22+

import { openAsBlob } from 'node:fs';
import { writeFile } from 'node:fs/promises';

const data = new FormData();
data.append('image', await openAsBlob('./photo.jpg'), 'photo.jpg');
data.append('format', 'webp');
const response = await fetch('http://localhost:3000/api/v1/optimize', { method: 'POST', body: data });
if (!response.ok) throw new Error((await response.json()).error);
await writeFile('./photo-optimized.webp', Buffer.from(await response.arrayBuffer()));

Python

import requests

with open('photo.jpg', 'rb') as image:
    response = requests.post(
        'http://localhost:3000/api/v1/optimize',
        files={'image': ('photo.jpg', image, 'image/jpeg')},
        data={'format': 'webp', 'width': 1600, 'quality': 82},
    )
response.raise_for_status()
open('photo-optimized.webp', 'wb').write(response.content)

限制与隐私 / Limits & privacy

请求只在处理期间驻留内存，不会保留。默认限制为每文件 25 MB、四千万像素、每运行实例每分钟 30 次请求；可通过 MAX_API_UPLOAD_BYTES、MAX_API_PIXELS 与 RATE_LIMIT_PER_MINUTE 配置。AVIF 输出仅用于本地浏览器流程，暂不用于此 API 适配器。 Requests live only in memory for the duration of the request and are not retained.

网页工具与 API / Web app vs. API

主优化器始终在本机处理文件，不会调用此接口；HTTP API 是用于自动化的明确服务器工作流。 The main optimizer stays local; the API is an explicit server workflow.

一次请求，完成图像优化。Image optimization in one request.