cursorapikey.com/Guida
Chiavi API di Cursor non funzionano: correzioni per endpoint personalizzati
Quando le chiavi API di Cursor non funzionano, la causa è quasi sempre una di quattro cose: l'URL base, il nome del modello, la chiave stessa o un limite all'account. Un singolo comando curl ti dice quale sia.
Aggiornato


Punti chiave
- Testa la chiave fuori da Cursor prima con curl; se curl funziona, il problema è nelle impostazioni di Cursor.
- L'URL base deve essere https://api.cursorapikey.com/v1 e il nome del modello deve essere esattamente uncensored.
- 401 indica una chiave errata, 404 un URL errato, 429 un limite di richieste o concorrenza, e un errore del modello un nome sbagliato.
- Le etichette del menu cambiano tra le versioni di Cursor, quindi abbina lo scopo del campo piuttosto che la parola esatta.
Passaggio 1: testa la chiave fuori da Cursor
Togli Cursor di mezzo. Se una richiesta semplice funziona, la tua chiave e il tuo account sono a posto e il problema è nelle impostazioni dell'editor. Se fallisce, il corpo dell'errore indica il problema.
curl -i https://api.cursorapikey.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"Reply with the word ready."}]}'
Il flag -i stampa la riga di stato e le intestazioni. Uno status 200 con un array choices indica successo. L'intestazione X-Balance-USD mostra il tuo credito residuo, che è la prima cosa da controllare se ricevi un errore di autorizzazione o pagamento.
Puoi anche elencare i modelli, il che conferma la chiave senza spendere nulla:
curl https://api.cursorapikey.com/v1/models -H "Authorization: Bearer YOUR_KEY" | grep uncensored
La risposta dovrebbe contenere il model ID uncensored.
Passaggio 2: imposta i campi in Cursor
Apri le impostazioni di Cursor e trova la sezione Modelli. Ti servono tre valori e un errore in uno di essi produce un fallimento che sembra una chiave rotta.
- Chiave API OpenAI: incolla la tua chiave senza spazi o interruzioni di riga all'inizio o alla fine.
- Override URL base OpenAI: attiva l'override e inserisci
https://api.cursorapikey.com/v1. Mantieni il/v1e rimuovi/chat/completions. - Modello personalizzato: aggiungi un modello chiamato
uncensorede abilitalo. Disabilita i modelli che non usi in modo che Cursor non ne selezioni uno che l'endpoint non conosce.
Dopo il salvataggio, usa l'opzione di verifica se la tua versione ce l'ha, poi seleziona uncensored nel menu a discesa del modello di chat. Una nuova scheda di chat è un buon test, poiché una vecchia scheda potrebbe mantenere il modello con cui è stata avviata. La guida passo-passo in come usare l'API di Cursor mostra la stessa configurazione con più contesto.
Abbina l'errore alla soluzione
| Quello che vedi | Causa probabile | Soluzione |
|---|---|---|
| 401, "chiave non valida", "non autorizzato" | Chiave digitata erroneamente, troncata o revocata | Copiala di nuovo dalla pagina della chiave; controlla gli spazi finali |
| 404, "non trovato" | URL errato, manca /v1, o un percorso ripetuto | Usa esattamente https://api.cursorapikey.com/v1 |
| "modello non trovato" o simile | Il nome del modello non corrisponde a uncensored | Aggiungi il modello personalizzato con quel nome esatto, in minuscolo |
429 con rate_limited | Superato il limite di richieste al minuto | Rallenta; le chiavi di prova permettono 60 al minuto, quelle complete 300 |
429 con concurrency | Troppe richieste contemporaneamente | Riduci le esecuzioni parallele degli agent; 2 per la prova, 8 per la chiave completa |
429 con Retry-After: 5 | Sovraccarico temporaneo | Attendi cinque secondi e riprova |
| Funziona in curl, fallisce in Cursor | Impostazione non salvata, modello della scheda errato o funzionalità che non usa chiavi personalizzate | Vedi la sezione successiva |
Le richieste fallite o rifiutate non vengono addebitate, quindi riprovare durante il debug non costa nulla.
Quando curl funziona ma Cursor fallisce ancora
Questo è il caso più confuso e ha alcune spiegazioni comuni.
È selezionato il modello sbagliato. Cursor mantiene i propri modelli integrati nell'elenco. Se uno di essi è selezionato, la richiesta non va affatto al tuo endpoint. Seleziona esplicitamente uncensored nel menu a discesa della chat o del composer che stai usando.
Non tutte le funzionalità usano la tua chiave. Le funzionalità che si affidano ai modelli di Cursor, come l'autocompletamento inline, potrebbero continuare a usarli indipendentemente dalla chiave che aggiungi. Le chiavi personalizzate si applicano dove puoi scegliere il modello, ovvero le modalità chat e modifica. Controlla la documentazione corrente di Cursor, poiché questo cambia tra le release.
Concorrenza dalla modalità agent. Gli agent e le esecuzioni multi-step possono inviare più richieste contemporaneamente. Una chiave di prova ne consente due contemporanee. Se gli errori compaiono solo nella modalità agent, probabilmente stai superando il limite di concurrency, e una chiave completa lo porta a otto. Una richiesta in streaming occupa la sua slot fino alla fine dello streaming, quindi le risposte lunghe occupano le slot più a lungo.
Chiamate di strumenti. L'API supporta le chiamate di strumenti, con tool_calls in streaming e i risultati passati indietro come role: "tool". La qualità dell'uso degli strumenti dipende dal modello, quindi se un'esecuzione dell'agent si blocca su un passaggio di chiamata a strumento, prova lo stesso compito nella chat normale prima.
Controlla la sezione account
Se curl restituisce un errore relativo al saldo, la chiave è valida ma il credito è esaurito o la prova è scaduta. La prova offre $0,50, è valida per 7 giorni e si ottiene con un clic nella pagina della chiave API dopo la registrazione. Successivamente è necessario un ricaricamento.
Le ricariche sono qualsiasi importo intero da $20 a $500, con +5% da $50, +10% da $100 e +15% da $200. Puoi pagare con cripto (USDT su TRC20, USDC su Base). La pagina dei prezzi mostra la tabella. Se non hai ancora una chiave, prendine una qui.
Mantieni una chiave per strumento. Se hai incollato una chiave in diversi editor e script, i limiti di richieste sono condivisi tra di essi, il che può sembrare fallimenti apparentemente casuali.
Controllo script per un caso ostinato
Se ancora non riesci a trovare la causa, esegui uno script breve che replica ciò che fa l'editor. Usa l'SDK OpenAI, su cui sono modellati i client in stile Cursor, e stampa l'oggetto di errore esatto.
from openai import OpenAI, APIStatusError
client = OpenAI(base_url="https://api.cursorapikey.com/v1", api_key="YOUR_KEY")
try:
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write a one-line Python hello world."}],
stream=True,
)
for chunk in r:
print(chunk.choices[0].delta.content or "", end="")
except APIStatusError as e:
print(e.status_code, e.response.headers.get("X-Request-Id"))
print(e.response.text)
Se lo script trasmette testo, l'endpoint, la chiave e il modello sono corretti e il problema rimanente è un'impostazione di Cursor. Se stampa un codice di stato, usa la tabella sopra. Mantieni il valore X-Request-Id quando contatti il supporto, poiché identifica la richiesta esatta. I dettagli completi sui parametri sono nella pagina della documentazione.
Evita che si rompa di nuovo
Alcune abitudini prevengono la maggior parte dei problemi ricorrenti. Memorizza la chiave in una singola voce del gestore di password e copiala da lì, piuttosto che dai log della chat o dalle note dove le interruzioni di riga si insinuano. Scrivi i tre valori (URL base, chiave, nome del modello) in modo da poterli reinserire dopo un aggiornamento dell'editor, poiché gli aggiornamenti a volte resettano gli override. Dopo ogni aggiornamento, invia un breve messaggio di chat prima di iniziare il lavoro reale.
Monitora il saldo. L'intestazione X-Balance-USD viene restituita su ogni risposta e puoi anche leggerla da GET /v1/balance. Il credito non scade mai, quindi una ricarica modesta rimasta sull'account non è sprecata. Se usi la chiave sia dagli script che dall'editor, dai ai lavori batch lunghi un ciclo di retry che attende cinque secondi su un 429 e si ferma dopo alcuni tentativi, in modo che uno script non possa affamare il tuo editor dei suoi slot di concorrenza.
Controllo dei costi e cosa leggere dopo
Una richiesta di chat di codice con 10.000 token di contesto del file e una risposta di 700 token costa 10.000 / 1.000.000 × $0,15 = $0,0015 per l'input e 700 / 1.000.000 × $0,50 = $0,00035 per l'output, per un totale di circa $0,00185. I prezzi sono $0,15 per 1M di token di input e $0,50 per 1M di token di output. L'articolo sui prezzi dell'API di Cursor copre le stime mensili.
Se la richiesta fallita era di grandi dimensioni, ricorda il limite della finestra: prompt più completamento devono rientrare in 100.000 token e il corpo della richiesta è limitato a 8 MB. Allegare un'intera repository a una chat può superare entrambi i limiti. Riduci il contesto ai soli file necessari e riprova.
Altre guide
Domande e risposte
Perché Cursor segnala che la mia chiave API non è valida?
Di solito la chiave contiene uno spazio di troppo o è stata copiata parzialmente, oppure l'URL base punta ancora a un altro servizio. Copia di nuovo la chiave, quindi conferma che l'URL sovrascritto sia https://api.cursorapikey.com/v1.
Quale nome del modello devo inserire?
Inserisci uncensored, tutto in minuscolo. È l'unico ID del modello offerto dall'API.
L'autocompletamento usa la mia chiave?
Non necessariamente. Alcune funzionalità di Cursor utilizzano i modelli di Cursor e le chiavi personalizzate si applicano principalmente alle modalità chat e modifica, dove puoi scegliere il modello.
Le richieste fallite vengono addebitate?
No. Le richieste fallite o rifiutate non vengono addebitate, quindi riprovare mentre esegui il debug non costa nulla.
La tua chiave è a un modulo di distanza
Crea un account, copia la chiave, modifica l'URL di base. È tutta la configurazione.