API 开发文档

快速开始

使用网站账号开通 API 服务并创建密钥。API 采用异步任务协议：提交图片 → 查询状态 → 下载 SVG。收到 202 仅表示已接收，不代表转换完成。

准备环境变量

export API_BASE_URL='https://svgo-api.com/openapi/v1'
export API_KEY='YOUR_API_KEY'
# 一个业务任务固定一个键；断线重试仍用原键。下一张新图片换新键。
export IDEMPOTENCY_KEY='your-business-request-0001'

示例中的密钥是占位符。每个新业务任务生成唯一幂等键，原任务重试保留原键及原图片。先用 GET /capabilities 检查 acceptsTasks，未开放时不要提交图片。

提交并保存任务

curl --fail-with-body -sS "$API_BASE_URL/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -F 'image=@image.png' \
  -o task.json

# 需要 jq；请保存 task.json 中的 taskId。
TASK_ID=$(jq -r '.taskId // empty' task.json)
cat task.json

{
  "taskId": "6dd39862-bec8-44e4-b72e-50a40618ba6e",
  "status": "queued",
  "errorCode": null,
  "createdAt": "2026-10-28T02:00:00.000Z",
  "finishedAt": null,
  "expiresAt": null,
  "billing": {
    "source": "package",
    "state": "reserved",
    "reservedCents": 0,
    "chargedCents": null,
    "successOrdinal": null
  }
}

查询并领取结果

curl --fail-with-body -sS "$API_BASE_URL/tasks/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

# 仅在 status=succeeded 后下载，以下响应是文件，不是 JSON。
curl --fail -sS "$API_BASE_URL/tasks/$TASK_ID/result" \
  -H "Authorization: Bearer $API_KEY" \
  -o result.svg

建议间隔 2–3 秒查询。只有 succeeded 可以下载；failed、cancelled、expired 为不成功的终态。

鉴权与安全

全部 /openapi/v1 接口都需要 Authorization: Bearer YOUR_API_KEY。网站 Cookie、会员状态和 URL 查询参数不能替代 API Key。生产请求使用 HTTPS。

查询能力只要求有效 Key。控制台创建的密钥当前包含上述四种权限；细分权限可由管理端配置。完整 Key 只在创建时展示一次，最多保留 20 把有效 Key。

• 密钥仅保存在自己的服务器或密钥管理系统，不嵌入网页、插件、Git 仓库或日志。
• 泄露后立即撤销旧 Key，创建替代 Key 并更新服务端配置；撤销不会撤销已提交任务。
• 同账户多把 Key 共用额度、历史次数、队列和双并发，可查询同账户任务。
• 访问其他账户的任务统一返回 404。不要尝试用账户 ID 参数切换任务归属。

输入与输出

交给客户端库生成 multipart boundary；不要手动写死 Content-Type: multipart/form-data。文件上传和 JSON URL 输入二选一。额外字段、Base64 输入、自定义颜色、背景和输出参数当前不受支持。

完整代码示例

下面的 Node.js 和 Python 示例包含能力检查、上传、轮询、结果保存及有限退避。网络中断重试始终保留原幂等键和相同图片，不将等待超时当作转换失败。

export API_BASE_URL='https://svgo-api.com/openapi/v1'
export API_KEY='YOUR_API_KEY'
# 一个业务任务固定一个键；断线重试仍用原键。下一张新图片换新键。
export IDEMPOTENCY_KEY='your-business-request-0001'

# 先确认 acceptsTasks=true，查询能力不收费。
curl --fail-with-body -sS "$API_BASE_URL/capabilities" \
  -H "Authorization: Bearer $API_KEY"

curl --fail-with-body -sS "$API_BASE_URL/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -F 'image=@image.png' \
  -o task.json

# 需要 jq；请保存 task.json 中的 taskId。
TASK_ID=$(jq -r '.taskId // empty' task.json)
cat task.json

# 查询时若还未成功，间隔 2–3 秒再次查询；不要直接下载或重新创建。
curl --fail-with-body -sS "$API_BASE_URL/tasks/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

# 仅在 status=succeeded 后下载，以下响应是文件，不是 JSON。
curl --fail -sS "$API_BASE_URL/tasks/$TASK_ID/result" \
  -H "Authorization: Bearer $API_KEY" \
  -o result.svg

示例使用 curl 和 jq。查询仍未成功时继续等待，不要把最后一条下载命令当成自动轮询。

接口参考

下列路径相对于 https://svgo-api.com/openapi/v1。所有接口均按 Key 所属账户进行权限校验。只有下载结果返回文件，其余成功响应均为 JSON。

{
  "taskId": "6dd39862-bec8-44e4-b72e-50a40618ba6e",
  "status": "queued",
  "errorCode": null,
  "createdAt": "2026-10-28T02:00:00.000Z",
  "finishedAt": null,
  "expiresAt": null,
  "billing": {
    "source": "package",
    "state": "reserved",
    "reservedCents": 0,
    "chargedCents": null,
    "successOrdinal": null
  }
}

{
  "taskId": "6dd39862-bec8-44e4-b72e-50a40618ba6e",
  "status": "succeeded",
  "errorCode": null,
  "createdAt": "2026-10-28T02:00:00.000Z",
  "finishedAt": "2026-10-28T02:01:00.000Z",
  "expiresAt": "2026-10-29T02:01:00.000Z",
  "billing": {
    "source": "package",
    "state": "consumed",
    "reservedCents": 0,
    "chargedCents": 0,
    "successOrdinal": "1"
  }
}

{
  "accountId": "6fb13245-5c30-48e4-a5c7-0bfffc34a32f",
  "currency": "CNY",
  "balanceCents": "10000",
  "reservedCents": "20",
  "availableCents": "9980",
  "packageAvailableCalls": "0",
  "packageReservedCalls": "0",
  "lifetimeSuccessCount": "999",
  "nextUnitPriceCents": 20,
  "maxConcurrency": 2,
  "activeTasks": 1,
  "maxPendingTasks": 20,
  "walletFallback": true
}

{
  "items": [
    {
      "taskId": "6dd39862-bec8-44e4-b72e-50a40618ba6e",
      "successOrdinal": "1001",
      "source": "wallet",
      "chargedCents": 15,
      "consumedPackageCalls": 0,
      "createdAt": "2026-10-28T02:01:00.000Z"
    }
  ],
  "nextCursor": null
}

{
  "version": "v1",
  "acceptsTasks": false,
  "paymentAvailable": false,
  "formats": [
    "png",
    "jpeg",
    "webp"
  ],
  "inputMethods": [
    "multipart",
    "https-url"
  ],
  "maxFileBytes": 10485760,
  "maxInputPixels": 20000000,
  "processingMaxEdge": 1200,
  "maxConcurrency": 2,
  "resultRetentionSeconds": 86400
}

响应字段

Task · 任务及计费状态

Account · 额度与限制

错误与响应头

{
  "error": {
    "code": "API_CREDIT_INSUFFICIENT"
  },
  "requestId": "f7d692da-01bf-48c8-bb45-28d063b3d9d0"
}

应用错误通常包含 requestId，便于排查；网关故障可能只返回 error.code，客户端应容忍非 JSON 的错误响应。

任务状态与取消

申请取消不是确认取消

POST /tasks/{taskId}/cancel 不需要请求体。返回 cancel_requested 时继续查询，额度仍可能保持预留；只有确认取消后才释放。转换已先完成时会返回 succeeded，按照成功结果结算。

幂等键覆盖整个逻辑任务

同一账户的同一幂等键和图片会返回原 taskId，包括任务已经成功、失败或过期的情况；它不会“重新运行”原任务。原图不同返回 409。HTTP 超时或状态确认中，先恢复查询；确认原任务终态且有新的业务意图时，才创建新键。

当前任务记录和幂等信息不会随结果文件删除而清除。不要在任务结束后循环复用历史幂等键。

计费与额度预留

历史成功次数按 API 账户永久累计，所有 Key 共用。分段计价不追溯改价。通过余额付费的 1,500 次累计为 275 元。充值只增加余额，不增加成功调用次数。

• 接收任务时预留当前余额单价。若账号已有管理发放的有效调用额度，会先抵扣该额度；当前不销售调用次数包。
• 结果成功归档后结算一次。失败、确认取消或排队过期释放预留，不增加成功次数。
• 同一任务只扣包次数或余额一种。状态未知时保留预留并恢复确认，不立即重新收费或退款。
• 在第 999 次后并发两个余额任务，可都先预留 20 分；成功序号分别为 1000 和 1001，实际扣 20 分、15 分，多预留的 5 分释放。
• 查询状态、能力、额度、用量以及重复下载不收费；HTTP 请求数量不等于计费调用次数。

API 控制台提供 ¥10、¥50、¥100、¥500 四档余额充值，支付金额 1:1 入账，不销售调用次数包。微信支付是否开放以实际环境为准；本地预览关闭真实收款。自动退款尚未实现，测试额度不代表真实充值。

限流、超时与重试

429 优先遵守 Retry-After；网络错误、500/502/503/504 使用有上限的退避，可在生产中加入抖动。不要自动重试 400、401、402、403、404、409、410、413，先修正原因。

提交响应丢失可能发生在服务端已经接收之后。重传必须保留原键、原文件；下载失败只重试原下载路径。本地停止轮询不会停止服务器任务，只有取消接口才能申请取消。

错误码与排查

先判断 HTTP 状态，再判断 error.code。查询任务返回 HTTP 200，但 status=failed 时，业务转换仍然失败，应查看任务的 errorCode。

任务侧原因码包括输入异常、转换失败、排队过期及状态恢复等；遇到 STATE_RECONCILING 时先保留 taskId 继续查询，不以换键重传处理。联系服务方时提供 taskId、requestId 和错误码，不提供完整 Key 或私有图片。

OpenAPI 与调试工具

提供 OpenAPI 3.0.3 JSON，可用于 Postman、Apifox 或支持 OpenAPI 的客户端生成工具。规范只包含对外 7 个 v1 接口，不包含控制台会话、管理接口或内部信息。

1. 导入下载的 JSON，并把服务地址配置为 https://svgo-api.com/openapi/v1。
2. 在本地私有环境变量中设置 Bearer Key，不把真实 Key 同步到公共工作区或分享集合。
3. 提交接口可选 form-data 的 image 文件字段，或 raw JSON 的 imageUrl；补充独立的 Idempotency-Key 请求头。
4. 先查看 capabilities，再提交；保存 taskId，成功后以文件响应方式下载。

接口变更通过版本管理。当前没有已发布的官方 npm/PyPI SDK；文档中的下载示例可以直接使用，生成客户端后仍需保留异步轮询与幂等恢复逻辑。

当前能力边界