PT ▾
Obter chave de API

cursorapikey.com/Guia

Chaves de API do Cursor não funcionam: correções de endpoint personalizado

Quando as chaves de API do Cursor não funcionam, a causa é quase sempre uma de quatro coisas: a URL base, o nome do modelo, a própria chave ou um limite na conta. Um único comando curl indica qual é o problema.

Atualizado

Painel de editor de código abstrato com uma chave brilhante sendo inserida, uma chave inglesa e uma lupa ao lado
Vista isométrica com caminhos para um editor, um servidor e um terminal, ilustrando a escolha de uma alternativa ao Cursor

Pontos principais

  • Teste a chave fora do Cursor primeiro com curl; se o curl funcionar, o problema está nas configurações do Cursor.
  • A URL base deve ser https://api.cursorapikey.com/v1 e o nome do modelo deve ser exatamente uncensored.
  • 401 indica uma chave inválida, 404 uma URL inválida, 429 um limite de taxa ou concorrência, e um erro de modelo um nome incorreto.
  • Os rótulos do menu mudam entre as versões do Cursor, portanto, associe o propósito do campo em vez da formulação exata.

Etapa 1: teste a chave fora do Cursor

Remova o Cursor da equação. Se uma solicitação simples funcionar, sua chave e conta estão corretas e a falha está nas configurações do editor. Se falhar, o corpo do erro indica o 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."}]}'

A sinalização -i imprime a linha de status e os cabeçalhos. Um status 200 com uma matriz choices significa sucesso. O cabeçalho X-Balance-USD mostra seu crédito restante, que é a primeira coisa a verificar se você obtiver um erro de autenticação ou pagamento.

Você também pode listar modelos, o que confirma a chave sem gastar nada:

curl https://api.cursorapikey.com/v1/models -H "Authorization: Bearer YOUR_KEY" | grep uncensored

A resposta deve conter o ID do modelo uncensored.

Etapa 2: defina os campos no Cursor

Abra as configurações do Cursor e encontre a seção Modelos. Você precisa de três valores, e um erro em qualquer um deles produz uma falha que parece uma chave quebrada.

  1. Chave de API OpenAI: cole sua chave sem espaços ou quebras de linha nas extremidades.
  2. Substituir URL base OpenAI: ative a substituição e insira https://api.cursorapikey.com/v1. Mantenha o /v1 e remova o /chat/completions.
  3. Modelo personalizado: adicione um modelo chamado uncensored e ative-o. Desative os modelos que você não usa para que o Cursor não selecione um que o endpoint não reconheça.

Após salvar, use a opção de verificação se sua versão tiver uma, depois selecione uncensored no menu suspenso do modelo de chat. Uma nova aba de chat é um bom teste, pois uma aba antiga pode manter o modelo com que foi iniciada. O passo a passo em como usar a API do Cursor mostra a mesma configuração com mais contexto.

Associe o erro à correção

O que você vêCausa provávelCorreção
401, "chave inválida", "não autorizado"Chave digitada incorretamente, truncada ou revogadaCopie-a novamente da página da chave; verifique se há espaços no final
404, "não encontrado"URL incorreta, falta /v1 ou caminho duplicadoUse exatamente https://api.cursorapikey.com/v1
"modelo não encontrado" ou similarNome do modelo diferente de uncensoredAdicione o modelo personalizado com esse nome exato, em minúsculas
429 com rate_limitedAcima do limite de requisições por minutoReduza a velocidade; chaves de teste permitem 60 por minuto, chaves completas 300
429 com concurrencyMuitas requisições de uma vezReduza as execuções de agentes em paralelo; teste 2, chave completa 8
429 com Retry-After: 5Sobrecarga temporáriaAguarde cinco segundos e tente novamente
Funciona no curl, falha no CursorConfiguração não salva, modelo de aba incorreto ou recurso que não usa chaves personalizadasVeja a próxima seção

Requisições falhas ou recusadas não são cobradas, portanto, tentar novamente enquanto você depura não custa nada.

Quando o curl funciona mas o Cursor ainda falha

Este é o caso mais confuso e tem algumas explicações comuns.

O modelo errado está selecionado. O Cursor mantém seus próprios modelos embutidos na lista. Se um deles estiver selecionado, a solicitação não vai para o seu endpoint. Selecione explicitamente uncensored no menu suspenso do chat ou do compositor que você está usando.

Nem todos os recursos usam sua chave. Recursos que dependem dos próprios modelos do Cursor, como autocompletar em linha, podem continuar a usá-los independentemente da chave que você adiciona. Chaves personalizadas se aplicam onde você pode escolher o modelo, que são os modos de chat e edição. Verifique a documentação atual do Cursor, pois isso muda entre as versões.

Concorrência do modo agente. Agentes e execuções multi-etapas disparam várias requisições simultâneas. Uma chave de teste permite duas ao mesmo tempo. Se erros aparecerem apenas no modo agente, você provavelmente atingiu o limite de concurrency, e uma chave completa aumenta para oito. Uma requisição em streaming mantém sua vaga até o fim do fluxo, então outputs longos ocupam vagas por mais tempo.

Chamadas de ferramentas. A API suporta chamadas de ferramentas, com tool_calls em streaming e resultados passados de volta como role: "tool". A qualidade do uso de ferramentas depende do modelo, portanto, se uma execução de agente travar em uma etapa de ferramenta, tente a mesma tarefa no chat simples primeiro.

Verifique o lado da conta

Se o curl retornar um erro sobre o saldo, a chave é válida, mas o crédito está zerado ou o período de teste acabou. O crédito de teste é de $0,50, válido por 7 dias, obtido com um clique na página da chave de API após o login. Depois disso, você precisa recarregar.

Recargas são qualquer valor inteiro de $20 a $500, com +5% a partir de $50, +10% a partir de $100 e +15% a partir de $200. Você pode pagar com cripto (USDT no TRC20, USDC na Base). A página de preços mostra a tabela. Se você ainda não tem uma chave, obtenha uma aqui.

Mantenha uma chave por ferramenta. Se você colou uma chave em vários editores e scripts, os limites de requisições são compartilhados entre eles, o que pode parecer falhas aleatórias.

Verificação de script para um caso teimoso

Se você ainda não conseguir encontrar a causa, execute um script curto que replica o que o editor faz. Ele usa o SDK OpenAI, no qual os clientes estilo Cursor são baseados, e imprime o objeto de erro exato.

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 o script transmitir texto, o endpoint, a chave e o modelo estão corretos, e o problema restante é uma configuração do Cursor. Se ele imprimir um código de status, use a tabela acima. Mantenha o valor X-Request-Id quando entrar em contato com o suporte, pois ele identifica a solicitação exata. Os detalhes completos dos parâmetros estão na página de documentação.

Evite que quebre novamente

Alguns hábitos previnem a maioria dos problemas recorrentes. Armazene a chave em uma única entrada do gerenciador de senhas e copie de lá, em vez de logs de chat ou notas onde quebras de linha podem aparecer. Anote os três valores (URL base, chave, nome do modelo) para que você possa inseri-los novamente após uma atualização do editor, pois atualizações às vezes redefinem as sobrescritas. Após cada atualização, envie uma mensagem de chat curta antes de iniciar o trabalho real.

Monitore o saldo. O cabeçalho X-Balance-USD é retornado em cada resposta, e você também pode lê-lo de GET /v1/balance. O crédito nunca expira, portanto, uma recarga modesta na conta não é desperdiçada. Se você usar a chave de scripts além do editor, dê a trabalhos longos em lote um loop de tentativa que aguarde cinco segundos em um 429 e pare após algumas tentativas, para que um script não prive seu editor de seus slots de concorrência.

Uma solicitação de chat de codificação com 10.000 tokens de contexto de arquivo e uma resposta de 700 tokens custa 10.000 / 1.000.000 x $0,15 = $0,0015 para entrada e 700 / 1.000.000 x $0,50 = $0,00035 para saída, cerca de $0,00185 no total. As taxas são $0,15 por 1M tokens de entrada e $0,50 por 1M tokens de saída. O artigo sobre preços da API do Cursor cobre estimativas mensais.

Se a solicitação que falhou foi uma grande, lembre-se da janela: prompt mais conclusão devem caber em 100.000 tokens, e o corpo da solicitação é limitado a 8 MB. Anexar um repositório inteiro a um chat pode exceder ambos. Reduza o contexto para os arquivos importantes e tente novamente.

01

Perguntas e respostas

Por que o Cursor diz que minha chave de API é inválida?

Normalmente, a chave tem um espaço extra ou foi copiada parcialmente, ou a URL base ainda aponta para outro serviço. Copie novamente a chave e confirme se a URL de sobrescrita é https://api.cursorapikey.com/v1.

Qual nome de modelo eu insiro?

Digite uncensored, em minúsculas. É o único ID de modelo que a API oferece.

O autocomplete usa minha chave?

Não necessariamente. Alguns recursos do Cursor usam os próprios modelos do Cursor, e as chaves personalizadas aplicam-se principalmente aos modos de chat e edição, onde você escolhe o modelo.

Requisições falhas são cobradas?

Não. Requisições falhas ou recusadas não são cobradas, então tentar novamente enquanto você depura não custa nada.

Sua chave está a um passo de distância

Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.