Collega la chiave del tuo modello
Usa una chiave fornita da un provider di modelli o da un gateway. Per una connessione corretta, provider, endpoint, ID modello e autorizzazioni dell'account devono corrispondere.
Raccogli i dettagli della connessione
Ti servono una chiave API del servizio che intendi chiamare, il relativo URL di base dell'API, un ID modello disponibile e un protocollo o preset compatibile. Un account su un sito web di chat per utenti finali, da solo, non fornisce accesso all'API né crediti API.
Tutti i piani, incluso Free, supportano BYOK. La chiave del provider utilizza la fatturazione e le quote di quel provider, anziché il saldo di OpenDesign.
Aggiungi il provider
- Apri Settings → Models & providers → API providers.
- Scegli il preset del servizio che ha emesso la chiave. Per Custom provider, usa il protocollo indicato nella documentazione di quel servizio.
- Incolla in API Key soltanto il segreto. Non aggiungere Bearer, virgolette o un wrapper di configurazione JSON.
- Controlla Base URL. Se l'indirizzo di un preset è bloccato, usa la relativa opzione per l'URL personalizzato prima di inserire un altro endpoint.
- Scegli un modello dall'elenco disponibile oppure inserisci in Custom l'ID modello API esatto. Il caricamento dei modelli dipende dal servizio e dall'account.
- Esegui Test. Leggi la risposta: un test riuscito verifica questa piccola richiesta, non ogni strumento, modello multimediale o richiesta futura.
- Attendi la conferma del salvataggio. Riapri Settings per controllare provider, indirizzo e modello, quindi torna al progetto e seleziona quella connessione prima di inviare una piccola attività.
Mantieni privata la chiave. Puoi visualizzare il campo con Show per un controllo locale; oscuralo prima di condividere uno screenshot.
Esempio: DeepSeek
Crea una chiave su DeepSeek Platform. Usa https://api.deepseek.com come URL di base e scegli un modello che il tuo account può chiamare. Usa un ID dall'elenco attuale dei modelli del provider, ad esempio deepseek-flash; lo screenshot del client installato contiene ancora un alias di preset precedente. Quando necessario, inserisci l'ID attuale come modello personalizzato. Nella versione 0.25.0 installata, la scorciatoia Get key può aprire la pagina del provider sbagliato. Usa invece la console del provider, senza creare una chiave OpenAI non correlata.
| Campo | Esempio DeepSeek diretto |
|---|---|
| Provider / protocollo | Preset DeepSeek oppure un preset personalizzato compatibile con il protocollo OpenAI |
| API Key | Una chiave emessa dal tuo account DeepSeek Platform |
| Base URL | https://api.deepseek.com |
| ID modello | deepseek-flash, se abilitato per il tuo account |
Copia l'ID esatto dalla documentazione attuale dell'API DeepSeek, anziché il nome visualizzato in un vecchio screenshot. Per questo esempio basato sul protocollo OpenAI, non usare l'endpoint /anthropic separato.
Esempio: OpenRouter
Crea una chiave nelle impostazioni delle chiavi di OpenRouter. Usa https://openrouter.ai/api/v1. Copia un ID modello dall'elenco dei modelli disponibili di OpenRouter, incluso il prefisso del provider. Non inserire una chiave Anthropic o OpenAI diretta nel preset OpenRouter. La chiave deve appartenere al gateway che riceve la richiesta.
- Scegli OpenRouter in API providers e incolla una chiave emessa da OpenRouter.
- Usa https://openrouter.ai/api/v1 come Base URL.
- Copia l'ID modello esatto dalla directory dei modelli OpenRouter, incluso il prefisso del provider.
- Verifica la connessione, attendi il salvataggio e selezionala nel progetto prima di eseguire una richiesta.
Controlla un altro provider
| Dettaglio | Cosa verificare |
|---|---|
| Protocollo | Il preset deve corrispondere al protocollo API documentato. |
| Base URL | Usa la radice API prevista dal preset, senza un percorso della dashboard o un segmento di versione duplicato. |
| Modello | Usa l'ID modello API, non il relativo nome commerciale. |
| Autorizzazione | Verifica l'accesso al modello, la disponibilità regionale, la quota e la fatturazione nell'account del provider. |
Una chiave non costituisce l'intero ambiente di esecuzione
Le attività BYOK richiedono comunque il runtime supportato che esegue le operazioni dell'agente su file e strumenti. Se l'app segnala che il runtime non è disponibile, segui le istruzioni di installazione o di nuova scansione di quel runtime. Sostituire la chiave non installerà un eseguibile.
Comprendi la fatturazione
Le richieste BYOK vengono fatturate dal provider o dal gateway di cui hai inserito la chiave. Un abbonamento a OpenDesign e il saldo di un provider esterno sono separati. Consulta fatturazione e risoluzione dei problemi di connessione se una chiave valida non riesce comunque a eseguire un'attività.
Leggi il risultato del test e risolvi il problema
| Risultato | Azione successiva |
|---|---|
| 401 / chiave non valida | Controlla il servizio che ha emesso la chiave e incollala per intero senza formattazione aggiuntiva. Sostituisci una chiave revocata nel servizio di origine. |
| 403 / accesso negato | Verifica con il provider le autorizzazioni del modello, la regione e l'accesso dell'account. Un segreto valido, da solo, non concede l'accesso al modello. |
| 404 / modello non trovato | Controlla la radice API e l'ID modello esatto. Rimuovi i percorsi della dashboard e i segmenti /v1 duplicati. |
| 429 / quota o limite di frequenza | Leggi l'errore del provider per distinguere un saldo esaurito da un limite di frequenza temporaneo. Controlla la console dell'account prima di riprovare. |
| Timeout / errore di rete | Controlla se l'endpoint è raggiungibile dall'ambiente del client. Riprova con una piccola richiesta dopo aver risolto il problema di rete. |
Dopo un test riuscito, invia una piccola richiesta nel progetto esistente e controlla la risposta ed eventuali file creati. Se il test riesce ma le operazioni sui file non funzionano, controlla il runtime descritto nella sezione sull'ambiente di esecuzione; non sostituire ripetutamente una chiave funzionante.