AIREITERUn’API a metà prezzo è allettante, finché il risultato non arriva oltre la scadenza. La Batch API di OpenRouter è adatta ai processi offline su testo ed embedding, non alle richieste interattive: lavora in modo asincrono, prevede una finestra di completamento di 24 ore e lo sconto pubblicizzato non si applica allo stesso modo a ogni voce di costo.
La scelta in una riga
Usa la Batch API di OpenRouter per classificazioni, valutazioni, embedding, riepiloghi arretrati e altri processi che possono aspettare. Per chat rivolte agli utenti, agenti integrati nell’IDE, flussi con ricerca web e richieste multimodali, resta sull’API sincrona.
OpenRouter dichiara che la modalità Batch offre in genere un prezzo per token più basso di circa il 50% su oltre 70 modelli. La finestra formale di completamento è di 24 ore. Nell’annuncio del lancio, OpenRouter ha riportato una mediana di 7 minuti e il completamento del 90% delle richieste entro un’ora durante la beta; sono dati osservati, non un SLA (annuncio ufficiale).
Cosa copre davvero lo sconto del 50%
Lo sconto riguarda soprattutto il prezzo dei token del modello. Non è una riduzione generalizzata applicata a ogni componente del conto di inferenza.
| Voce di costo o controllo | Trattamento nella Batch API |
|---|---|
| Token di input e output | In genere circa il 50% del prezzo standard del modello |
| Chiamate di ricerca web | Addebitate alle tariffe standard, secondo il quickstart ufficiale |
| Prompt caching | Varia in base al modello; controlla la pagina del modello |
| Inferenza BYOK | Il provider addebita direttamente l’inferenza; OpenRouter comunica separatamente il proprio costo BYOK |
| Prezzo effettivamente applicabile | Verificalo nella pagina del singolo modello e nei consumi della batch completata |
Nel suo esempio sui costi del batching, Will Cygan mostra un caso con Claude Sonnet 5 in cui 10 milioni di token di input e 2 milioni di output passano da $40 in modalità sincrona a $20 in modalità Batch. È un calcolo specifico per quel modello, non un preventivo universale.
“La modalità batch applica esattamente la metà della tariffa sync.” — Will Cygan, Batching (LLM Inference)
Non mettere a budget il risparmio prima di aver controllato provider e modello. Un utente reale, @fogelmania, ha segnalato che un modello beta era più costoso delle chiamate sincrone concorrenti perché il traffico batch veniva instradato verso un provider diverso: il post di @fogelmania. È un avvertimento a verificare il costo finale, non la prova che ogni modello si comporti così.
Una batch è un job, non un endpoint più veloce
L’annuncio della Batch API di OpenRouter e il relativo quickstart descrivono un flusso basato su job, non un completamento immediato. Una sottomissione riuscita restituisce HTTP 202 Accepted e un batch ID con stato validating. Il normale ciclo di vita è:
validating → in_progress → finalizing → completedGli altri esiti finali sono failed, expired e cancelled. Il worker deve salvare il batch ID e interrogare periodicamente lo stato fino a raggiungere una condizione finale, invece di tenere aperta una richiesta interattiva.
OpenRouter ha riportato oltre 230.000 batch in beta, con una mediana di 7 minuti e il 90% dei completamenti entro un’ora. Un test effettuato dall’utente @luismmolina ha segnalato tempi di 5–8 minuti in un certo momento del giorno del lancio (post del test); queste osservazioni non sostituiscono il limite di pianificazione di 24 ore.
Come impostare l’integrazione senza rifare tutto da capo
Il quickstart attuale usa un array JSON requests inline, non il caricamento di un file JSONL. Ogni riga deve avere un custom_id univoco; questo ID permette di associare la risposta completata o l’errore al record originale.
La struttura minima della richiesta è:
{
"endpoint": "/v1/chat/completions",
"model": "openai/gpt-4o",
"requests": [
{
"custom_id": "ticket-0001",
"body": {
"messages": [
{"role": "user", "content": "Classify this ticket: ..."}
]
}
}
]
}Il quickstart documenta POST https://openrouter.ai/api/beta/batches. Endpoint e modello al livello principale valgono per l’intera batch: per usare modelli o formati API diversi servono batch separate. Sono supportati Chat Completions, Responses, Anthropic Messages ed Embeddings.
Dopo l’invio, interroga periodicamente GET https://openrouter.ai/api/beta/batches/:id. Una batch completata restituisce i risultati inline. Ogni risultato contiene una response oppure un error, mentre request_counts separa il numero totale di righe da quelle completate e fallite. Ritenta le righe fallite usando il relativo custom_id; non ripetere automaticamente l’intera batch.
Se il comportamento del provider è rilevante per policy sui dati, BYOK o asset indicati tramite URL, fissa il provider usando i controlli documentati invece di affidarti al routing verso il provider più economico. Prima del deployment, verifica che modello e provider selezionati espongano una route Batch idonea.
Dove la modalità Batch interrompe il flusso di lavoro
I limiti indicati nel quickstart fanno della Batch una soluzione pensata soprattutto per il testo. Le richieste batch rifiutano contenuti sotto forma di immagini, audio, video e file. Gli asset in Base64 e gli URI data: vengono rifiutati; gli asset accessibili tramite URL supportati dipendono dal provider. Il plugin di ricerca web di OpenRouter non è disponibile nella modalità Batch.
Usa l’API sincrona quando l’utente è in attesa, il modello deve analizzare un file caricato localmente, la richiesta richiede audio o video oppure l’applicazione deve rispettare un obiettivo di risposta nell’ordine dei secondi.
Esempio di costo: quando il risparmio è concreto
Consideriamo 10.000 ticket di assistenza, ognuno con 1.000 token di input e 200 token di output. In totale sono 10 milioni di token di input e 2 milioni di token di output.
| Modalità | Input | Output | Totale |
|---|---|---|---|
| Esempio sincrono | 10M × $2 = $20 | 2M × $10 = $20 | $40 |
| Esempio Batch | 10M × $1 = $10 | 2M × $5 = $10 | $20 |
Il risparmio nominale è di $20 per esecuzione, ovvero $1.040 all’anno se l’esempio viene eseguito ogni settimana. Il risparmio effettivo diminuisce ogni volta che recupero, monitoraggio o fallback sincrono d’emergenza costano più della differenza nominale.
Considera questa riserva nella decisione. Se la scadenza è rigida, confronta la finestra di 24 ore con il tempo ancora disponibile per una nuova esecuzione a portata ridotta o per un fallback sincrono. Una batch che costa meno per token ma non è utilizzabile dopo la scadenza non è più economica per quel processo aziendale.
Domande frequenti
La Batch API di OpenRouter costa sempre la metà?
No. OpenRouter descrive lo sconto come tipico e dipendente dal modello. Le chiamate di ricerca web mantengono le tariffe standard, il caching varia e il BYOK separa i costi di inferenza del provider da quelli di OpenRouter.
Quanto impiega una batch di OpenRouter?
La finestra di completamento supportata è di 24 ore. I tempi osservati durante la beta sono un riferimento utile, non un livello di servizio garantito.
Posso caricare un JSONL o combinare più modelli?
Il quickstart accetta un array JSON requests inline. Modello e formato API valgono per l’intera batch, quindi per modelli o formati endpoint diversi servono batch separate.
Posso ritentare solo le righe fallite?
Sì, quando una batch completata restituisce errori a livello di singola riga, puoi usare il custom_id di ciascuna riga per creare una batch di retry più piccola. Gestisci separatamente i casi di errore, scadenza o annullamento a livello di batch, perché i risultati potrebbero non essere disponibili.
Meglio Batch o API sincrona?
Scegli Batch per i processi in background non urgenti. Scegli l’inferenza sincrona quando il risultato fa parte di un’interazione attiva con l’utente oppure richiede modalità e strumenti non supportati.
La scelta pratica: usa Batch dove serve davvero
Prima di spostare un workload, verifica cinque aspetti:
- La pagina del modello mostra una route Batch compatibile e il provider previsto.
- Il processo aziendale può tollerare l’intera finestra di 24 ore.
- Ogni riga ha un
custom_idstabile e un piano di retry. - L’applicazione registra consumi e costi effettivi delle batch completate.
- Input e risultati hanno un responsabile e una policy di eliminazione.
Il quickstart di OpenRouter specifica che input e risultati delle batch vengono conservati per 30 giorni, salvo eliminazione anticipata. Elimina le batch in stato finale quando gli artefatti non servono più.
La prima migrazione ideale riguarda un corpus congelato e verificabile, non un percorso rivolto ai clienti in cui una risposta in ritardo costerebbe più di quanto il risparmio sui token possa far guadagnare.