Configuração da API do Astra com autenticação oficial da OpenAI

Comece pelo provedor e pela conta de faturamento

Use gpt-6-astra pela API da OpenAI com sua própria chave da OpenAI Platform. Em uma aplicação, comece pelo exemplo de Responses abaixo. Para trabalho de programação local, use os comandos de login e seleção de modelo do Codex CLI. Ambos os caminhos usam sua conta da Platform e geram cobranças de API segundo as tarifas aplicáveis da OpenAI.

Antes de executar uma solicitação, confirme quem é o proprietário do projeto da Platform, se a chave pode acessar o modelo e quais controles de faturamento se aplicam. Um modelo aparecer no ChatGPT ou no Codex não concede acesso a todos os projetos de API. Mantenha o login por assinatura e o login por chave de API separados nas anotações da tarefa. Essa distinção é essencial ao diagnosticar um limite ou reconciliar cobranças mais tarde.

Prepare a chave e o cliente em um ambiente confiável

Crie uma chave de API no painel da OpenAI e forneça-a como OPENAI_API_KEY por meio do seu ambiente privado ou de um gerenciador de segredos. O SDK oficial lê essa variável. Nunca incorpore a chave em JavaScript de navegador, repositório público, captura de tela ou transcrição de terminal compartilhada. Evite rastreamento do shell ao lidar com credenciais.

Para o exemplo JavaScript abaixo, instale o pacote oficial openai no projeto com npm install openai. Registre a versão instalada no lockfile. O baseURL explícito seleciona a OpenAI, em vez de um endpoint personalizado herdado. Revise também a configuração existente do agente: uma substituição de provedor e uma credencial de outro serviço não se tornam compatíveis apenas porque ambos aceitam um cabeçalho Authorization.

Envie uma solicitação de Responses e leia a resposta

Crie astra-example.mjs com o código a seguir e execute node astra-example.mjs. O prompt pede uma checklist curta para que você possa inspecionar a resposta retornada antes de conectar um fluxo maior. As tentativas automáticas do SDK ficam desativadas nesta primeira solicitação, o que facilita diagnosticar erros de conexão ou de conta.

Quando o status for completed, response.output_text conterá a saída de texto combinada do SDK. Imprima-a na saída padrão para que outro programa possa consumi-la ou redirecione-a para um arquivo. Envie os metadados da resposta para o erro padrão, mantendo-os separados da resposta. Para respostas incompletas, preserve incomplete_details e usage e retorne um código de saída diferente de zero.

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: 'https://api.openai.com/v1',
  maxRetries: 0,
})
const response = await client.responses.create({
  model: 'gpt-6-astra',
  input: 'List three checks for a small code change.',
})
console.error(JSON.stringify({
  id: response.id,
  model: response.model,
  status: response.status,
  usage: response.usage,
  incomplete_details: response.incomplete_details,
}))
if (response.status === 'completed') {
  console.log(response.output_text)
} else {
  process.exitCode = 1
}

Selecione autenticação por chave de API para o Codex local

A OpenAI documenta o login por chave de API para trabalho local no Codex. Na CLI, verifique codex login status antes de alterar as credenciais. O comando documentado por stdin abaixo evita colar um segredo em um argumento de comando. Depois do login, verifique novamente o método de autenticação ativo e selecione o modelo exato com a opção de modelo da CLI.

O comando final abre uma sessão interativa com o Astra selecionado. Comece no diretório do seu projeto para que o agente possa ler os arquivos corretos e as instruções do repositório. Revise substituições de provedor existentes e confirme a conta ativa. O modo por chave de API permite trabalho local; o Codex cloud exige autenticação do ChatGPT. Para uma tarefa cloud que você queira continuar localmente, leve primeiro os arquivos de trabalho e um resumo curto do trabalho restante para o projeto local.

codex login status
printenv OPENAI_API_KEY | codex login --with-api-key
codex login status
codex --model gpt-6-astra

Associe os recursos ao caminho do cliente

O Astra é compatível com Responses e Chat Completions, mas a chamada de ferramentas exige Responses. Use Responses para um agente que executa funções ou ferramentas personalizadas. Um cliente escrito para ler chat choices não consegue analisar a saída de Responses apenas trocando a URL, e um smoke test somente de texto não exercita um loop de ferramentas.

Adicione um recurso por vez usando um exemplo pequeno da sua aplicação. Para ferramentas, valide os argumentos, execute a função na aplicação e retorne o resultado por Responses com o call_id correspondente. Para saída estruturada, valide o esquema e trate respostas incompletas. Para streaming, processe eventos de conclusão e cancelamento, além do texto. Mantenha a solicitação simples de texto disponível como caminho de diagnóstico enquanto adiciona esses recursos.

Diagnostique separadamente falhas de acesso, taxa e conclusão

Use o status HTTP e os campos de erro estruturados antes de tentar novamente. O guia de erros da OpenAI distingue autenticação inválida, créditos esgotados, limites de gasto aplicados e pressão sobre a taxa de solicitações. Em particular, uma resposta 429 não basta para escolher uma solução: inspecione error.code e as configurações relevantes da conta.

Para pressão temporária sobre a taxa, respeite Retry-After quando presente e use tentativas limitadas. Falhas de faturamento ou de limite de gasto exigem uma decisão sobre a conta, não solicitações repetidas. Um resultado de Responses marcado como incomplete é outra condição e pode já ter consumido tokens. Retenha informações de erro redigidas e o uso; não transforme um timeout ou um recibo ausente em uma tentativa bem-sucedida ou gratuita.

Disponibilidade do provedor e evidências: 5 de setembro de 2026

A OpenAI anunciou o GPT-6 Astra com uma distribuição gradual, e sua referência do modelo documenta a API oficial. Os exemplos aqui seguem essas fontes; nenhum pedido pago ou troca de autenticação do Codex foi executado para este guia. A verificação do catálogo público da APIsRouter em 5 de setembro de 2026 retornou HTTP 200, success: true e 34 modelos, sem entrada para Astra ou GPT-6.

Use credenciais da OpenAI somente com o endpoint oficial mostrado acima. Consulte o catálogo ao vivo da APIsRouter para suas próprias ofertas. Uma listagem futura do Astra ainda exigiria verificar o ID exato do modelo, o preço e os recursos necessários do cliente antes de usá-lo na aplicação.

Conecte a resposta a um fluxo local útil

Escolha uma tarefa local com um resultado concreto, como explicar uma função e propor um teste. Dê ao agente o caminho do arquivo relevante, o comportamento esperado e o comando de teste. Depois de uma alteração de código, inspecione o diff e execute os testes focados. Mantenha a entrada original e a resposta retornada juntas para facilitar a comparação das revisões.

Em uma aplicação, passe o texto concluído para sua tela de revisão ou pipeline de documentos. Se o próximo passo esperar dados legíveis por máquina, use saída estruturada e valide os campos obrigatórios antes de armazená-los. Mantenha a identidade da solicitação e o uso junto da tarefa e defina uma política de tentativas limitada. Amplie o fluxo depois que sua entrada básica, o tratamento da resposta e as verificações de conclusão funcionarem em conjunto.

Perguntas frequentes