IT ▾
Ottieni la chiave API

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

Pannello di un editor di codice astratto con una chiave luminosa che viene inserita, una chiave inglese e una lente d'ingrandimento accanto
Ramificazione isometrica con percorsi verso un editor, un server e un terminale, che illustra la scelta di un'alternativa a Cursor

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.

  1. Chiave API OpenAI: incolla la tua chiave senza spazi o interruzioni di riga all'inizio o alla fine.
  2. Override URL base OpenAI: attiva l'override e inserisci https://api.cursorapikey.com/v1. Mantieni il /v1 e rimuovi /chat/completions.
  3. Modello personalizzato: aggiungi un modello chiamato uncensored e 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 vediCausa probabileSoluzione
401, "chiave non valida", "non autorizzato"Chiave digitata erroneamente, troncata o revocataCopiala di nuovo dalla pagina della chiave; controlla gli spazi finali
404, "non trovato"URL errato, manca /v1, o un percorso ripetutoUsa esattamente https://api.cursorapikey.com/v1
"modello non trovato" o simileIl nome del modello non corrisponde a uncensoredAggiungi il modello personalizzato con quel nome esatto, in minuscolo
429 con rate_limitedSuperato il limite di richieste al minutoRallenta; le chiavi di prova permettono 60 al minuto, quelle complete 300
429 con concurrencyTroppe richieste contemporaneamenteRiduci le esecuzioni parallele degli agent; 2 per la prova, 8 per la chiave completa
429 con Retry-After: 5Sovraccarico temporaneoAttendi cinque secondi e riprova
Funziona in curl, fallisce in CursorImpostazione non salvata, modello della scheda errato o funzionalità che non usa chiavi personalizzateVedi 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.

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.

01

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.