llmocrapi.comGuida
Integrazione API OCR: Esempi di codice in Python e Node
Un'integrazione API OCR qui significa aggiungere una chiamata HTTP dopo il tuo motore OCR: invii il testo riconosciuto grezzo e ricevi testo pulito. L'endpoint è compatibile con OpenAI, quindi l'SDK che probabilmente hai già funziona dopo aver modificato due impostazioni.
Aggiornato

Punti chiave
- Imposta l'URL di base su https://api.llmocrapi.com/v1, usa l'ID del modello uncensored e invia la tua chiave come token Bearer.
- L'API accetta solo testo. Esegui prima il tuo motore OCR e passa il suo output come messaggio dell'utente.
- La modalità JSON restituisce risultati leggibili dalla macchina e un piccolo thread pool di fino a 8 worker mantiene veloce un batch.
- Una risposta 429 è un segnale di attesa e retry, non un errore: le richieste fallite non vengono addebitate.
Dove si inserisce la chiamata in una pipeline
Un tipico flusso di documenti ha quattro passaggi. Uno scanner o la fotocamera di un telefono producono un'immagine, un motore OCR trasforma l'immagine in testo grezzo, un passaggio di pulizia ripara quel testo e la tua applicazione memorizza o cerca il risultato. L'API descritta qui è il terzo passaggio. Non vede mai l'immagine e non ha input immagine. Questa è una funzionalità quando ti interessa la privacy delle scansioni originali, perché solo il testo lascia la tua macchina, ed è un limite se ti aspettavi un singolo endpoint che gestisce le immagini.
I prompt non vengono utilizzati per l'addestramento. Tuttavia, invia solo ciò di cui ha bisogno il compito: rimuovi numeri di conto o nomi prima della chiamata se la pulizia non dipende da essi.
Prima di scrivere qualsiasi codice, ottieni una chiave API. I nuovi utenti possono richiedere $0,50 di credito di prova con un clic su quella pagina dopo essersi registrati, che è sufficiente per eseguire ogni esempio di seguito molte volte. La chiave di prova consente 2 richieste concorrenti e 60 richieste al minuto; una chiave completa consente 8 e 300.
Impostazioni necessarie
| Impostazione | Valore |
|---|---|
| URL di base | https://api.llmocrapi.com/v1 |
| Endpoint | POST /v1/chat/completions |
| ID modello | uncensored |
| Intestazione di autenticazione | Authorization: Bearer YOUR_KEY |
| Finestra di contesto | 100.000 token, prompt più completamento |
Memorizza la chiave in una variabile d'ambiente, mai nel controllo del codice sorgente. Gli esempi leggono LLMOCR_API_KEY.
Due note pratiche prima di iniziare. Tieni la chiave fuori dal codice front-end, poiché tutto ciò che viene inviato a un browser può essere letto dai suoi utenti; chiama l'API da un server o un worker. E decidi presto dove risiederanno il testo OCR grezzo e il testo pulito, perché l'output pulito è il file che cercherai, indicizzerai e mostrerai alle persone, mentre il testo grezzo è la tua prova se una correzione viene messa in discussione.
Prima richiesta con curl
Inizia con curl per vedere la forma grezza di una richiesta prima che un SDK la nasconda. L'esempio seguente è un tipico frammento OCR danneggiato: un trattino spezzato a capo, una lettera confusa con una cifra e un numero di pagina estraneo.
curl https://api.llmocrapi.com/v1/chat/completions \
-H "Authorization: Bearer $LLMOCR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"temperature": 0,
"messages": [
{"role": "system", "content": "You repair raw OCR text. Fix broken words, rejoin hyphenated line breaks, remove page numbers. Return only the corrected text."},
{"role": "user", "content": "The inven-\ntory was com1leted on Tuesday.\n\n- 14 -\n\nA second ship-\nment arrived."}
]
}'
La risposta segue la forma standard del completamento della chat. Il testo pulito è in choices[0].message.content, e usage segnala i token prompt e completion per la chiamata. Imposta temperature a 0 per la pulizia. Vuoi che lo stesso input dia lo stesso output, non una variazione creativa.
Python con l'SDK OpenAI
Installa l'SDK con pip install openai. Solo il costruttore differisce da una configurazione OpenAI standard.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.llmocrapi.com/v1",
api_key=os.environ["LLMOCR_API_KEY"],
max_retries=4,
)
SYSTEM = (
"You repair raw OCR text. Fix broken words, rejoin hyphenated line breaks, "
"remove page numbers and running headers. Do not add or remove facts. "
"Return only the corrected text."
)
def clean(raw: str) -> str:
resp = client.chat.completions.create(
model="uncensored",
temperature=0,
messages=[
{"role": "system", "content": SYSTEM},
{"role": "user", "content": raw},
],
)
return resp.choices[0].message.content
print(clean("The inven-\ntory was com1leted on Tuesday."))
L'argomento max_retries dice all'SDK di riprovare in caso di errori di connessione e risposte 429 con backoff, quindi non hai bisogno di scrivere quel loop da solo per un uso leggero.
Esempio Node.js
Con npm install openai e un modulo ES, la stessa chiamata appare così.
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.llmocrapi.com/v1",
apiKey: process.env.LLMOCR_API_KEY,
});
export async function clean(raw) {
const resp = await client.chat.completions.create({
model: "uncensored",
temperature: 0,
messages: [
{ role: "system", content: "Repair raw OCR text. Return only the corrected text." },
{ role: "user", content: raw },
],
});
return resp.choices[0].message.content;
}
console.log(await clean("A second ship-\nment arrived."));
Qualsiasi cosa che supporti il formato chat OpenAI, come un tool di automazione no-code o un wrapper interno esistente, può usare le stesse due impostazioni. La documentazione elenca ogni parametro supportato.
Output strutturato con modalità JSON
Il testo libero va bene per gli archivi, ma le pipeline di estrazione dati hanno bisogno di campi. Attiva la modalità JSON con response_format e descrivi la forma che desideri nel prompt. Chiedere JSON nelle istruzioni oltre che nell'impostazione dà i risultati più affidabili.
import json
resp = client.chat.completions.create(
model="uncensored",
temperature=0,
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": (
"Clean the OCR text of a receipt and answer in JSON with keys "
"'vendor' (string), 'date' (YYYY-MM-DD or null), 'total' (number or null), "
"'cleaned_text' (string)."
)},
{"role": "user", "content": raw_receipt_text},
],
)
data = json.loads(resp.choices[0].message.content)
Avvolgi sempre json.loads in un blocco try e mantieni il testo grezzo, perché una risposta molto lunga o tronca può ancora produrre JSON non valido. Se l'analisi fallisce, riprova una volta e poi accoda la pagina per la revisione manuale.
Elaborazione di un batch in parallelo
Una singola richiesta alla volta è lenta per migliaia di pagine. Una chiave completa consente 8 richieste concorrenti, quindi un pool di 6 o 8 worker ti mantiene sotto il limite. Lascia un po' di margine se la stessa chiave è utilizzata da qualcos'altro.
from concurrent.futures import ThreadPoolExecutor
pages = [open(f"ocr/page_{i:04d}.txt").read() for i in range(1, 501)]
with ThreadPoolExecutor(max_workers=6) as pool:
cleaned = list(pool.map(clean, pages))
for i, text in enumerate(cleaned, start=1):
open(f"clean/page_{i:04d}.txt", "w").write(text)
Se superi il limite, l'API restituisce HTTP 429. Il codice di errore rate_limited significa troppe richieste al minuto, e concurrency significa troppe contemporaneamente. Un 429 con un'intestazione Retry-After: 5 significa sovraccarico temporaneo: aspetta cinque secondi. Le richieste in streaming mantengono uno slot di concorrenza fino alla fine dello streaming, quindi chiudi gli stream che smetti di leggere.
Monitora l'intestazione di risposta X-Balance-USD nelle esecuzioni lunghe. Quando scende, metti in pausa e ricarica dalla pagina dei prezzi invece di far fallire il lavoro a metà.
Documenti lunghi e verifica dell'output
L'output OCR reale raramente è una pagina ordinata. Un libro scansionato ti dà migliaia di pagine, e i danni sono disuniformi: un capitolo pulito, poi una pagina macchiata piena di caratteri rotti. Alcune abitudini mantengono prevedibile il passaggio di pulizia.
Dividi per struttura, non per conteggio di caratteri. Taglia alle interruzioni di pagina o ai confini dei paragrafi, così il modello non riceve mai una frase a metà all'inizio di un blocco. Se una frase attraversa un confine di pagina, includi l'ultimo paragrafo della pagina precedente come contesto di sola lettura e dì al modello di restituire solo la pagina corrente. Questo costa alcuni token di input extra per richiesta, che a $0,15 per 1M sono quasi nulla, e risolve le parole con il trattino che si estendono su due pagine.
Verifica ogni risultato con controlli economici prima di accettarlo. Confronta la lunghezza del testo pulito con la fonte: un rapporto lontano da 1 significa che il modello ha scartato o inventato materiale. Confronta i numeri: estrai ogni sequenza di cifre da entrambe le versioni e segnala le pagine in cui differiscono, poiché date, importi e identificatori sono gli errori più costosi da perdere. Tieni l'OCR grezzo accanto al testo pulito, così una persona può sempre ricostruire ciò che il motore ha effettivamente visto.
Infine, tratta la prima esecuzione come un pilota. Pulisci 20 pagine, leggine dieci da solo e sintonizza il sistema prompt. Di solito due o tre round di modifiche all'istruzione fanno più per la qualità di qualsiasi modifica ai parametri.
Errori comuni
- Invio di pagine molto grandi in un unico pezzo. La finestra è di 100.000 token e il corpo della richiesta massimo è 8 MB, ma l'accuratezza è migliore con chunk di dimensioni di pagina, e un chunk fallito costa meno da rifare.
- Lasciare che il modello riscriva. Se il prompt non dice di non aggiungere o rimuovere fatti, potrebbe levigare un passaggio danneggiato. Mantieni l'istruzione esplicita e confronta le lunghezze: una pagina pulita molto più corta della sua fonte merita un'occhiata.
- Uso del nome del modello sbagliato. L'unico ID del modello è
uncensored. Puoi elencare i modelli conGET /v1/models. - Aspettarsi embedding o input immagine. Nessuno di questi esiste su questa API. Per la ricerca sul testo pulito, usa uno strumento di embedding separato.
- Dimenticarsi di registrare l'ID della richiesta. Ogni risposta include un'intestazione
X-Request-Id. Memorizzala accanto alla pagina in modo che il supporto possa tracciare un risultato errato.
Le regole sui contenuti sono semplici: il modello è ottimizzato per rispondere senza rifiuti per l'uso adulto legale, e i contenuti sessuali che coinvolgono minorenni non sono mai consentiti. Le domande su un caso specifico vanno al supporto.
Altre guide
Domande e risposte
Ho bisogno di un SDK speciale?
No. Qualsiasi SDK OpenAI o client HTTP funziona una volta impostato l'URL di base su https://api.llmocrapi.com/v1, usato l'ID del modello uncensored e inviato una chiave Bearer.
Posso inviare un'immagine o un PDF direttamente?
No. L'API accetta solo testo. Esegui prima un motore OCR e invia il suo output come contenuto del messaggio.
Quante richieste posso eseguire contemporaneamente?
Una chiave completa permette 8 richieste concorrenti e 300 richieste al minuto. Una chiave di prova permette 2 richieste concorrenti e 60 al minuto.
Cosa succede se raggiungi un limite di richieste?
Ottieni HTTP 429 con il codice rate_limited o concurrency. Attendi e riprova; le richieste fallite non vengono addebitate.
La tua chiave è a un modulo di distanza
Crea un account, copia la chiave, modifica l'URL di base. È tutta la configurazione.