A configuração da API compatível com OpenAI do Cursor parece simples se você pensar apenas em três campos: chave de API, URL de base e nome do modelo. Na prática, o Cursor é uma ferramenta de codificação de nível superior com seu próprio seletor de modelos, contabilidade de uso, controles de equipe e caminho de construção de prompts, então a configuração mais segura é um fluxo de trabalho de verificação em vez de um copiar e colar cego.
De acordo com a documentação pública da chave de API do Cursor verificada em 8 de julho de 2026, o Cursor documenta o uso de sua própria chave de API (Bring Your Own API Key) para provedores nomeados em Configurações do Cursor > Modelos. Ele documenta chaves para OpenAI, Anthropic, Google, Azure OpenAI e AWS Bedrock; também informa que chaves de API personalizadas funcionam apenas com modelos de chat, a conclusão por Tab continua usando os modelos integrados do Cursor, e as solicitações com chave própria ainda passam pelos servidores do Cursor para a construção final do prompt. A documentação pública não menciona um campo geral arbitrário para URL de base compatível com OpenAI.
Isso é importante para os usuários do Flatkey. O Flatkey oferece às equipes uma única chave, um gateway compatível com OpenAI em https://router.flatkey.ai/v1, acesso a modelos de vários provedores e revisão de uso e custos em um só lugar. Se a sua compilação do Cursor, política de administrador ou configuração de provedor expuser um campo de URL de base OpenAI personalizado, use este guia para validar a configuração. Se a sua interface do Cursor suportar apenas chaves de API de propriedade do provedor, use as mesmas verificações para decidir quando manter o Cursor em seu fluxo de provedor documentado e usar o Flatkey em ferramentas que expõem explicitamente uma URL de base personalizada, como os fluxos de trabalho do roteador Cline ou Claude Code.
O objetivo não é forçar todas as solicitações do Cursor a passarem por um gateway. O objetivo é tornar cada decisão da API compatível com OpenAI do Cursor inspecionável: quem é o proprietário da chave, qual URL de base é realmente usada, qual nome de modelo é selecionado, onde o uso aparece e como reverter.
Configuração da API compatível com OpenAI do Cursor: o que verificar primeiro
Comece com uma tabela de decisão curta antes de alterar qualquer configuração.
| Superfície de configuração | O que o Cursor documenta publicamente | O que você deve verificar em seu espaço de trabalho |
|---|---|---|
| Chave de API do provedor | Adicione uma chave em Configurações do Cursor > Modelos para provedores suportados. | Qual linha de provedor você está editando, quem é o proprietário da chave e se a política da equipe permite BYOK. |
| URL de base personalizada | A documentação pública do Cursor verificada em 8 de julho de 2026 não documenta um caminho geral arbitrário para URL de base compatível com OpenAI. | Se a sua versão instalada do Cursor ou configuração empresarial expõe uma substituição de URL de base. |
| Nomes de modelos | Os modelos do Cursor aparecem no seletor de modelos; a disponibilidade depende do plano, provedor e região. | Se o nome do modelo selecionado é um modelo do Cursor, um modelo de provedor ou um alias de modelo do gateway. |
| Logs de uso | O painel de uso do Cursor mostra o uso, a cota, as cobranças sob demanda, o custo e a seleção de modelos para o uso do Cursor. | Se uma solicitação também aparece nos logs do Flatkey, nos logs do provedor ou apenas no uso do Cursor. |
| Modo de privacidade | O Cursor afirma que a Retenção Zero de Dados não se aplica quando você usa suas próprias chaves de API. | Se a sua revisão de segurança aceita a construção de prompts do Cursor mais o caminho do provedor ou gateway escolhido. |
Esta é a primeira regra da configuração da API compatível com OpenAI do Cursor: não trate um campo de chave de API como prova de uma rota de gateway. Um campo de chave prova a entrada de credenciais. Um campo de URL de base, um log de solicitações e um registro de uso provam o roteamento.
Os valores a coletar antes de mexer no Cursor
Coloque os valores de configuração em uma pequena planilha. Compartilhe isso com a pessoa responsável pela faturação ou segurança, não apenas com o desenvolvedor que está fazendo a alteração na interface.
| Campo | Exemplo do Flatkey | Por que é importante |
|---|---|---|
| Proprietário da chave de API | Uma chave Flatkey dedicada para avaliação do Cursor | Separa o tráfego do IDE do tráfego do aplicativo e torna a reversão limpa. |
| URL de base | https://router.flatkey.ai/v1 | Evita caminhos duplicados /v1/v1 e mantém a rota compatível com OpenAI. |
| Família de endpoints | Chat Completions primeiro | A documentação BYOK do Cursor diz que chaves de API personalizadas funcionam apenas com modelos de chat. |
| Nome do modelo | Alias atual do catálogo Flatkey selecionado pela equipe | Os aliases do gateway podem ser diferentes dos nomes do seletor de modelos do Cursor. |
| Prompt de teste | Um prompt de Agente ou chat de baixo risco | Mantém a primeira solicitação fácil de encontrar nos logs. |
| Responsável pelo uso | Página de uso do Cursor, uso/logs do Flatkey, responsável financeiro | Evita disputas de faturamento surpresa após o teste. |
| Valor de reversão | Configuração anterior de modelo/chave do Cursor | Permite que a equipe reverta sem apagar evidências. |
Para um teste de API compatível com OpenAI do Cursor, o erro mais comum é usar um nome de exibição de modelo de um sistema em outro. Os nomes de modelo do Cursor, os IDs de modelo do provedor e os aliases de rota do Flatkey não são automaticamente intercambiáveis. Escolha o nome do modelo do local que receberá a solicitação.
Execute um teste de fumaça externo primeiro
Antes de testar dentro do Cursor, valide os valores do gateway fora do Cursor. Estes trechos de código são apenas modelos; substitua a chave e o modelo pelos valores da sua conta e catálogo Flatkey atuais.
export FLATKEY_API_KEY="sk-fk-..."
export FLATKEY_MODEL="your-current-model-alias"
curl -sS https://router.flatkey.ai/v1/models \
-H "Authorization: Bearer $FLATKEY_API_KEY"
Use a resposta dos modelos para confirmar o ID ou alias exato do modelo. Em seguida, teste o caminho do chat:
curl -sS https://router.flatkey.ai/v1/chat/completions \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"messages": [
{
"role": "user",
"content": "Reply with exactly: cursor route probe ok"
}
]
}'
Salve o carimbo de data/hora da solicitação, o nome do modelo, o status HTTP, o corpo da resposta e o objeto usage se a resposta incluir um. O formato da API de Chat Completions da OpenAI é construído em torno de model e messages, e respostas bem-sucedidas podem incluir o uso de tokens. O endpoint de modelos da OpenAI lista os modelos atualmente disponíveis para uma conta. Esses dois fatos tornam este teste de fumaça (smoke test) útil antes de você envolver o Cursor.
Se este teste externo falhar, não continue para o Cursor. Corrija primeiro a chave, o alias do modelo, a cota ou a família de endpoints. Um teste externo que falhou não se tornará mais fácil de depurar depois que o Cursor adicionar seu próprio seletor de modelos, construção de prompts e caminho de solicitação.
Configure o Cursor somente depois que a rota for comprovada
Agora abra o Cursor e inspecione as configurações reais disponíveis para sua conta.
- Abra as Configurações do Cursor > Modelos.
- Verifique se sua organização permite chaves de API pessoais. Administradores corporativos podem restringir o uso de BYOK.
- Se você estiver usando o caminho BYOK documentado do Cursor, escolha a linha do provedor que o Cursor suporta e insira a chave desse provedor.
- Se o seu ambiente Cursor expuser um campo de URL de base personalizado compatível com OpenAI, insira apenas a raiz da URL de base, por exemplo,
https://router.flatkey.ai/v1, e não o caminho completo/chat/completions. - Insira ou selecione o nome do modelo do sistema receptor. Para o Flatkey, use o alias do modelo confirmado no catálogo do Flatkey ou no teste de fumaça (smoke test)
/v1/models. - Salve a configuração e, em seguida, selecione o modelo de destino no seletor de modelos do Cursor, se o Cursor o expuser lá.
É aqui que o título do artigo pode enganar as equipes: a configuração da API compatível com OpenAI do Cursor não está completa quando a página de configurações é salva. Ela só está completa quando a solicitação que você envia do Cursor aparece no rastro de uso esperado.
Uma lista de verificação de nomes de modelos para o roteamento de modelos do Cursor
Use esta tabela quando alguém perguntar: "Qual nome de modelo devo digitar?"
| Pergunta | Boa evidência | Atalho ruim |
|---|---|---|
| O Cursor expõe o modelo em seu seletor? | O modelo ativo está visível no painel de chat ou do Agente. | Assumir que um ID de provedor aparece porque a chave foi salva. |
| O gateway conhece o alias do modelo? | /v1/models ou o catálogo do Flatkey mostra o alias para sua conta. | Copiar um nome de modelo de marketing de uma postagem de blog. |
| A família de endpoints corresponde? | A rota de Chat Completions está selecionada para o tráfego do modelo de chat. | Enviar um modelo apenas nativo pelo caminho errado compatível com OpenAI. |
| O modelo suporta seu recurso? | Um teste salvo para chat simples, streaming e chamadas de ferramentas, se necessário. | Tratar a conclusão de texto simples como prova de todos os recursos. |
| O financeiro consegue encontrá-lo mais tarde? | A entrada de uso inclui contexto de rota/modelo suficiente para revisão. | Confiar apenas em uma resposta bem-sucedida no editor. |
Para uma implementação da API compatível com OpenAI do Cursor, comece com um chat simples. Não use uma grande refatoração de código, uma execução do Agente com muitas ferramentas ou uma longa sessão no Modo Max como primeiro teste. Faça o primeiro prompt ser suficientemente simples para que o registro de uso seja o resultado principal.
Verifique os logs de uso em três lugares
Uma configuração de gateway que retorna texto, mas não deixa rastro de uso, não está pronta para produção. Verifique três camadas após a primeira solicitação.
| Camada | O que verificar | Proprietário |
|---|---|---|
| Uso do Cursor | Uso do painel do Cursor, seleção de modelo, cota e cobranças sob demanda. | Proprietário da licença (seat) do Cursor ou administrador da equipe. |
| Uso/logs do Flatkey | Carimbo de data/hora da solicitação, chave, alias do modelo, família de endpoints, uso de tokens, contexto de custo e erros, quando disponíveis. | Proprietário da plataforma ou de operações. |
| Resposta do provedor ou gateway | Status HTTP, usage da resposta, campo do modelo e qualquer ID de solicitação ou código de erro. | Desenvolvedor fazendo o teste de fumaça (smoke test). |
O detalhe importante sobre a propriedade é que a própria documentação do Cursor diz que sua chave de API é enviada para o backend do Cursor a cada solicitação com chave própria para a construção final do prompt. Isso significa que um teste da API compatível com OpenAI do Cursor deve ser revisado como um caminho de ferramenta mais gateway, e não como uma chamada local direta do seu laptop para o provedor.
Se sua equipe depende da Retenção Zero de Dados (Zero Data Retention) do Cursor, leia a nota de privacidade do BYOK do Cursor antes de usar sua própria chave. O Cursor afirma que sua política de Retenção Zero de Dados não se aplica ao usar suas próprias chaves de API; o tratamento de dados segue a política do provedor escolhido. Se você rotear através do Flatkey, adicione a política atual, o painel e as evidências de retenção do Flatkey ao mesmo pacote de revisão.
Solução de problemas de falhas de URL de base, chave e modelo
A maioria das falhas se enquadra em um pequeno conjunto de causas.
| Sintoma | Causa provável | Correção |
|---|---|---|
401 ou erro de autenticação | Chave incorreta, espaço em branco copiado, chave revogada ou chave não permitida para a rota. | Copie novamente a chave, use uma chave de teste dedicada e tente novamente o curl externo primeiro. |
403 ou erro de permissão | A política da equipe, o direito do provedor, a região ou a permissão do gateway bloqueiam a solicitação. | Verifique a política BYOK do Cursor, o acesso à conta Flatkey e a disponibilidade do provedor. |
404 ou modelo não encontrado | O nome do modelo não é válido para o sistema receptor. | Use o seletor de modelos, /v1/models ou o catálogo atual do Flatkey como fonte da verdade. |
429 ou erro de cota | A permissão do plano Cursor, a cota do provedor, a cota do Flatkey ou a taxa de solicitação foi excedida. | Diminua o volume de teste, verifique os limites e atribua um proprietário para aumentos de cota. |
| O texto retorna, mas nenhum log do Flatkey aparece | A solicitação não foi roteada através do Flatkey. | Verifique novamente se o Cursor aceitou uma URL de base personalizada ou apenas uma chave de provedor. |
| Comportamento da guia do Cursor inalterado | O Cursor documenta que chaves de API personalizadas funcionam apenas com modelos de chat. | Não use o preenchimento com Tab como sinal de verificação. |
O próprio guia de erros da OpenAI trata os erros de autenticação, limite de taxa, cota e serviço sobrecarregado como ações de proprietário diferentes. Mantenha essa separação em seu runbook do Cursor. Uma política de nova tentativa não corrigirá um nome de modelo incorreto, e um novo nome de modelo não corrigirá um bloqueio de política BYOK.
Quando não usar o Flatkey para o Cursor
Há momentos em que a melhor decisão sobre a API compatível com OpenAI do Cursor é parar.
Não roteie o Cursor através do Flatkey se sua compilação atual do Cursor não expuser uma substituição de URL de base e seu fluxo de trabalho exigir um endpoint personalizado verdadeiro. Não roteie o Cursor através do Flatkey se o administrador da sua empresa tiver desativado as chaves de API pessoais. Não roteie o Cursor através do Flatkey se sua revisão de segurança depender dos controles de privacidade de modelos integrados do Cursor que não se aplicam ao tráfego de chave própria.
Nesses casos, mantenha o Cursor no caminho do provedor documentado e use o Flatkey onde o cliente suporta explicitamente URLs de base compatíveis com OpenAI: SDKs de aplicativos, ferramentas internas, scripts de avaliação, Cline, Open WebUI, LangChain, LlamaIndex ou outras superfícies de integração. Se você precisar do padrão geral de migração, comece com o guia de migração de API compatível com OpenAI. Para padrões de roteador de agente de codificação, compare a configuração do roteador da API Claude Code e a configuração da API compatível com OpenAI do Cline.
Lista de verificação de produção
Antes de considerar a configuração da API compatível com OpenAI do Cursor concluída, salve estas evidências:
| Evidência | Concluído quando |
|---|---|
| Configuração do Cursor | A captura de tela ou nota do administrador mostra o caminho do provedor/chave/URL de base usado, com os segredos ocultos. |
| Prova do modelo | O nome do modelo é obtido do seletor de modelos do Cursor, do catálogo do Flatkey ou de /v1/models, não de uma suposição. |
| Teste de fumaça externo | https://router.flatkey.ai/v1/chat/completions retorna uma resposta simples com o modelo escolhido. |
| Prova da solicitação do Cursor | Um pequeno prompt do Cursor usou o modelo pretendido e não dependeu do preenchimento com Tab. |
| Prova de uso | As evidências de uso/log do Cursor e do Flatkey são salvas com carimbos de data/hora. |
| Mapa de erros | As ações do proprietário para 401, 403, 404, 429 e 5xx estão documentadas. |
| Reversão | O caminho anterior do modelo/chave do Cursor é registrado e pode ser restaurado sem excluir os logs. |
A configuração da API compatível com OpenAI do Cursor é valiosa quando transforma o tráfego da ferramenta de codificação em uso de modelo governado e revisável. Mantenha a URL de base, o nome do modelo e a prova do log de uso juntos. Quando você precisar de uma chave de gateway e um lugar para revisar o tráfego do modelo, obtenha uma chave Flatkey, teste primeiro uma solicitação de chat de baixo risco e prossiga somente depois que os logs comprovarem a rota.
