Modelli e routing

UberLLM invia ogni richiesta a un fornitore terzo disponibile per il modello che hai richiesto. Se il fornitore fallisce prima di iniziare a rispondere, la richiesta viene ritentata, e una richiesta che fallisce ancora non viene fatturata. Ogni richiesta viene fatturata in base a quanto addebitato dal fornitore, senza costi aggiuntivi di UberLLM, ed è elencata con il suo costo in Dashboard → Attività. Tu scegli un modello, non un fornitore.

ID dei modelli

Usa l'ID del modello dal catalogo, ad es. deepseek/deepseek-v4-flash, anthropic/claude-sonnet-5 o z-ai/glm-5.3. Elenca ciò che puoi chiamare subito:

GET https://api.uberllm.dev/v1/models: i modelli di chat a cui è possibile inviare una richiesta subito, così uno strumento che popola il suo menu dei modelli da questo elenco (SillyTavern, LibreChat, n8n, Cline) mostra solo i modelli con cui può chattare. Aggiungi ?type=video (o image, music, speech, transcription, audio per entrambi, chat, diversi uniti da virgole) per altri tipi, o ?type=all per ogni modello, prima chat, poi immagine, video, musica, voce e trascrizione. Ogni voce ha type (chat, image, video, music, speech, transcription), endpoints (i percorsi che lo servono) e pricing.
Ogni modello di chat indica anche cosa può fare: context_length, max_output_tokens, input_modalities (image = legge le immagini), supports_tools, supports_reasoning, supports_vision e supported_parameters (i campi di richiesta che accetta). Gli stessi fatti sono anche sotto i nomi di OpenRouter (architecture.input_modalities, top_provider.context_length, top_provider.max_completion_tokens, e pricing.prompt / pricing.completion in dollari per token), quindi gli strumenti creati per l'elenco di OpenRouter leggono il nostro così com'è.
GET https://api.uberllm.dev/v1/models/<model id>: un modello, con il suo prezzo, il suo contesto (chat) e, per un modello multimediale, parameters: uno JSON Schema del corpo della richiesta (vedi Crea un video o un'immagine).
Ogni voce, in entrambe le risposte, ha anche:
- available: true quando una richiesta per esso può essere servita subito. false significa che nessuno lo sta servendo al momento, quindi una richiesta verrebbe rifiutata con no_available_provider. Scegli un altro modello o riprova più tardi.
- input_modalities: ciò che il modello accetta. Un modello che richiede un'immagine (da immagine a video, da riferimento a video, modifica di immagini) elenca "image" accanto a "text"; uno che accetta un video (upscaling) elenca "video".
- nsfw: true per un modello creato per contenuti per adulti o non filtrati (Lustify, i modelli "non censurati" e simili). Salta questi se il tuo prodotto deve rimanere adatto all'ambiente di lavoro.
Pubblico, senza chiave: GET https://api.uberllm.dev/api/v1/public/models (con prezzi, e gli stessi campi available, input_modalities e nsfw)
Web: uberllm.dev/#models, e una pagina per modello a uberllm.dev/models/<model id>

Cosa succede a ogni richiesta

UberLLM verifica che il modello esista, che il tuo prompt rientri nella sua finestra di contesto e che supporti gli strumenti se la tua richiesta li utilizza.
Riserva il costo stimato dal tuo saldo e inoltra la richiesta.
La richiesta viene inviata a un provider disponibile per quel modello. Il provider viene scelto nuovamente per ogni chiamata: quello più economico che inizia a rispondere abbastanza velocemente per la dimensione del tuo prompt (entro 2x del più veloce misurato, o sotto 1 secondo). Un prompt lungo in streaming va anche a un secondo provider veloce quando il primo è lento ad avviarsi; ricevi e paghi per una sola risposta. Nominare i provider in provider.only, ignore o order, o impostare sort, sostituisce questa scelta. Come funziona: smart routing.
Quando la risposta termina, UberLLM si assesta al prezzo che il marketplace riporta per quella chiamata e rilascia il resto della prenotazione.

Tentativi automatici

Se una chiamata fallisce prima che ti arrivi qualsiasi contenuto, UberLLM la ritenta per te. Il marketplace ri-abbina un venditore ad ogni tentativo e non addebita nulla per una chiamata fallita prima di essere instradata, quindi un nuovo tentativo ti costa solo tempo.

Ritentato: nessun venditore per il modello al momento (no_sellers_for_model, no_healthy_sellers), il marketplace ha esaurito il tempo per instradare (route_deadline_exceeded), un 429 che chiede di attendere 5 secondi o meno, qualsiasi 5xx, un errore di connessione, un venditore la cui API key o account del provider è fallito, o nessun primo byte in tempo.
Non ritentato: il modello non esiste, la richiesta non è valida, o un problema di fatturazione o auth. Questi vengono restituiti immediatamente.
Programma: fino a 4 tentativi, attendendo 0.3 s, 0.9 s, poi 2.7 s tra di essi (o il Retry-After inviato dal marketplace, se è 5 secondi o meno). Quando nessuno vende il modello, la risposta torna entro pochi secondi.
Attesa del primo byte: uno stream ottiene 10 secondi (di più per un prompt lungo, e di più per un modello che è solitamente lento); una risposta senza "stream": true ottiene 85 secondi, perché nulla arriva finché non è completa. Un tentativo che esaurisce tutti i 85 secondi non viene atteso una seconda volta. Nessun nuovo tentativo inizia dopo 150 secondi.

Una volta avviato lo streaming, nulla viene ritentato: un fallimento a metà stream termina lo stream e ti viene addebitato solo ciò che è stato prodotto.

Se ogni tentativo fallisce, ricevi un errore invece di una risposta, e la prenotazione viene completamente rilasciata. Quelli comuni:

HTTP	`code`	Quando
503	`no_available_provider`	Nessuno è riuscito a servire quel modello al momento, anche dopo i tentativi: nessun venditore, ogni venditore che fallisce o è troppo lento per iniziare, o le tue opzioni `provider` non hanno lasciato nulla a cui instradare. Il messaggio nomina il modello. Riprova tra poco o scegli un altro modello.
503	`service_unavailable`	Un problema temporaneo da parte di UberLLM. Riprova tra qualche minuto.
404	`model_not_found`	L'ID del modello non è disponibile.

Vedi Errori per l'elenco completo.

Modelli di fallback

Invia models con un elenco di altri ID modello da provare, in ordine, quando il primo non può essere servito:

{ "model": "deepseek/deepseek-v4-flash",
  "models": ["z-ai/glm-5.3", "qwen/qwen3.6-plus"],
  "messages": [{ "role": "user", "content": "hi" }] }

Il modello successivo viene provato solo quando nessuno può servire quello precedente in questo momento (no_available_provider), o nessuno lo vende all'interno del tuo provider.max_price. Un errore di richiesta (un body non valido, un ID modello sconosciuto in uno dei due campi) e un rifiuto di pagamento (saldo, limiti della chiave) ricevono una risposta immediata e non vengono mai passati lungo la lista. Al massimo 5 modelli in model e models insieme. Il campo model della risposta e la riga Attività nominano il modello che ha risposto. models funziona su /v1/chat/completions e su richieste di immagini, video, musica e parlato; /v1/messages e /v1/audio/transcriptions non lo leggono.

Alias dei modelli

Invece di un ID modello, puoi nominare ciò di cui hai bisogno, e UberLLM sceglie il modello ad ogni richiesta:

best-price:<job>: il modello disponibile con il prezzo più basso per una richiesta ordinaria. Un modello di chat è confrontato in base al suo prezzo per milione di token con l'output contato tre volte; un modello di immagine in base a un'immagine (un'immagine 1024×1024 quando il prezzo è per megapixel); un modello video in base al suo clip più corto; un modello musicale in base a una traccia; un modello vocale in base a 1K caratteri; un modello di trascrizione in base a un minuto.
fastest:<job>: il modello con il tempo mediano più basso sulle sue richieste riuscite su UberLLM negli ultimi 7 giorni (tempo al primo token per la chat, tempo al file completato per i media), contando solo i modelli con almeno 5 richieste di questo tipo. Quando nessun modello è sufficiente, la richiesta viene rifiutata con 503 no_timing_data, e best-price: funziona ancora.

Entrambi scelgono solo tra i modelli disponibili in questo momento: il mercato in tempo reale mostra un venditore sano per esso, e l'ultima richiesta di UberLLM ad esso negli ultimi 10 minuti non ha trovato ogni venditore occupato o inattivo (la stessa regola di available su /v1/models). Su una rotta multimediale, quando il modello scelto da un alias risponde che nessuno può prendere la richiesta, la stessa richiesta passa al modello successivo che l'alias rappresenta (fino a 3 modelli), e il model della risposta nomina quello che ha risposto. Quando nessun modello per il lavoro è disponibile, la risposta è 503 no_available_provider e nulla viene addebitato.

<job> è uno tra chat, image, image-edit, text-to-video, image-to-video, music, speech, transcription. Invia un alias di chat a /v1/chat/completions o /v1/messages, e uno multimediale alla sua rotta multimediale. Il campo model della risposta nomina il modello a cui si è risolto. GET /v1/models/aliases elenca ogni alias che si risolve in questo momento e il suo modello; GET /v1/models/best-price:chat descrive il modello che rappresenta, con alias impostato.

Opzioni di routing

L'oggetto provider viene letto su /v1/chat/completions. Un'opzione che UberLLM non può applicare viene rifiutata con 400 unsupported_routing_option e nulla viene addebitato, quindi una richiesta non viene mai eseguita con un'impostazione scartata silenziosamente.

Opzione	Cosa fa
`only` / `allow`	Solo queste route o provider. `uberllm` (la route marketplace di UberLLM) e `seller` (le offerte proprie dei venditori) scelgono tra le nostre route. Qualsiasi altro nome, come `openai` o `api.venice.ai`, è un provider sul marketplace: la richiesta passa quindi attraverso la route `uberllm`, che utilizza solo offerte di quei provider.
`ignore` / `deny`	Mai queste. Nomi delle route come sopra. I nomi dei provider (al massimo 32) vengono rifiutati sul marketplace e la richiesta passa quindi attraverso la route `uberllm`.
`order`	Ordine preferito. I nomi delle route ordinano le nostre route; i nomi dei provider impostano l'ordine di tentativo del marketplace. Non rende mai un provider idoneo o non idoneo.
`sort`	`price` (il default), `latency` (il più veloce osservato per primo, all'interno di una fascia di prezzo) o `uptime` (il più affidabile per primo, all'interno della stessa fascia). `throughput` ordina solo le nostre route.
`max_price`	Il massimo che paghi per milione di token, in dollari USA: `{ "prompt": 1.0, "completion": 3.0 }`. Le route con un prezzo superiore vengono saltate; la route marketplace è vincolata ai venditori almeno tanto al di sotto del prezzo di listino del modello quanto richiesto dal tuo limite massimo. Se non rimane nulla, la richiesta viene rifiutata con `400 max_price_exceeded` e nulla viene addebitato. Quando imposti sia `prompt` che `completion`, una richiesta non viene mai fatturata al di sopra di essi per i token utilizzati.
`allow_fallbacks`	`false` disattiva i tentativi automatici di cui sopra; il primo fallimento ti viene restituito.
`data_collection`	Solo `"allow"` (il default) è accettato.
`zdr`, `require_parameters`	Solo `false` è accettato.

I suffissi del modello :floor e :nitro sono accettati e rimossi dall'id del modello; :floor ordina per prezzo e :nitro per throughput.

Per immagini, video, musica e parlato, ogni richiesta viene inviata a un provider terzo disponibile per il modello. provider.max_price è il costo massimo che una singola unità (immagine, secondo, megapixel, minuto, 1K caratteri o richiesta) può avere, come numero: { "max_price": 0.05 }; limita anche il conto. Ogni altra opzione provider viene rifiutata per i media.

Tag

Invia metadata, un oggetto con un massimo di 16 valori di testo (chiavi fino a 64 caratteri senza due punti, valori fino a 512), su qualsiasi richiesta:

{ "model": "deepseek/deepseek-v4-flash", "messages": [...],
  "metadata": { "project": "spring-ads", "run": "42" } }

I tag vengono memorizzati con la richiesta e non vengono mai inviati a un provider. Appaiono sulla richiesta in Dashboard → Attività, sullo stato di un lavoro video o musicale e nell'esportazione CSV (colonna metadata). Filtra l'Attività per tag con GET /api/v1/usage/activity?tag=project:spring-ads (ripeti tag per richiederne diversi); il link CSV applica lo stesso filtro. Su /v1/messages il metadata ({"user_id": "…"}) di Anthropic viene memorizzato allo stesso modo.