开发者 API

将 AI 图像增强嵌入您的产品

用于 AI 增强（磨皮、放大、自动增强、去背景）的 REST API，并提供一流的出站 Webhook。使用 API 密钥认证，并在任务完成时接收已签名事件。

获取 AI API 密钥试用 AI 增强管理 API 密钥 Webhook 投递 Webhook 事件 OpenAPI / Swagger

身份验证

每个请求都通过 x-api-key 请求头中的 API 密钥进行身份验证。在控制台中创建和管理密钥。密钥仅完整显示一次 — 请妥善保存。公共 API 请勿使用 Bearer token。

curl https://pickimg.com/api/ai/enhance \
  -H "x-api-key: YOUR_API_KEY"

权限范围

每个密钥都带有 scope。缺少所需 scope 会返回 403。

image:read读取图像任务与源文件

image:write上传并处理图像

ai:enhance上传源图、创建并轮询 AI 任务

webhook:manage创建并查看出站 Webhook

新密钥默认包含 image:read、image:write 和 ai:enhance。webhook:manage 需单独开启。

HTTP 错误

集成重试与升级流程时请使用这些状态码。

401	缺少或无效的 API 密钥。
403	密钥缺少所需 scope。月度增强或存储配额已用尽 — 任务会被拦截，不会按超量计费。
429	该密钥的每分钟请求上限已超出。请等待后重试。

429 响应包含 Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining.

AI 增强

POST/api/ai/upload上传源图像

POST/api/ai/enhance创建增强任务

GET/api/ai/enhance/:id获取任务状态与结果

GET/api/ai/enhance列出您的任务

POST /api/ai/upload 使用 multipart 字段 file（JPEG、PNG、WebP 或 AVIF，最大 20MB），返回 { url } 作为 sourceUrl。

操作： smooth_skin, upscale, auto_enhance, bg_remove. level: low | medium | high.

轮询 GET 直到 status 为 queued, processing, completed, failed.

上传、增强、轮询

# 1. Upload a source image (multipart field: file, max 20MB)
curl -X POST https://pickimg.com/api/ai/upload \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@./photo.jpg"
# { "url": "https://cdn.example.com/uploads/..." }

# 2. Queue enhancement
curl -X POST https://pickimg.com/api/ai/enhance \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceUrl": "https://cdn.example.com/uploads/photo.jpg",
    "operation": "smooth_skin",
    "level": "medium"
  }'
# { "id": "job_123", "status": "queued", "operation": "smooth_skin" }

# 3. Poll until completed or failed
curl https://pickimg.com/api/ai/enhance/job_123 \
  -H "x-api-key: YOUR_API_KEY"
# { "id": "job_123", "status": "completed", "resultUrl": "https://cdn.example.com/out.jpg" }

// Node.js
const key = process.env.PICKIMG_KEY;

const form = new FormData();
form.append("file", blob, "photo.jpg");
const uploaded = await fetch("https://pickimg.com/api/ai/upload", {
  method: "POST",
  headers: { "x-api-key": key },
  body: form,
}).then((r) => r.json());

const job = await fetch("https://pickimg.com/api/ai/enhance", {
  method: "POST",
  headers: {
    "x-api-key": key,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sourceUrl: uploaded.url,
    operation: "upscale",
  }),
}).then((r) => r.json());

const poll = await fetch(`https://pickimg.com/api/ai/enhance/${job.id}`, {
  headers: { "x-api-key": key },
}).then((r) => r.json());

官方 SDK（v0.1.0）

JavaScript（@pickimg/sdk）与 Python（pickimg）封装上传 → 增强 → 轮询。在 npm/PyPI 发布前请从仓库克隆安装。不要把令牌写入源码。

# From a clone of the pickimg repo (v0.1.0)
pnpm add ./sdk/js
pip install ./sdk/python

# After npm / PyPI publish:
# npm install @pickimg/sdk
# pip install pickimg

import { PickimgClient } from "@pickimg/sdk";

const client = new PickimgClient({ apiKey: process.env.PICKIMG_API_KEY! });

// 1. Upload
const { url } = await client.uploadImage(file);
// 2. Enhance
const job = await client.enhance({ sourceUrl: url, operation: "smooth_skin" });
// 3. Poll
const done = await client.waitForEnhancement(job.id);
console.log(done.resultUrl);

from pickimg import PickimgClient

client = PickimgClient(api_key="YOUR_KEY")

# 1. Upload
with open("photo.jpg", "rb") as fh:
    upload = client.upload_image(fh)
# 2. Enhance
job = client.enhance(source_url=upload["url"], operation="smooth_skin")
# 3. Poll
done = client.wait_for_enhancement(job.id)
print(done.result_url)

Webhook

注册端点以在任务完成时接收事件。每次投递都会签名，便于您验证真实性。

GET/api/webhooks/events列出可用事件类型

POST/api/webhooks/endpoints创建端点

GET/api/webhooks/deliveries查看投递记录

事件： enhancement.queued, enhancement.completed, enhancement.failed, image.uploaded, quota.exceeded, ping, job.completed, upload.finished.

job.completed 会与 image.completed、enhancement.completed 一并发送。upload.finished 会与 image.uploaded 一并发送。若希望用一个处理函数覆盖两类任务，请订阅别名。

验证签名

投递包含 X-PickIMG-Signature 请求头，格式为 t=<timestamp>,v1=<hmac>, 其中 HMAC-SHA256 基于 <timestamp>.<raw-body>.

import crypto from "crypto";

function verify(rawBody, header, secret) {
  const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

速率限制与配额

RPM 按每个 API 密钥计算（套餐上限）。每月 AI 增强次数与存储由同一账户下的所有密钥共享。

套餐	RPM	AI / 月	存储	API 密钥
Free	30	50	1 GB	1
Personal	120	2,000	50 GB	3
Business	600	20,000	500 GB	15
Enterprise	定制	定制	定制	定制

硬配额返回 403。RPM 返回带 Retry-After 的 429。企业套餐限额为定制 — 请联系销售，不要套用自助数字。

超出配额时 API 返回 403 并提示升级。详见定价.