PixelToPath API

快速入门

只需三步，您就可以从终端、脚本或应用中将图像转换为 SVG。

您的第一次转换

curl -sS -f -X POST https://api.pixel-to-path.com/v1/convert \
  -H "Authorization: Bearer ptp_live_YOUR_KEY" \
  -F "[email protected]" \
  -F "colormode=binary" \
  -o logo.svg

交互式参考文档：pixel-to-path.com/v1/docs (OpenAPI/Swagger).

身份验证

每个请求都通过 Authorization 标头中的 Bearer 令牌进行身份验证：

Authorization: Bearer ptp_live_0123abc…

• 密钥是秘密：它们在服务器端经过哈希存储，并且在创建时仅显示一次。丢失密钥？撤销它并创建一个新密钥。
• 一个帐户，多个密钥：最多可创建 5 个有效密钥以分离您的项目。您的每月免费额度按帐户计算，而不是按密钥计算。
• 即时撤销：已撤销的密钥会立即停止工作，无论是从门户撤销还是封禁帐户的 API 响应。

POST /v1/convert

在单个无状态调用中完成上传和转换。一次成功的调用最多消耗 1 个积分 — 失败、无效或受速率限制的调用不收费。

请求 (multipart/form-data)

由 "colormode" 决定的两个引擎

API 运行的引擎与免费在线转换器和桌面应用完全相同：

图像的预处理与网站上完全相同：在转换之前，最长边将被调整为 1500 像素，API 会在 X-Detected-Type 标头中返回检测到的图像类型（line_art、logo、photo 或 illustration）。

响应

成功时：200 OK 并且带有 image/svg+xml — 主体即是 SVG 文件本身。包含信息的标头：

GET /v1/me

用于调用该请求的密钥的帐户状态。免费 — 绝不计入您的额度，绝不扣分。

响应示例

GET /v1/me
Authorization: Bearer ptp_live_…

{
  "key": { "name": "prod", "prefix": "ptp_live_0123abc", … },
  "usage": {
    "month": "2026-09", "free_used": 7, "free_limit": 10,
    "free_remaining": 3, "resets_at": "2026-10-01T00:00:00+00:00"
  },
  "credits": { "balance": 120 }
}

错误

每个错误都会返回一致的 JSON 格式。失败的调用永远不会消耗积分。

HTTP/1.1 402 Payment Required
{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly free quota used and no credits left.",
    "usage": { "free_used": 10, "free_limit": 10, "credits": 0 }
  }
}

速率限制

限制按 API 密钥应用，而不是按 IP 应用，因此共享办公室或 CI 运行器永远不会因为其他人的流量而受罚。

定价

每个新帐户都会获得每月 10 次免费转换，无需信用卡。需要更多？购买预付费图像 — 任意数量 (以 50 张为一批次)，并享受批量折扣。它们永不过期，并可与您的每月免费额度叠加 (优先消耗免费转换次数)。

自动发放积分：付款后几秒钟内通过付款 webhook 更新您的余额。退款将扣除购买的积分，上限为当前余额。由 Lemon Squeezy 提供安全结账 (自动处理增值税)。

代码示例

复制并修改使用。该 API 使用简单的 multipart/form-data，因此任何 HTTP 客户端均可运行。

cURL

curl -sS -f -X POST https://api.pixel-to-path.com/v1/convert \
  -H "Authorization: Bearer ptp_live_YOUR_KEY" \
  -F "[email protected]" \
  -F "colormode=color" \
  -F "filter_speckle=4" \
  -o photo.svg

Python

import requests

resp = requests.post(
    "https://api.pixel-to-path.com/v1/convert",
    headers={"Authorization": "Bearer ptp_live_YOUR_KEY"},
    files={"file": open("photo.jpg", "rb")},
    data={"colormode": "color", "filter_speckle": 4},
)
resp.raise_for_status()
print(resp.headers["X-Credits-Remaining"], "credits left")
with open("photo.svg", "wb") as f:
    f.write(resp.content)

JavaScript

const form = new FormData();
form.append("file", new Blob([imageBytes]), "photo.jpg");
form.append("colormode", "color");

const resp = await fetch("https://api.pixel-to-path.com/v1/convert", {
  method: "POST",
  headers: { "Authorization": "Bearer ptp_live_YOUR_KEY" },
  body: form,
});
if (!resp.ok) {
  const { error } = await resp.json();
  throw new Error(`${error.code}: ${error.message}`);
}
const svg = await resp.text();
console.log(resp.headers.get("X-Credits-Remaining"), "credits left");

常见问题解答