---
title: "Migrare a un’API compatibile con OpenAI: checklist | BroadRouter"
description: "Cambiare base_url è la parte facile. Si rompono ID dei modelli, token di ragionamento, usage in streaming, errori, rate limit e chiavi. Una checklist con codice."
url: https://broadrouter.com/it/blog/openai-compatible-api-migration-checklist/
lang: it
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Tradotto dall’inglese con l’aiuto dell’IA. [Leggi l’originale in inglese](https://broadrouter.com/blog/openai-compatible-api-migration-checklist/) (aggiornato il 2026-11-16).

# Passare a un’API compatibile con OpenAI: la checklist di migrazione

A cura del team di BroadNet Inference · 5 min di lettura · Pubblicato 2026-11-14 · Aggiornato 2026-11-16

Per passare a un’API compatibile con OpenAI cambi tre impostazioni (base\_url, api\_key e model) e poi verifichi cosa è diverso: ID dei modelli, come i token di ragionamento contano in max\_tokens, come lo streaming riporta l’usage, quali errori ritentare, rate limit e sicurezza delle chiavi. Per BroadNet Inference la base URL è https://inference.broadnet.ai/v1.

## Punti chiave

-   Cambiano tre impostazioni: `base_url`, `api_key` e `model`.
-   Prima di cambiare, fai l’inventario di ogni endpoint e campo che la tua app usa, poi testali uno per uno.
-   I modelli di ragionamento contano il ragionamento in `max_tokens`; limiti bassi restituiscono risposte vuote.
-   Chiedi l’usage negli stream con `stream_options`, altrimenti il monitoraggio dei costi resta al buio.
-   Prima di spostare il traffico di produzione, decidi per ogni codice di errore se ritentare o correggere.
-   Fai girare vecchio e nuovo provider in parallelo sul traffico reale per un giorno prima del passaggio definitivo.

**In questa pagina**

1.  0\. Cosa usa oggi la tua app?
2.  1\. Quali sono le tre impostazioni da cambiare?
3.  2\. Quali sono i nuovi ID dei modelli?
4.  3\. Perché dopo il cambio le risposte arrivano vuote?
5.  4\. Lo streaming riporta ancora l’usage?
6.  5\. Quali errori conviene ritentare?
7.  6\. Quali sono i nuovi rate limit?
8.  7\. I tuoi prompt ci stanno ancora?
9.  8\. E le chiavi e la conservazione dei dati?
10.  9\. Come si fa il passaggio in sicurezza?
11.  Quali sono gli errori di migrazione più comuni?
12.  Dove si colloca BroadNet Inference

Ormai quasi tutti i provider LLM parlano il [formato dell’API di OpenAI](https://broadrouter.com/it/glossary/openai-compatible-api/). Così il cambio sembra una modifica di una riga, e per ottenere una prima risposta lo è davvero. Per portare traffico di produzione, invece, segui questa lista. Ogni voce nasce da un modo reale in cui le migrazioni si rompono.

## 0\. Cosa usa oggi la tua app?

Prima di cambiare qualsiasi cosa, annota da cosa dipende la tua app. Cerca nel codice ogni chiamata all’SDK ed elencale. Se chiami l’API Whisper di OpenAI, tieni presente che OpenAI indica la dismissione di `whisper-1` il 26 febbraio 2027; per la parte audio vedi [alternative all’API Whisper](https://broadrouter.com/it/blog/whisper-api-alternative/).

| Funzione | Dove guardare | Test dopo il cambio |
| --- | --- | --- |
| Chat completions | Ogni `chat.completions.create` | Stessi prompt, confronta le risposte |
| Streaming | `stream=True` | I chunk arrivano, finisce con `[DONE]`, usage presente |
| Tool calling | `tools=` | Le chiamate ai tool si parsano e si eseguono |
| Output strutturato | `response_format=` | Il JSON è valido rispetto al tuo schema |
| Immagini | Parti immagine nei messaggi | Il modello le accetta |
| Trascrizione audio | `audio.transcriptions` | Testo e lingua corretti |
| Embeddings, file, batch | Altri endpoint | Verifica che il provider li offra |

L’ultima riga conta. «Compatibile con OpenAI» di solito copre prima di tutto le chat completions. Il catalogo di BroadNet Inference elenca modelli chat su `/v1/chat/completions` e modelli speech-to-text su `/v1/audio/transcriptions`; se usi altri endpoint, lasciali sul provider attuale o trova un sostituto.

## 1\. Quali sono le tre impostazioni da cambiare?

```python
from openai import OpenAI
import os

client = OpenAI(
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
)
```

Il nome dell’impostazione della [base URL](https://broadrouter.com/it/glossary/base-url/) cambia da libreria a libreria: `base_url` nell’SDK Python e in ChatOpenAI di LangChain, `baseURL` nell’SDK Node.js. Secondo il suo [README](https://github.com/openai/openai-python), l’SDK Python legge anche la variabile d’ambiente `OPENAI_BASE_URL`. Controlla che nel tuo ambiente non sia rimasto un valore vecchio, altrimenti le richieste possono finire al vecchio provider senza alcun errore.

Tieni le [chiavi API](https://broadrouter.com/it/glossary/api-key/) in variabili d’ambiente o in un secret manager, mai nel codice. Configurazione per ciascun SDK: [Python](https://broadrouter.com/it/guides/openai-python-sdk/), [Node.js](https://broadrouter.com/it/guides/openai-node-sdk/), [LangChain](https://broadrouter.com/it/guides/langchain-openai-base-url/). Per costruire e provare a mano una prima richiesta, usa il [costruttore di richieste API](https://broadrouter.com/tools/api-request-builder/). Per applicare le modifiche a base URL, chiave e modello al codice esistente, incollalo nell’[assistente di migrazione da OpenAI a BroadNet](https://broadrouter.com/tools/openai-to-broadnet-migration/), che elenca anche cosa controllare.

## 2\. Quali sono i nuovi ID dei modelli?

Ogni provider dà ai modelli nomi suoi. Su BroadNet Inference:

| Modello | ID |
| --- | --- |
| DeepSeek V4.1 Flash | `broadnet/deepseek-v4.1-flash` |
| GLM 5.3 | `broadnet/glm-5.3` |
| Qwen3.8 27B | `broadnet/qwen3.8-27b` |
| Gemma 4 VL 26B | `broadnet/gemma-4-26b-a4b` |

Metti l’ID del modello nella configurazione, non nel codice, così un cambio futuro è un deploy e non una riscrittura. Limiti e prezzi di ogni modello sono nella sua pagina: [DeepSeek V4.1 Flash](https://broadrouter.com/it/models/deepseek-v4.1-flash/), [GLM 5.3](https://broadrouter.com/it/models/glm-5.3/), [Qwen3.8 27B](https://broadrouter.com/it/models/qwen3.8-27b/) e [Gemma 4 VL 26B](https://broadrouter.com/it/models/gemma-4-vl-26b/).

## 3\. Perché dopo il cambio le risposte arrivano vuote?

È la sorpresa più comune. DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B ragionano prima di rispondere, e **i [token di ragionamento](https://broadrouter.com/it/glossary/reasoning-tokens/) contano in [`max_tokens`](https://broadrouter.com/it/glossary/max-tokens/)**. Un limite di 256 che andava bene con un modello senza ragionamento può finire tutto nel ragionamento, e la risposta arriva vuota. Lascia 1.000 token o più, oppure imposta `reasoning_effort` su `low` per i compiti semplici. [Spiegazione completa](https://broadrouter.com/it/guides/reasoning-tokens-empty-response/).

## 4\. Lo streaming riporta ancora l’usage?

Gli [stream](https://broadrouter.com/it/glossary/streaming/) usano i Server-Sent Events e finiscono con `data: [DONE]`. L’usage dei token arriva nell’ultimo chunk solo se lo chiedi:

```python
stream = client.chat.completions.create(
    model="broadnet/deepseek-v4.1-flash", messages=messages,
    stream=True, stream_options={"include_usage": True},
)
```

Senza questa opzione la tua dashboard dei costi segna zero. Se uno stream si chiude prima di `[DONE]`, consideralo incompleto. [Guida allo streaming](https://broadrouter.com/it/guides/streaming-chat-completions/).

## 5\. Quali errori conviene ritentare?

| Stato | Significato | Cosa fare |
| --- | --- | --- |
| 401 | Chiave errata o revocata, oppure plafond a consumo esaurito | Correggi, non ritentare |
| 402 | Saldo o budget | Ricarica, non ritentare |
| 403 | Rifiutata dalla policy su modello, percorso o IP | Correggi la discrepanza |
| 413 | Richiesta troppo grande | Riducila, non ritentare |
| 429 | Limite di frequenza, concorrenza o spesa | Backoff e retry |
| 5xx | Lato server | Retry con backoff limitato |

L’SDK Python ufficiale ritenta già alcuni errori: il README dice che errori di connessione, 408, 409, 429 e risposte 5xx vengono ritentati due volte di default con un breve backoff esponenziale. Imposta `max_retries` in modo esplicito, così il comportamento è una tua scelta e non un default. Registra nei log l’ID richiesta di ogni risposta, così il supporto può ricostruire un problema. [Tutti i codici](https://broadrouter.com/it/guides/errors-and-retries/).

## 6\. Quali sono i nuovi rate limit?

Conosci i nuovi limiti prima che arrivi il traffico. Una chiave BroadNet a consumo consente 30 richieste al minuto e 4 in corso. I piani illimitati eseguono una richiesta alla volta per sessione. Dimensiona il pool di worker di conseguenza, o vedrai dei 429 dal primo giorno; il [calcolatore dei rate limit](https://broadrouter.com/tools/llm-rate-limit-calculator/) fa il dimensionamento. Vedi [dimensionare per agenti in parallelo](https://broadrouter.com/it/blog/run-parallel-coding-agents-flat-rate/).

## 7\. I tuoi prompt ci stanno ancora?

Controlla le finestre di contesto: 1.048.576 token su DeepSeek V4.1 Flash e GLM 5.3, 262.144 su Qwen3.8 27B, 32.768 su Gemma 4 VL 26B. Un prompt che stava nel vecchio modello potrebbe non stare in una finestra più piccola; verificalo con il [calcolatore della finestra di contesto](https://broadrouter.com/tools/context-window-calculator/). Metti all’inizio la parte stabile del prompt per sfruttare il [prezzo dell’input in cache](https://broadrouter.com/it/blog/cached-input-tokens-explained/).

## 8\. E le chiavi e la conservazione dei dati?

Blocca le chiavi di produzione sugli IP dei tuoi server con un [elenco di IP consentiti](https://broadrouter.com/it/guides/api-keys-ip-allow-lists/). Chiedi al nuovo provider cosa conserva; vedi la [checklist ZDR](https://broadrouter.com/it/blog/zero-data-retention-llm-api-checklist/).

## 9\. Come si fa il passaggio in sicurezza?

1.  Invia a entrambi i provider una copia delle richieste reali di un giorno.
2.  Confronta le risposte su un campione, più latenza, errori e costo per richiesta.
3.  Sposta il 10% del traffico, osserva per un giorno, poi sposta il resto.
4.  Tieni configurato il vecchio provider come fallback per una settimana.

Se gestisci molti servizi, un proxy come [LiteLLM](https://broadrouter.com/it/guides/litellm-proxy-custom-provider/) ti permette di cambiare provider in un solo punto invece che in ogni app.

## Quali sono gli errori di migrazione più comuni?

-   **Manca `/v1` nella base URL.** Le richieste restituiscono 404. Usa l’URL completo.
-   **Vecchi nomi dei modelli nella configurazione.** Il nuovo provider non li conosce.
-   **Campi specifici del provider rimasti nelle richieste.** I campi che capiva solo il vecchio provider possono essere rifiutati o ignorati. Toglili dai client generici.
-   **Testare un solo prompt.** Ripercorri l’inventario del passo 0, funzione per funzione.
-   **Fare il passaggio di venerdì.** Lasciati il tempo di osservare un’intera giornata di traffico reale.

## Dove si colloca BroadNet Inference

BroadNet Inference è un sostituto diretto per le app che usano chat completions e trascrizione audio tramite gli SDK di OpenAI: cambi tre impostazioni e segui la lista qui sopra. Il suo catalogo elenca solo modelli chat e speech-to-text, quindi se dipendi da altri endpoint, come embeddings o archiviazione di file, lasciali presso un altro provider. I nuovi account partono con $5 di credito. Tra i modelli chat, ci gira solo Gemma 4 VL 26B (copre anche i due modelli Transcribe), quindi un test in parallelo su DeepSeek, GLM o Qwen richiede una ricarica.

Strumenti gratuiti sul tema (in inglese)

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[Strumenti gratuiti (in inglese)](https://broadrouter.com/tools/)

## Termini in questo articolo

[Streaming](https://broadrouter.com/it/glossary/streaming/)

Lo streaming è un modo di restituire la risposta di un modello linguistico in piccoli pezzi mentre viene ancora generata, invece che in un’unica risposta alla fine. Le API compatibili con OpenAI trasmettono in streaming tramite server-sent event quando la richiesta imposta stream a true.

[Token](https://broadrouter.com/it/glossary/token/)

Un token è l’unità di testo che un modello linguistico legge e scrive: una parola, una parte di parola, un segno di punteggiatura o una sequenza di byte prodotta dal tokenizer del modello. Le API LLM contano, limitano e di solito fatturano l’uso in token.

[Rate limit (limite di frequenza)](https://broadrouter.com/it/glossary/rate-limit/)

Un rate limit è un tetto che un’API pone a quanto un client può usarla in un intervallo di tempo, per esempio richieste al minuto o token al minuto. Le richieste oltre il limite vengono rifiutate, di solito con HTTP 429 Too Many Requests, finché l’uso non torna sotto la soglia.

[Base URL (URL di base)](https://broadrouter.com/it/glossary/base-url/)

La base URL è l’indirizzo radice fisso di un’API, come https://api.example.com/v1, che un client antepone a ogni percorso di endpoint, come /chat/completions. Negli SDK compatibili con OpenAI, cambiare la base URL, insieme alla chiave API e all’ID del modello, punta lo stesso codice verso un altro provider.

[Embedding (embeddings)](https://broadrouter.com/it/glossary/embeddings/)

Gli embedding sono liste di numeri in virgola mobile (vettori) che un modello produce per rappresentare un testo, un’immagine o un altro input. Input con significato simile ottengono vettori vicini tra loro, quindi la distanza tra vettori serve a ordinare i risultati di ricerca, raggruppare documenti o trovare elementi correlati.

[Speech-to-text (riconoscimento vocale)](https://broadrouter.com/it/glossary/speech-to-text/)

Lo speech-to-text, detto anche riconoscimento automatico del parlato (ASR), è la tecnologia che converte l’audio parlato in testo scritto. Un’API speech-to-text riceve un file o uno stream audio e restituisce una trascrizione, di solito a prezzo per minuto di audio. L’accuratezza si misura con il word error rate e varia con accento, dialetto e qualità della registrazione.

[Tool calling (chiamata di strumenti)](https://broadrouter.com/it/glossary/tool-calling/)

Il tool calling, detto anche function calling, è una funzionalità delle API LLM in cui il modello restituisce una richiesta strutturata di eseguire una funzione definita dallo sviluppatore, con argomenti JSON. L’applicazione esegue la funzione e rimanda il risultato; il modello non esegue mai codice da solo.

[Pagamento a consumo (pay-as-you-go)](https://broadrouter.com/it/glossary/pay-as-you-go/)

Il pagamento a consumo è un modello di prezzo in cui paghi solo ciò che usi, misurato per unità come token, richieste o minuti di audio, senza abbonamento né impegno minimo. La maggior parte delle API LLM fattura così, da un saldo prepagato o con una fattura periodica.

## Domande frequenti

### Mi serve un SDK diverso?

No. Gli SDK ufficiali di OpenAI per Python e Node.js accettano una base URL personalizzata. La accettano anche i framework costruiti sopra, come ChatOpenAI di LangChain.

### Come cambio la base URL nell’SDK di OpenAI?

Passa base\_url al client in Python o baseURL in Node.js, oppure imposta la variabile d’ambiente OPENAI\_BASE\_URL. Per BroadNet Inference il valore è https://inference.broadnet.ai/v1 e la chiave va in api\_key.

### Perché dopo il cambio ricevo risposte vuote?

I modelli di ragionamento come DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B ragionano prima di rispondere, e il ragionamento conta in max\_tokens. Alza max\_tokens a 1.000 o più, oppure imposta reasoning\_effort su low.

### Perché dopo il cambio ricevo un 404 o un errore «model not found»?

Di solito l’ID del modello è ancora il nome usato dal vecchio provider, oppure alla base URL manca il percorso /v1. Usa l’ID esatto del nuovo provider e la base URL completa.

### Quali errori devo ritentare?

Ritenta 429 e 5xx con un backoff esponenziale limitato. Correggi 401, 402 e 413 prima di ritentare. La guida agli errori di questo sito elenca tutti i codici.

### Compatibile con OpenAI vuol dire identico?

No. La forma di richieste e risposte è la stessa, ma ID dei modelli, parametri supportati, limiti, campi di usage e dettagli degli errori possono cambiare. Testa ogni funzione che la tua app usa.

## Continua a leggere

-   [Base URL delle API compatibili con OpenAI: 14 provider verificati](https://broadrouter.com/it/blog/openai-compatible-api-base-urls/)
-   [OpenRouter o piano flat per agenti AI: quale costa meno?](https://broadrouter.com/it/blog/openrouter-alternative-flat-rate/)
-   [Quando conviene una finestra di contesto da 1M di token (e quando no)](https://broadrouter.com/it/blog/million-token-context-window-guide/)
-   [API LLM con zero data retention: una checklist di 10 domande](https://broadrouter.com/it/blog/zero-data-retention-llm-api-checklist/)
-   [Hardware GPU e serving di BroadNet, come li descrive BroadNet](https://broadrouter.com/it/blog/broadnet-gpu-fleet-and-serving/)
-   [Cache delle risposte delle API LLM: una cache esatta in Python](https://broadrouter.com/it/blog/cache-llm-responses-cut-cost/)
-   [Guida: Usare l’SDK Python di OpenAI con BroadNet Inference](https://broadrouter.com/it/guides/openai-python-sdk/)
-   [Guida: Usare l’SDK Node.js di OpenAI con BroadNet Inference](https://broadrouter.com/it/guides/openai-node-sdk/)
-   [Guida: Usare LangChain con BroadNet Inference](https://broadrouter.com/it/guides/langchain-openai-base-url/)
-   [Guida: Codici di errore di BroadNet Inference e quando ritentare](https://broadrouter.com/it/guides/errors-and-retries/)
-   [Guida: Streaming delle chat completions e connessioni interrotte](https://broadrouter.com/it/guides/streaming-chat-completions/)
-   [Guida: Perché un modello di ragionamento restituisce una risposta vuota](https://broadrouter.com/it/guides/reasoning-tokens-empty-response/)
-   [Guida: Instradare LiteLLM verso BroadNet Inference (SDK e proxy)](https://broadrouter.com/it/guides/litellm-proxy-custom-provider/)

Provalo sul tuo carico di lavoro reale. I nuovi account partono con USD 5 di credito per Gemma e trascrizione. DeepSeek, GLM e Qwen3.8 richiedono una ricarica.

[Inizia](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-blog-openai-compatible-api-migration-checklist&utm_content=page-cta) ·

**Fonti**

-   [Riferimento API di BroadNet Inference (in inglese)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-blog-openai-compatible-api-migration-checklist&utm_content=sources)
-   [README dell’SDK Python di OpenAI (base\_url, OPENAI\_BASE\_URL, retry; verificato il 2026-11-14)](https://github.com/openai/openai-python)
