Per i costruttori

API HTTP

Il sito web è il client di una semplice API HTTP — tutto ciò che fa la zona di trascinamento, puoi farlo tu con curl. L'API è gratuita durante la beta, senza chiave richiesta. Limiti di frequenza: 30 richieste di scrittura al minuto per IP, più le quote gratuite giornaliere (20 conversioni / 3 vocali / 30 verifiche — i fallimenti vengono rimborsati). Agenti IA: puntateli a /skill.md — contiene tutta questa pagina in forma adatta agli agenti.

Autenticazione e quote

L'API è aperta senza alcuna chiave: le chiamate anonime condividono il livello gratuito per IP (L1). Agenti e script che servono più margine possono usare una chiave API (L2b) — emettine una nella pagina del tuo account e inviala come token Bearer; ogni chiave ha le sue quote giornaliere. Le chiavi sono conservate come hash SHA-256, il testo in chiaro viene mostrato una sola volta alla creazione e non appare mai nei log.

Identità	Conversioni/giorno	Voci/giorno	Verifiche di file/giorno
Anonimo (per IP) — L1	20	3	30
Chiave API (per chiave) — L2b	500	20	300

Le quote si azzerano alla mezzanotte UTC; le conversioni non riuscite vengono rimborsate automaticamente. Le scritture sono limitate a 30 richieste al minuto per IP.

# Anonimo (L1) — nessuna chiave necessaria
curl -X POST https://liteconvert.cc/api/public/detect -F "file=@document.pdf"

# Con una chiave API (L2b) — sostituisci sk-… con la tua chiave
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: una chiave è stata presentata come token Bearer ma ha fallito la validazione (invalida o revocata) — una chiave presentata viene sempre rifiutata, mai degradata ad anonima. Le richieste senza chiave, o con un'intestazione Authorization che non è una chiave Bearer, contano semplicemente sulla quota anonima L1. 429 QUOTA_EXCEEDED: la quota giornaliera di questa identità è esaurita; error.reset_at riporta l'ora esatta di reset (mezzanotte UTC).

Pronto per più margine — emetti una chiave API nella pagina del tuo account.

Endpoint

Metodo	Percorso	Che cosa fa
POST	/api/public/detect	Identifica un file (campo multipart file). Sincrono, ≤20 s.
POST	/api/public/convert	Invia una conversione (multipart meta + file). Restituisce request_id.
GET	/api/public/requests/{id}	Stato, avanzamento e artefatti di una richiesta.
GET	/api/public/requests/recent?limit=20	Le tue conversioni recenti su questo dispositivo (intestazione X-Owner-Token, anonimo).
GET	/api/public/requests/{id}/artifacts/{name}	Reindirizzamento 302 all'URL di download prefirmato.
GET	/api/public/requests/{id}/timeline	Traccia di eventi leggibile della conversione.
GET	/api/public/stats	Statistiche live del tasso di successo.
GET	/api/public/conversions	Il catalogo delle conversioni (tutte le coppie supportate).
GET	/api/public/catalog	Il manifest di build (chiavi canoniche con famiglia/lossy/steps) per chi costruisce siti.

Rileva un file

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 }
}

Converti e scarica

# 1. Invia (le sorgenti URL inviano meta con source_url e senza la parte file)
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. Interroga
curl https://liteconvert.cc/api/public/requests/REQUEST_ID
# → { "status": "succeeded", "artifacts": [{ "name": "docx", "download": "…", … }] }

# 3. Scarica (302 all'URL prefirmato, valido 1 h)
curl -L -o result.docx https://liteconvert.cc/api/public/requests/REQUEST_ID/artifacts/docx

Codici di errore

Stato	Codice	Significato
401	INVALID_API_KEY	È stata presentata una chiave invalida, oppure la chiave è stata revocata. La revoca ha effetto immediato — emetti una nuova chiave nella pagina dell'account.
429	QUOTA_EXCEEDED	Quota gratuita giornaliera esaurita (si azzera alla mezzanotte UTC; error.reset_at riporta l'ora esatta). Le conversioni non riuscite vengono rimborsate automaticamente.
422	UNSUPPORTED_CONVERSION	La coppia di conversione non è nel catalogo.
404	ARTIFACT_EXPIRED	Il risultato è scaduto ed è stato eliminato (conservazione 24 h) — riconverti.
413/422	INTAKE_FAILED	Caricamento non riuscito o oltre i 200 MB.
502	CONVERT_FAILED	I motori hanno provato ma non sono riusciti a leggere questo file. I codici di dettaglio (NEEDS_OCR, ENCRYPTED_DOCUMENT, MALFORMED_DOCUMENT) vengono restituiti in error.code della richiesta con messaggi fissi.
400	INVALID_SOURCE_URL	source_url manca o non è un URL pubblico http(s) valido.
400	SOURCE_URL_BLOCKED	L'URL di origine risolve a un indirizzo privato, di loopback o link-local ed è stato bloccato (protezione SSRF).
502	SOURCE_URL_FETCH_FAILED	Non è stato possibile scaricare l'URL di origine — offline, tempo scaduto, troppo grande o non raggiungibile pubblicamente.
503	CONVERT_API_UNAVAILABLE	Interruzione temporanea — riprova tra un minuto.

Per gli agenti IA

Scarica /skill.md — è un foglio di istruzioni autosufficiente con gli endpoint qui sopra, esempi risolti e la dichiarazione del livello gratuito. Rileggilo nel dubbio; si aggiorna insieme all'API.