Usare GPT-6 Astra con OmniaKey

Questo tutorial ti porta da un nuovo account OmniaKey alla prima richiesta GPT-6 Astra completata con successo. Copre le chiamate API lato server e la CLI di Codex. Una chiave API OmniaKey non è un abbonamento ChatGPT e non può essere inserita nel sito di ChatGPT.

La guida Astra attuale di OpenAI parte dalla Responses API. Chat Completions rimane disponibile per il testo semplice, ma le chiamate agli strumenti di Astra richiedono Responses. Gli esempi seguenti rispettano questo limite e leggono la chiave da una variabile d'ambiente invece di inserirla nel codice sorgente.

Prima di iniziare

Crea una chiave API con ambito limitato

Accedi a OmniaKey e apri la pagina delle chiavi API. Crea una chiave separata per questa integrazione, quindi imposta quota e scadenza adatte al test. Copia la chiave quando compare.

L'account deve avere anche un saldo utilizzabile. La creazione della chiave dimostra che la credenziale esiste, non che l'account possa pagare una richiesta.

Tratta la chiave come una password. Non commetterla in Git, non inserirla in un'applicazione eseguita nel browser e non includerla in screenshot o chat.

Inserisci la chiave in una variabile d'ambiente

Su macOS o Linux:

export OMNIAKEY_API_KEY="your-omniakey-api-key"

In PowerShell:

$env:OMNIAKEY_API_KEY="your-omniakey-api-key"

Gli esempi SDK e Codex seguenti leggono la stessa variabile.

Invia la prima richiesta alla Responses API

Esegui questa richiesta in un terminale:

curl https://api.omniakey.com/v1/responses \
  -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "reasoning": {"effort": "medium"},
    "input": "Esamina questo piano di migrazione. Restituisci i due rischi principali e un test di accettazione per ciascuno."
  }'

Una risposta riuscita contiene un array output, il testo generato e l'utilizzo dei token. Questa prima chiamata verifica insieme Base URL, chiave, saldo, autorizzazione del modello, ID del modello e rotta Responses.

Dopo il successo, apri la dashboard di utilizzo e conferma che il modello registrato sia gpt-6-astra. Esamina l'utilizzo reale di input, cache, ragionamento e output invece di stimare il costo dal solo testo visibile.

Chiama Astra da Python

Installa o aggiorna l'SDK Python ufficiale di OpenAI:

python -m pip install --upgrade openai

Crea astra_example.py:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OMNIAKEY_API_KEY"],
    base_url="https://api.omniakey.com/v1",
)

response = client.responses.create(
    model="gpt-6-astra",
    reasoning={"effort": "medium"},
    input="Spiega questo rapporto sull'incidente, poi elenca i tre controlli successivi più utili.",
)

print(response.output_text)

Eseguilo:

python astra_example.py

response.output_text è il campo di comodo dell'SDK per il testo generato. Conserva la risposta completa se ti servono anche utilizzo, stato o elementi di chiamata agli strumenti.

Chiama Astra da Node.js

Installa l'SDK:

npm install openai

Crea un file lato server come astra-example.mjs:

import OpenAI from "openai";

const apiKey = process.env.OMNIAKEY_API_KEY;
if (!apiKey) throw new Error("OMNIAKEY_API_KEY is required");

const client = new OpenAI({
  apiKey,
  baseURL: "https://api.omniakey.com/v1",
});

const response = await client.responses.create({
  model: "gpt-6-astra",
  reasoning: { effort: "medium" },
  input: "Esamina questo design API. Trova due modalità di guasto e un test per ciascuna.",
});

console.log(response.output_text);

Eseguilo dalla shell in cui è impostata la variabile d'ambiente:

node astra-example.mjs

Esegui questo codice su un server, una macchina locale o un worker affidabile. Una chiave inserita in un bundle frontend diventa accessibile ai visitatori.

Usa GPT-6 Astra nella CLI di Codex

Un provider Codex personalizzato usa il Responses wire format. Aggiungi questa configurazione al file utente ~/.codex/config.toml:

model = "gpt-6-astra"
model_provider = "omniakey"

[model_providers.omniakey]
name = "OmniaKey"
base_url = "https://api.omniakey.com/v1"
env_key = "OMNIAKEY_API_KEY"
wire_api = "responses"

Avvia Codex da una shell in cui sia impostata la chiave:

export OMNIAKEY_API_KEY="your-omniakey-api-key"
codex

Lascia requires_openai_auth non impostato. La documentazione ufficiale di configurazione di Codex lo definisce come flag per l'autenticazione OpenAI; questo provider personalizzato si autentica invece con env_key.

Controlla prima il modello mostrato da Codex, poi esegui una piccola attività di sola lettura prima di consentire modifiche. Se una richiesta cURL diretta funziona e Codex no, verifica per prima la configurazione del client.

Usa Chat Completions solo quando serve al client

GPT-6 Astra accetta testo semplice anche con Chat Completions. Usa questa rotta se il client non ha ancora adottato Responses:

curl https://api.omniakey.com/v1/chat/completions \
  -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "reasoning_effort": "medium",
    "messages": [
      {"role": "user", "content": "Riassumi i due rischi principali di questo piano di rilascio."}
    ]
  }'

Nota la differenza fra i parametri: Responses usa reasoning.effort, mentre Chat Completions usa reasoning_effort. Non aggiungere strumenti Astra a questo esempio Chat Completions. La guida OpenAI attuale richiede Responses per le chiamate agli strumenti di Astra.

Scegli il reasoning effort

Astra supporta low, medium, high, xhigh e max, ma non none. Un effort superiore può aumentare ragionamento, latenza e costi dei token di output senza garantire una risposta corretta. Usa l'impostazione più bassa che supera il test di accettazione.

Assegna ad Astra un'attività verificabile

Un buon primo prompt indica obiettivo, contesto pertinente, vincoli e controllo di completamento:

Obiettivo: esaminare il rischio di deployment di questa migrazione del database.
Contesto: PostgreSQL 15, un solo writer in produzione, rollback da completare entro cinque minuti.
Vincoli: non proporre comandi distruttivi; separare i fatti verificati dalle ipotesi.
Completato quando: vengono restituiti i tre rischi principali, una mitigazione e un test di accettazione per ciascuno.

Per il lavoro sul codice, indica anche le regole del repository e il comando esatto che dimostra il completamento. Astra segue con attenzione i file di istruzioni accessibili, quindi esamina AGENTS.md, skills e file simili prima di concedere l'accesso agli strumenti.

Risolvi gli errori comuni di configurazione

401, unauthorized o chiave API non valida

Verifica che OMNIAKEY_API_KEY sia impostata nella stessa shell che esegue il comando. La variabile d'ambiente contiene soltanto la chiave; Bearer appartiene solo all'header HTTP. Controlla inoltre che la chiave sia attiva e non scaduta.

Saldo o quota insufficienti

Controlla sia il saldo dell'account sia la quota della chiave. Un account finanziato può comunque fallire quando la chiave limitata ha raggiunto il suo tetto.

Modello non trovato o non disponibile

Usa l'ID esatto gpt-6-astra. Apri la pagina attuale del modello e conferma che la chiave abbia il permesso di usarlo. Nomi visualizzati come GPT 6 non sono ID API.

Parametro non supportato

Rimuovi temperature, top_p e top_logprobs. Per Chat Completions rimuovi anche logprobs; da include di Responses rimuovi message.output_text.logprobs. Astra non supporta questi parametri.

Risposta incomplete o senza testo visibile

Aumenta max_output_tokens e controlla output_tokens_details.reasoning_tokens. I token di ragionamento consumano il budget di output prima che la risposta visibile sia completa.

La chat funziona, gli strumenti no

Sposta il workflow su /v1/responses. Inizia con una chiamata Responses di solo testo, poi aggiungi uno strumento alla volta e verifica richiesta, risultato, timeout e percorso delle autorizzazioni. L'elenco ufficiale OpenAI descrive le capacità dirette del modello; un gateway o client può esporne meno.

Codex continua a usare un altro modello

Controlla model, model_provider, base_url, env_key e wire_api nella configurazione Codex attiva. Riavvia quindi Codex dalla shell in cui è impostata OMNIAKEY_API_KEY.

Verifica il costo prima della produzione

Esegui un'attività rappresentativa, conferma il record di utilizzo e includi i tentativi nel costo completo. La pagina del modello Astra mantiene il prezzo OmniaKey attuale. La recensione di Astra separa il prezzo del gateway dalle tariffe OpenAI dirette e spiega la soglia di 272K per queste ultime.

Se un limite ha interrotto il lavoro, la guida ai limiti di Codex spiega come controllare il reset e scegliere tra crediti extra, un altro piano e API locale fatturata separatamente.

Riferimenti

Tutte le fonti ufficiali OpenAI seguenti sono in inglese. Anche i link alla documentazione OmniaKey portano attualmente a pagine in inglese.

• OpenAI: modello GPT-6 Astra
• OpenAI: guida all'uso di GPT-6 Astra
• OpenAI: riferimento di configurazione di Codex
• Avvio rapido dell'API OmniaKey (in inglese)
• API OmniaKey compatibile con OpenAI (in inglese)
• Guida OmniaKey alla CLI Codex (in inglese)