# LiteConvert Skill

Convert any file to another format over plain HTTP — or install the CLI skill below and
let your agent do it. The anonymous tier needs no key and no account; an optional API key
only raises the daily quota.

Re-read this URL when unsure: https://liteconvert.cc/skill.md

## Install the skill (CLI, pure Python stdlib)

- Self-install / self-update guide: https://liteconvert.cc/docs/skill.md
- Skill files: https://liteconvert.cc/skill/SKILL.md · https://liteconvert.cc/skill/liteconvert.py

## Endpoints (base: https://liteconvert.cc)

| Method | Path | Purpose |
| ------ | ---- | ------- |
| POST   | /api/public/detect                          | Identify file type (multipart: file). Sync, <=20s. |
| POST   | /api/public/convert                         | Start conversion (multipart: meta JSON + file, or meta JSON with source_url). |
| GET    | /api/public/requests/{id}                   | Status/progress/artifacts. |
| GET    | /api/public/requests/recent?limit=20        | Recent conversions of this device (X-Owner-Token header). |
| GET    | /api/public/requests/{id}/artifacts/{name}  | 302 -> presigned download (1h TTL). |
| GET    | /api/public/requests/{id}/timeline          | Human-readable event trail. |
| GET    | /api/public/stats                           | Live success-rate stats. |
| GET    | /api/public/conversions                     | Catalog of all supported conversion keys. |
| GET    | /api/public/catalog                         | Build manifest (canonical keys with family/lossy/steps). |

## Auth and quotas

Anonymous requests need no key and no account (L1). An API key only raises the daily
quota: sign in at https://liteconvert.cc/account and issue one (up to 3 per account, plaintext shown once).
Send it on every request as `Authorization: Bearer sk-...`.

| Identity | Conversions/day | Voice/day | File checks/day |
| -------- | --------------- | --------- | --------------- |
| Anonymous, per IP — L1 | 20 | 3 | 30 |
| API Key, per key — L2b | 500 | 20 | 300 |

Quotas reset at UTC midnight (429 carries `error.reset_at`); failed conversions are
refunded automatically. Writes are rate-limited to 30 requests/minute/IP.
Without a key nothing changes — the anonymous quota above applies as before.

## Quick start

```bash
# 1) Detect (recommended before converting unknown files)
curl -X POST https://liteconvert.cc/api/public/detect -F "file=@input.bin"

# 2) Convert (list all keys: GET /api/public/conversions)
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"}

# 3) Poll until status is succeeded/failed/timed_out/cancelled
curl https://liteconvert.cc/api/public/requests/REQUEST_ID

# 4) Download the artifact named in artifacts[].download
curl -L -o result.docx \
  https://liteconvert.cc/api/public/requests/REQUEST_ID/artifacts/docx

# URL sources (url-pdf): meta carries source_url, NO file part
curl -X POST https://liteconvert.cc/api/public/convert \
  -F 'meta={"conversion":"url-pdf","source_url":"https://example.com"};type=application/json'

# With an API key (L2b) — add this header to any call above
curl -H "Authorization: Bearer sk-..." https://liteconvert.cc/api/public/requests/REQUEST_ID

# Voice: text-to-speech txt-markdown -> wav/mp3 (txt-mp3), transcription wav/mp3 -> txt (mp3-txt)
```

## Error codes (in {"error":{"code","message"}})

- 401 INVALID_API_KEY — the presented key is invalid or was revoked. Never downgraded to
  anonymous: check the Authorization header, drop it to continue anonymously, or issue a
  new key at https://liteconvert.cc/account. Revocation takes effect immediately.
- 429 QUOTA_EXCEEDED — this identity's daily quota is used up (error.reset_at says when it
  resets, UTC midnight). Failures are refunded, so the cap means real usage; signing in or
  using an API key raises the quota (L1 20/day -> L2b 500/day conversions) — keys are
  issued at https://liteconvert.cc/account.
- 422 UNSUPPORTED_CONVERSION — conversion pair not in catalog. GET /api/public/conversions lists valid keys.
- 404 ARTIFACT_EXPIRED — result deleted (files are kept 24 hours). Convert again.
- 413/422 INTAKE_FAILED — file exceeds 200 MB or upload failed.
- 503 CONVERT_API_UNAVAILABLE — temporary outage, retry in a minute.
- 502 CONVERT_FAILED — the engines tried and could not read this file. Message is a fixed generic string.

Terminal failures carry a normalized detail code in the request's error.code
(GET /api/public/requests/{id}) — drive user messaging off the code, not the message:

- NEEDS_OCR — scanned PDF; text recognition (OCR) is not supported.
- ENCRYPTED_DOCUMENT — the document is password-protected.
- MALFORMED_DOCUMENT — the file could not be read and may be corrupted.
- TASK_TIMEOUT / timed_out — the conversion took too long and was stopped.
- CONVERT_FAILED — anything else; retry or try another file.

## Declarations

- Free during the beta. The anonymous tier needs no key and no account; signing in or
  issuing an API key (L2b) raises the daily quota. Rate limit: 30 writes/min/IP.
- Conversion keys are canonical `{src}-{dst}` pairs (e.g. `pdf-docx`, `txt-mp3`); older
  key styles are rejected with 422 — list the live catalog with GET /api/public/conversions
  (`formats` in the CLI) instead of guessing.
- Uploaded files and results are auto-deleted within 24 hours.
- No OCR (scanned files are detected and reported). No DRM removal.
- Quotas and their refunds may change as the beta evolves — this file and
  https://liteconvert.cc/docs/skill.md update with them.