Configurazione API Astra con autenticazione OpenAI ufficiale

Inizia dal provider e dall'account di fatturazione

Usa gpt-6-astra tramite l'API OpenAI con la tua chiave OpenAI Platform. Per un'applicazione, inizia dall'esempio Responses seguente. Per il coding locale, usa i comandi Codex CLI per login e selezione del modello. Entrambi i percorsi usano il tuo account Platform e comportano addebiti API alle tariffe OpenAI applicabili.

Prima di eseguire una richiesta, conferma chi possiede il progetto Platform, se la sua chiave può accedere al modello e quali controlli di fatturazione si applicano. La presenza di un modello in ChatGPT o Codex non concede accesso a ogni progetto API. Mantieni separati login con abbonamento e login con API key nelle note del run. Questa distinzione è essenziale per diagnosticare un limite o riconciliare gli addebiti in seguito.

Prepara chiave e client in un ambiente affidabile

Crea una chiave API nella dashboard OpenAI e fornisci OPENAI_API_KEY attraverso il tuo ambiente privato o un secret manager. L'SDK ufficiale legge quella variabile. Non incorporare mai la chiave in JavaScript del browser, repository pubblico, screenshot o transcript di terminale condiviso. Evita il tracing della shell quando gestisci credenziali.

Per l'esempio JavaScript seguente, installa nel progetto il pacchetto ufficiale openai con npm install openai. Registra la versione installata nel lockfile. Il baseURL esplicito seleziona OpenAI invece di un endpoint personalizzato ereditato. Rivedi anche la configurazione esistente dell'agente: un override del provider e una credenziale di un altro servizio non diventano compatibili solo perché entrambi accettano un Authorization header.

Invia una richiesta Responses e leggi la risposta

Crea astra-example.mjs con il codice seguente, poi esegui node astra-example.mjs. Il prompt chiede una checklist breve, così puoi ispezionare la risposta prima di collegare un workflow più grande. I retry automatici dell'SDK sono disabilitati per questa prima richiesta, rendendo più facili da diagnosticare errori di connessione o account.

Quando status è completed, response.output_text contiene l'output testuale combinato dell'SDK. Stampalo su standard output perché un altro programma possa consumarlo o reindirizzarlo a un file. Invia i metadati della risposta su standard error per tenerli separati dalla risposta. Per risposte incomplete, conserva incomplete_details e usage e restituisci un exit code diverso da 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
}

Seleziona l'autenticazione API-key per Codex locale

OpenAI documenta il login con API key per il lavoro Codex locale. Nella CLI, controlla codex login status prima di cambiare credenziali. Il comando stdin documentato sotto evita di incollare un segreto in un argomento del comando. Dopo il login, controlla di nuovo il metodo di autenticazione attivo, poi seleziona il modello esatto con il flag del modello CLI.

Il comando finale apre una sessione interattiva con Astra selezionato. Avvia dal directory del progetto perché l'agente possa leggere file e istruzioni del repository corretti. Rivedi gli override di provider esistenti e conferma l'account attivo. La modalità API-key supporta il lavoro locale; Codex cloud richiede autenticazione ChatGPT. Per continuare localmente un task cloud, porta prima nel progetto locale i file di lavoro e un breve riepilogo del lavoro restante.

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

Abbina le capacità al percorso del client

Astra supporta Responses e Chat Completions, ma il tool calling richiede Responses. Usa Responses per un agente che esegue funzioni o strumenti personalizzati. Un client scritto per leggere chat choices non può fare il parsing dell'output Responses cambiando solo l'URL, e uno smoke test solo testuale non esercita un tool loop.

Aggiungi una capacità alla volta con un esempio piccolo della tua applicazione. Per gli strumenti, valida gli argomenti, esegui la funzione nell'applicazione e restituisci il risultato tramite Responses con il call_id corrispondente. Per l'output strutturato, valida lo schema e gestisci le risposte incomplete. Per lo streaming, gestisci eventi di completamento e cancellazione oltre al testo. Mantieni disponibile la semplice richiesta testuale come percorso diagnostico mentre aggiungi queste funzioni.

Diagnostica separatamente accesso, rate e completamento

Usa status HTTP e campi di errore strutturati prima di riprovare. La guida agli errori OpenAI distingue autenticazione non valida, crediti esauriti, limiti di spesa imposti e pressione sul rate delle richieste. In particolare, una risposta 429 non basta per scegliere il rimedio: controlla error.code e le impostazioni dell'account pertinenti.

Per pressione temporanea sul rate, rispetta Retry-After quando presente e usa retry limitati. Gli errori di fatturazione o limite di spesa richiedono una decisione sull'account, non richieste ripetute. Un risultato Responses marcato incomplete è ancora una condizione diversa e potrebbe aver già consumato token. Conserva informazioni di errore redatte e utilizzo; non trasformare timeout o ricevuta mancante in un tentativo riuscito o gratuito.

Disponibilità del provider e prove: 5 settembre 2026

OpenAI ha annunciato GPT-6 Astra con un rollout graduale e il riferimento del modello documenta l'API ufficiale. Gli esempi seguono quelle fonti; per questa guida non è stata eseguita alcuna richiesta a pagamento né un cambio di autenticazione Codex. Il controllo del catalogo pubblico APIsRouter del 5 settembre 2026 ha restituito HTTP 200, success: true e 34 modelli, senza voce Astra o GPT-6.

Usa credenziali OpenAI solo con l'endpoint ufficiale mostrato sopra. Controlla il catalogo live APIsRouter per le sue offerte. Un'eventuale voce Astra successiva richiederebbe comunque la verifica di model ID esatto, prezzo e funzioni client necessarie prima dell'uso nell'applicazione.

Collega la risposta a un workflow locale utile

Scegli un task locale con un risultato concreto, come spiegare una funzione e proporre un test. Fornisci all'agente percorso del file, comportamento atteso e comando di test pertinenti. Dopo una modifica di codice, ispeziona il diff ed esegui i test mirati. Conserva insieme input originale e risposta restituita per confrontare facilmente le revisioni.

In un'applicazione, passa il testo completato alla schermata di revisione o alla pipeline documentale. Se il passaggio successivo si aspetta dati leggibili dalla macchina, usa output strutturato e valida i campi richiesti prima di salvarli. Conserva identità della richiesta e utilizzo accanto all'attività e imposta una policy di retry limitata. Espandi il workflow dopo che input di base, gestione delle risposte e controlli di completamento funzionano insieme.

Domande frequenti