Endpoint personalizzati e Base URL

Endpoint API personalizzato: come collegare un’API compatibile con OpenAI

Cosa sono un endpoint API personalizzato e il Base URL, e come collegare un’API compatibile con OpenAI, un relay, un proxy o un gateway con indirizzo e chiave.

Aggiornato il
  • Un endpoint API personalizzato è l’indirizzo web, o Base URL (indirizzo base), di un servizio di IA che non è integrato nella tua app: per esempio un’API compatibile con OpenAI, un servizio intermediario (relay), un proxy o un gateway. In Oriveo, per collegarlo di solito bastano due cose: quell’indirizzo e un’API key.
  • Oriveo riconosce da solo il protocollo (OpenAI Chat Completions, OpenAI Responses, Anthropic Messages o Gemini) e aggiunge il percorso della versione, come /v1, quando inserisci solo l’indirizzo principale.
  • Gli indirizzi pubblici devono usare HTTPS. Un servizio di terze parti può vedere tutto ciò che ci passa attraverso: usa una chiave dedicata con un limite di spesa e non dargli mai la chiave del tuo account ufficiale presso il fornitore.
Oriveo su iPhone: la schermata dei fornitori, con i fornitori che hai collegato e la spesa del mese.

Che cos’è un Base URL o un endpoint API?

Ogni servizio di IA ha un indirizzo web a cui le app inviano le richieste. Gli sviluppatori lo chiamano Base URL, endpoint API o URL della richiesta: qui indicano la stessa cosa. Ha l’aspetto di un normale indirizzo web; quello di OpenAI, per esempio, è https://api.openai.com/v1.

In Oriveo i 15 fornitori integrati hanno già il loro indirizzo impostato, quindi basta incollare una chiave. Un endpoint personalizzato serve per tutto il resto: un servizio che offre un’API compatibile con OpenAI, un servizio intermediario o un gateway gestito da un’azienda, oppure un gateway che fai girare sul tuo server.

«Compatibile con OpenAI» significa che il servizio accetta richieste nello stesso formato dell’API di OpenAI, quindi le app pensate per OpenAI possono usarlo. Molti fornitori e gateway offrono questo formato.

Relay (servizio intermediario), proxy, gateway: che differenza c’è?

Questi termini si usano spesso come sinonimi e, quando si tratta di collegare un’app, il funzionamento è lo stesso: un servizio si mette tra la tua app e i fornitori dei modelli, riceve la richiesta e la inoltra. Alcuni riuniscono più fornitori dietro una sola chiave e una sola fattura; altri aggiungono controlli sull’uso per un team; altri ancora sono software che installi sul tuo server.

Oriveo non ne consiglia né ne classifica nessuno. Qualunque tu usi, i passaggi qui sotto sono gli stessi.

Che cosa serve per collegare un endpoint personalizzato?

Di solito due cose, che trovi entrambe nella dashboard o nella documentazione del servizio:

  • L’URL della richiesta (Base URL), per esempio https://api.example.com/v1. Se il servizio è su internet pubblico, deve iniziare con https://.
  • Un’API key che il servizio ti ha rilasciato. Puoi aggiungere altre chiavi con «Aggiungi un’altra chiave».
  • Facoltativo: un nome per la connessione, per distinguerla dalle altre.

Come aggiungere un endpoint personalizzato in Oriveo?

I passaggi sono gli stessi su iPhone, Android e web.

  • Apri «Fornitori» e tocca il pulsante + («Aggiungi fornitore»).
  • Scegli il filtro «Personalizzato», poi «Servizio intermediario personalizzato» («Collega il tuo servizio di modelli»).
  • In «Collega un servizio intermediario personalizzato» incolla l’URL della richiesta e la chiave API. La riga «Richiederà …» mostra l’indirizzo completo che Oriveo userà. Tocca «Avanti».
  • Oriveo verifica la connessione, legge l’elenco dei modelli e individua il protocollo di ciascuno. In questo passaggio legge l’elenco senza inviare nessun messaggio di chat.
  • Spunta i modelli che vuoi e tocca «Salva (N selezionati)». Se il servizio non elenca i suoi modelli, usa «Aggiungi ID modello manualmente».
  • Prima di salvare, Oriveo invia una richiesta minima al primo modello selezionato. La connessione viene salvata se il test va a buon fine; se non riesce, resti allo stesso passaggio e puoi correggere i dati.
Schermata «Fornitori» di Oriveo su iPhone, con il pulsante + in alto a destra e l’elenco dei fornitori collegati
Tocca + nella schermata «Fornitori» e scegli «Personalizzato» per aggiungere un endpoint accanto ai fornitori integrati.

Preferisci impostare tutto da te? Usa la configurazione manuale

La «Configurazione manuale» mette tutto in una sola pagina: l’indirizzo, la chiave, un ID modello, un nome facoltativo per la connessione e il protocollo predefinito, che all’inizio è impostato su automatico. Tocca «Convalida e salva». Se la verifica non riesce, non viene ancora salvato nulla, e la scheda dell’errore offre «Salva comunque (non verificato)» se vuoi tenere la connessione e provarla più tardi.

Oriveo riconosce il protocollo da solo?

Quasi sempre sì. Ogni servizio di IA usa uno tra pochi formati di richiesta, chiamati protocolli. Oriveo ne supporta quattro: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages e Gemini generateContent.

Decide modello per modello. Usa quello che il servizio dice di ogni modello, quando questa informazione c’è, e altrimenti sceglie i candidati più probabili in base alla famiglia del modello. Quando salvi, il primo modello selezionato viene provato con una richiesta reale; gli altri vengono verificati più tardi, quando inizi a usarli.

Quindi nella maggior parte dei casi bastano indirizzo e chiave. Se la documentazione del servizio indica un protocollo preciso, o se un modello non supera la verifica, scegli tu il protocollo nella configurazione manuale.

Devo aggiungere /v1 all’indirizzo?

Di solito no. Se inserisci solo l’indirizzo principale, come https://api.example.com, Oriveo aggiunge il percorso di versione standard per il protocollo: /v1 per i formati OpenAI e Anthropic, /v1beta per Gemini.

Se l’indirizzo contiene già una versione, come /api/paas/v4, Oriveo la mantiene. Se incolli un endpoint completo che termina con /chat/completions, /responses, /messages o :generateContent, Oriveo toglie quella parte finale e la usa per capire quale protocollo usa il servizio.

Controlla la riga «Richiederà …» prima di toccare «Avanti». Se la verifica dice «L’indirizzo potrebbe puntare a una pagina web. Controlla se manca /v1.», confronta il tuo indirizzo con la documentazione del servizio.

Devo aggiungere /v1 all’indirizzo?
InserisciOriveo richiede (formato OpenAI)
https://api.example.comhttps://api.example.com/v1
https://api.example.com/v1https://api.example.com/v1
https://api.example.com/v1/chat/completionshttps://api.example.com/v1, con Chat Completions
https://api.example.com/api/paas/v4https://api.example.com/api/paas/v4

Quali indirizzi sono consentiti?

Oriveo segue alcune regole per proteggere la tua chiave:

  • Gli indirizzi pubblici devono iniziare con https://. Un indirizzo http:// su internet pubblico non può essere provato né salvato.
  • Non sono accettati indirizzi che contengono nome utente e password, né indirizzi con parametri di query (tutto ciò che segue un «?»). Oriveo non prova mai a leggere chiavi API dai parametri di query.
  • Gli indirizzi con il semplice http:// sulla rete di casa o su una VPN privata, come un server di modelli sul tuo computer, si aggiungono dalla voce separata «Calcolo locale» invece che da «Servizio intermediario personalizzato».
  • Su iPhone e Android l’app si collega direttamente all’indirizzo.
  • Nell’app web, gli URL di richiesta pubblici vengono inoltrati tramite il server di Oriveo per aggirare i limiti CORS del browser (una regola di sicurezza dei browser che blocca molte richieste dirette): la tua chiave API resta in memoria solo per quella richiesta e non viene mai salvata né registrata. Gli indirizzi della rete locale si connettono direttamente dal tuo dispositivo, e in entrambi i casi è richiesto HTTPS; per un indirizzo con il semplice http:// sulla rete di casa servono l’app per iPhone o Android e la sua voce «Calcolo locale».
  • Le chiavi restano su questo dispositivo e non vengono caricate dalla sincronizzazione cloud.

Base URL dei fornitori integrati

In Oriveo non ti servono: basta scegliere il fornitore per nome. Li elenchiamo perché spesso si cercano per configurare altri strumenti. Ognuno è l’indirizzo ufficiale compatibile con OpenAI indicato nella documentazione del fornitore, al 18 novembre 2026.

  • Anthropic descrive il suo livello di compatibilità con OpenAI come pensato per test e confronti, e la guida rapida di Mistral non descrive la sua API come compatibile con OpenAI. Collegali invece entrambi come fornitori integrati.
Base URL dei fornitori integrati
FornitoreBase URL compatibile con OpenAI
OpenAIhttps://api.openai.com/v1
Google Geminihttps://generativelanguage.googleapis.com/v1beta/openai/
OpenRouterhttps://openrouter.ai/api/v1
DeepSeekhttps://api.deepseek.com
xAI (Grok)https://api.x.ai/v1
Groqhttps://api.groq.com/openai/v1
Together AIhttps://api.together.ai/v1
Fireworks AIhttps://api.fireworks.ai/inference/v1
MiniMax (internazionale)https://api.minimax.io/v1
Z.ai (internazionale)https://api.z.ai/api/paas/v4/
Qwen (regione di Singapore)https://dashscope-intl.aliyuncs.com/compatible-mode/v1
Kimi (internazionale)https://api.moonshot.ai/v1
SiliconFlow (internazionale)https://api.siliconflow.com/v1

È sicuro usare un servizio intermediario o un’API di terze parti?

Fai attenzione. Qualsiasi servizio tra te e il modello può leggere i tuoi prompt, i file che alleghi e le risposte, e stabilisce i propri prezzi. Oriveo non può vedere al suo interno né garantire per quel servizio.

  • Non dare mai a un servizio di terze parti l’API key del tuo account ufficiale presso il fornitore. Usa la chiave che il servizio ti rilascia.
  • Crea una chiave dedicata a Oriveo e, se il servizio lo consente, imposta un limite di spesa o tieni basso il saldo.
  • Non inviare password, numeri di documenti d’identità o lavoro riservato tramite un servizio di cui non ti fidi.
  • Controlla i consumi nella dashboard del servizio. I costi mostrati da Oriveo sono stime; fanno fede i registri del servizio.
  • Se una chiave trapela, eliminala dalla dashboard del servizio e creane una nuova.

Perché il mio endpoint personalizzato non si collega?

Oriveo ti dice in una riga che cosa è andato storto. Ecco i messaggi, come compaiono nell’app in italiano:

  • Per codici come 401, 402 e 429, la nostra guida agli errori delle API key spiega che cosa significa ciascuno.
Perché il mio endpoint personalizzato non si collega?
Messaggio in OriveoChe cosa controllare
L’indirizzo potrebbe puntare a una pagina web. Controlla se manca /v1.Confronta l’indirizzo con la documentazione del servizio; aggiungi o togli il percorso della versione
La chiave non è valida.Copia di nuovo la chiave dalla dashboard del servizio
Questa chiave non può elencare i modelli. Puoi aggiungere i modelli manualmente.Aggiungi tu l’ID del modello nel passaggio successivo
Impossibile connettersi. Controlla la rete o il proxy.Controlla la connessione a internet e che l’indirizzo sia raggiungibile
Il servizio a questo indirizzo sta limitando le richieste.Aspetta un momento e riprova
Questa connessione non ha raggiunto il fornitore a monte.L’account che il servizio ha presso il fornitore potrebbe non essere valido, essere senza credito o aver raggiunto un limite di richieste; contatta chi gestisce il servizio

Domande frequenti

Che cos’è un endpoint API personalizzato?
È l’indirizzo web di un servizio di IA che non è integrato nella tua app, come un’API compatibile con OpenAI, un servizio intermediario o un gateway. Lo colleghi inserendo quell’indirizzo (il Base URL) e un’API key rilasciata dal servizio.
Che cos’è un’API compatibile con OpenAI?
Un’API che accetta richieste nello stesso formato di quella di OpenAI, così le app pensate per OpenAI possono usarla. Molti fornitori e gateway ne offrono una, di solito a un indirizzo che termina con /v1.
Quale Base URL devo inserire?
Quello indicato nella documentazione del servizio. Se indica solo un dominio, inserisci quello e Oriveo aggiunge /v1 (o /v1beta per il formato Gemini). Prima di continuare, controlla la riga «Richiederà …».
Posso usare un endpoint personalizzato su iPhone e Android?
Sì. La voce «Servizio intermediario personalizzato» è presente nelle app Oriveo per iPhone e Android e nell’app web. Su iPhone e Android l’app si collega direttamente all’indirizzo.
Perché Oriveo richiede HTTPS?
HTTPS cifra la connessione, così la chiave e i messaggi non viaggiano in chiaro su internet. Per un server di modelli sulla rete di casa, usa la voce «Calcolo locale».
È sicuro usare un relay o un proxy per le API?
Può leggere tutto ciò che gli invii, quindi conta la fiducia. Usa una chiave rilasciata dal servizio, mai la chiave ufficiale del fornitore, imposta un limite di spesa e non farci passare informazioni sensibili.

Letture correlate

Collega il tuo servizio di modelli

Apri l’app web o scarica Oriveo per iPhone o Android, scegli «Servizio intermediario personalizzato» e incolla l’indirizzo e la chiave del tuo servizio.

Non hai ancora una chiave API? Con Oriveo Free puoi iniziare senza.