面向开发者

HTTP API

本网站本身就是一套纯 HTTP API 的客户端 —— 拖放区能做的一切，你都可以用 curl 完成。API Beta 期间免费、无需密钥。限流：每 IP 每分钟 30 次写请求，另有每日免档额度（20 次转换 / 3 次语音 / 30 次探测 —— 失败自动返还）。AI 智能体：把 /skill.md 给它 —— 本页全部内容都有面向智能体的版本。

鉴权与每日额度

API 无需任何密钥即可使用：匿名调用共享每 IP 免档额度（L1）。需要更高额度的 Agent 与脚本可以使用 API Key（L2b）—— 到账号页签发，以 Bearer 方式携带，每把 Key 有独立的每日额度。Key 仅以 SHA-256 哈希存储，明文只在签发时显示一次，也不会出现在任何日志中。

身份	转换/天	语音/天	文件探测/天
匿名（按 IP）—— L1	20	3	30
API Key（每 Key）—— L2b	500	20	300

每日额度在 UTC 午夜重置；失败的转换自动返还。写请求限流为每 IP 每分钟 30 次。

# 匿名（L1）—— 无需密钥
curl -X POST https://liteconvert.cc/api/public/detect -F "file=@document.pdf"

# 携带 API Key（L2b）—— 用你签发的 Key 替换示例中的占位密钥
curl -X POST https://liteconvert.cc/api/public/convert \
  -H "Authorization: Bearer sk-…" \
  -F 'meta={"conversion":"pdf-docx"};type=application/json' \
  -F "file=@document.pdf"

401 INVALID_API_KEY：以 Bearer 形式出示的 Key 校验失败（无效或已撤销）—— 已出示的 Key 一律拒绝，绝不降级为匿名；未携带 Key，或 Authorization 头不是 Bearer 形式的请求，按匿名 L1 计额。429 QUOTA_EXCEEDED：当前身份当日额度已用完；error.reset_at 给出准确重置时间（UTC 午夜）。

需要更高额度 —— 到账号页签发 API Key。

端点

方法	路径	作用
POST	/api/public/detect	识别文件（multipart file 字段）。同步，≤20 秒。
POST	/api/public/convert	提交转换（multipart meta + 文件）。返回 request_id。
GET	/api/public/requests/{id}	请求的状态、进度与产物。
GET	/api/public/requests/recent?limit=20	本设备的最近转换（X-Owner-Token 头，匿名）。
GET	/api/public/requests/{id}/artifacts/{name}	302 重定向到预签名下载地址。
GET	/api/public/requests/{id}/timeline	人类可读的转换事件轨迹。
GET	/api/public/stats	实时成功率统计。
GET	/api/public/conversions	转换目录（全部支持的转换对）。
GET	/api/public/catalog	面向站点构建方的构建清单（canonical 键,含 family/lossy/steps）。

探测文件

curl -X POST https://liteconvert.cc/api/public/detect -F "file=@document.pdf"

{
  "request_id": "c0af…",
  "status": "succeeded",
  "report": { "declared": "pdf", "detected": "pdf", "match": true,
              "mime": "application/pdf", "confidence": 0.99 }
}

转换并下载

# 1. 提交（URL 源发送带 source_url 的 meta，无文件部分）
curl -X POST https://liteconvert.cc/api/public/convert \
  -F 'meta={"conversion":"pdf-docx"};type=application/json' \
  -F "file=@document.pdf"
# → 202 { "request_id": "…", "status": "running" }

# 2. 轮询
curl https://liteconvert.cc/api/public/requests/REQUEST_ID
# → { "status": "succeeded", "artifacts": [{ "name": "docx", "download": "…", … }] }

# 3. 下载（302 到预签名地址，1 小时有效）
curl -L -o result.docx https://liteconvert.cc/api/public/requests/REQUEST_ID/artifacts/docx

错误码

状态	错误码	含义
401	INVALID_API_KEY	出示的 Key 无效，或该 Key 已被撤销。撤销立即生效 —— 请到账号页签发新 Key。
429	QUOTA_EXCEEDED	当日免档额度已用完（UTC 午夜重置；error.reset_at 带准确时间）。失败的转换会自动返还额度。
422	UNSUPPORTED_CONVERSION	转换对不在目录中。
404	ARTIFACT_EXPIRED	结果已过期并被删除（保留 24 小时）—— 请重新转换。
413/422	INTAKE_FAILED	上传失败或超过 200 MB。
502	CONVERT_FAILED	引擎已尝试但无法读取该文件。细分码（NEEDS_OCR、ENCRYPTED_DOCUMENT、MALFORMED_DOCUMENT）通过请求详情的 error.code 返回，消息为固定文案。
400	INVALID_SOURCE_URL	source_url 缺失，或不是合法的公开 http(s) 网址。
400	SOURCE_URL_BLOCKED	源地址解析到私有、回环或链路本地地址，已被拦截（SSRF 防护）。
502	SOURCE_URL_FETCH_FAILED	源地址无法下载 —— 离线、超时、过大或无法公开访问。
503	CONVERT_API_UNAVAILABLE	临时故障 —— 请一分钟后再试。

面向 AI 智能体

抓取 /skill.md —— 它是一份自包含的说明，包含上述端点、完整示例与免费档声明。不确定时先重读它；它会随 API 一起更新。