免费图片压缩、格式转换与异步处理 API

在线压缩与转换图片

任务提交后会显示队列位置、处理阶段和进度；完成后由受保护的接口下载结果。

为什么采用异步图片转换

异步 API：三步完成转换

1. 提交文件

curl -X POST 'https://www.livetops.com/tools/img-api.php?action=submit&lang=zh' \
  -F 'image=@photo.jpg' \
  -F 'format=webp' \
  -F 'quality=82' \
  -F 'max_side=1600'

响应为 HTTP 202。access_token 只在创建响应中返回一次，请安全保存，不要写入公开日志。

2. 查询进度

curl 'https://www.livetops.com/tools/img-api.php?action=status&id=j_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&lang=zh' \
  -H 'Authorization: Bearer YOUR_JOB_ACCESS_TOKEN'

3. 下载结果

curl -L 'https://www.livetops.com/tools/img-api.php?action=download&id=j_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Authorization: Bearer YOUR_JOB_ACCESS_TOKEN' \
  -o result.webp

输入模式

multipart/form-data

# 单图字段 image；批量字段 images[]curl -X POST 'https://www.livetops.com/tools/img-api.php?action=submit' \
  -F 'images[]=@a.jpg' \
  -F 'images[]=@b.png' \
  -F 'format=webp'

JSON 远程 URL

{
  "image_url": "https://example.com/photo.jpg",
  "format": "webp",
  "quality": 82,
  "max_side": 1600
}

多个远程 URL

{
  "image_urls": [
    "https://example.com/a.jpg",
    "https://example.com/b.png"
  ],
  "format": "webp",
  "quality": 80
}

Base64 / Data URL

{
  "image_base64": "data:image/png;base64,iVBORw0KGgoAAA...",
  "format": "jpeg",
  "background": "#ffffff"
}

原始二进制请求体

curl -X POST 'https://www.livetops.com/tools/img-api.php?action=submit&format=png' \
  -H 'Content-Type: image/jpeg' \
  --data-binary '@photo.jpg'

任务状态与响应结构

queued → processing → completed，也可能结束为 partially_completed、failed、cancelled、expired。

HTTP 202 创建响应

{
  "success": true,
  "request_id": "r_...",
  "job": {
    "id": "j_...",
    "status": "queued",
    "stage": "waiting",
    "progress": 5,
    "poll_after_ms": 2000,
    "expires_at": "...",
    "links": {"status": "...", "download": "...", "cancel": "..."}
  },
  "access_token": "..."
}

处理中响应

{
  "success": true,
  "job": {
    "status": "processing",
    "stage": "encoding",
    "progress": 72,
    "queue_position": 0,
    "total_items": 3,
    "completed_items": 2,
    "failed_items": 0,
    "download_ready": false
  }
}

标准错误

{
  "success": false,
  "request_id": "r_...",
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "...",
    "details": {"max_bytes": 25165824}
  }
}

客户端应以 error.code 和 HTTP 状态码为主要判断依据，不要依赖可能本地化的 message 文本。progress 是任务阶段进度，并非底层编码器的逐字节精确进度。

完整客户端示例

JavaScript / TypeScript

async function convertImage(file) {
  const form = new FormData();
  form.append('image', file);
  form.append('format', 'webp');
  form.append('quality', '82');

  const createdResponse = await fetch('https://www.livetops.com/tools/img-api.php?action=submit', {
    method: 'POST', body: form
  });
  const created = await createdResponse.json();
  if (!createdResponse.ok) throw new Error(created.error?.code || 'SUBMIT_FAILED');

  const headers = { Authorization: `Bearer ${created.access_token}` };
  let job = created.job;
  while (!['completed','partially_completed','failed','cancelled','expired'].includes(job.status)) {
    await new Promise(r => setTimeout(r, job.poll_after_ms || 2000));
    const response = await fetch(job.links.status, { headers, cache: 'no-store' });
    const payload = await response.json();
    if (!response.ok) throw new Error(payload.error?.code || 'STATUS_FAILED');
    job = payload.job;
  }
  if (!job.download_ready) throw new Error(job.error?.code || job.status);
  const result = await fetch(job.links.download, { headers });
  if (!result.ok) throw new Error('DOWNLOAD_FAILED');
  return await result.blob();
}

Python requests

import time
import requests

with open("photo.jpg", "rb") as image:
    response = requests.post(
        "https://www.livetops.com/tools/img-api.php?action=submit",
        files={"image": ("photo.jpg", image, "image/jpeg")},
        data={"format": "webp", "quality": 82, "max_side": 1600},
        timeout=60,
    )
response.raise_for_status()
created = response.json()
headers = {"Authorization": f"Bearer {created['access_token']}"}
job = created["job"]

while job["status"] not in {"completed", "partially_completed", "failed", "cancelled", "expired"}:
    time.sleep(job.get("poll_after_ms", 2000) / 1000)
    status = requests.get(job["links"]["status"], headers=headers, timeout=30)
    status.raise_for_status()
    job = status.json()["job"]

if not job.get("download_ready"):
    raise RuntimeError(job.get("error", {}).get("code", job["status"]))
result = requests.get(job["links"]["download"], headers=headers, timeout=120)
result.raise_for_status()
open("result.webp", "wb").write(result.content)

PHP cURL

<?php
$ch = curl_init('https://www.livetops.com/tools/img-api.php?action=submit');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'image' => new CURLFile('/path/photo.jpg', 'image/jpeg', 'photo.jpg'),
        'format' => 'webp',
        'quality' => 82,
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
]);
$created = json_decode(curl_exec($ch), true, 512, JSON_THROW_ON_ERROR);
curl_close($ch);
$job = $created['job'];
$token = $created['access_token'];
// 按 job.poll_after_ms 轮询 job.links.status，完成后携带 Bearer token 下载。

Node.js 18+

import { openAsBlob } from 'node:fs';
const form = new FormData();
form.set('image', await openAsBlob('photo.jpg'));
form.set('format', 'webp');
const created = await fetch('https://www.livetops.com/tools/img-api.php?action=submit', { method: 'POST', body: form }).then(r => r.json());
const headers = { Authorization: `Bearer ${created.access_token}` };

Go

// 使用 mime/multipart 创建 image 字段，POST 到 action=submit。
// 保存响应中的 job.id 和 access_token；后续 GET status/download 时设置：
req.Header.Set("Authorization", "Bearer " + accessToken)

Java 11+

// 使用 HttpClient 发送 multipart 请求创建任务。
// 状态与下载请求：
HttpRequest request = HttpRequest.newBuilder(URI.create(statusUrl))
    .header("Authorization", "Bearer " + accessToken)
    .GET().build();

C# / .NET

using var form = new MultipartFormDataContent();
form.Add(new StreamContent(File.OpenRead("photo.jpg")), "image", "photo.jpg");
form.Add(new StringContent("webp"), "format");
var created = await http.PostAsync("https://www.livetops.com/tools/img-api.php?action=submit", form);
// 查询与下载时设置 AuthenticationHeaderValue("Bearer", accessToken)。

下载文件名与批量 ZIP

multipart 上传会保留原文件名的主文件名，只把扩展名替换为目标格式。例如 aaa.png 转 WebP 后下载为 aaa.webp。服务器磁盘内部仍使用随机名称。

curl -F "image=@aaa.png" -F "format=webp" "https://www.livetops.com/tools/img-api.php?action=submit"
# 完成后的状态响应：job.download_name = "aaa.webp"
# 下载响应：Content-Disposition: attachment; filename*=UTF-8''aaa.webp

批量任务返回 ZIP；ZIP 内按原文件名生成 aaa.webp、bbb.webp，并包含 manifest.json。若转换后重名，会自动变为 aaa-2.webp、aaa-3.webp。状态响应的 items[].original_name、items[].download_name 和 outputs[].download_name 可直接建立输入输出映射。

# 可选：单图自定义结果名；批量时自定义 ZIP 名称
-F "output_name=project-final"
# 也可使用请求头：X-Output-Filename: project-final

# Base64 / 原始二进制没有天然文件名，可选：
input_name=aaa.png
# 或请求头：X-Input-Filename: aaa.png

主要处理参数

接口、HTTP 状态与错误处理

200 查询或下载成功；202 任务已接受；400 请求错误；403 凭证或输入被拒绝；409 结果尚未准备；410 结果已过期；413 体积或像素超限；415 格式不支持；429 频率或图片额度超限；503 服务容量或处理能力暂时不可用。

对 429 和 503 优先读取 Retry-After。状态查询遵循 poll_after_ms。不要自动重试 400、403、413、415；网络失败可采用 1、2、4、8 秒的有限指数退避。

SERVICE_CAPACITY_REACHED · DOWNLOAD_TEMPORARILY_UNAVAILABLE · TOO_MANY_PENDING_JOBS · QUEUE_BUSY · FILE_TOO_LARGE · INVALID_IMAGE · UNSUPPORTED_OUTPUT_FORMAT · RESULT_EXPIRED

服务限制、长队列与保留期限

队列位置仅供参考。不同任务图片尺寸、输出格式和远程下载速度不同，实际完成顺序和耗时可能变化。客户端应持久保存任务凭证，不要依赖浏览器页面持续打开。

隐私与使用说明