API Hop

Documentazione

Documentazione API Hop

Integrazione Codex

Usa l’endpoint compatibile con OpenAI Responses di RequestBeam in Codex CLI, nell’estensione VS Code o nell’app desktop.

Codex chiama i modelli tramite il protocollo OpenAI Responses. Configura il fornitore del modello con l’URL di base compatibile con OpenAI mostrato in questa pagina.

text
Codex base_url: https://api.apihop.ai/openai

Prerequisiti

Prepara prima una chiave API RequestBeam valida. Verrà scritta nella directory di configurazione locale di Codex. Non inserirla in repository, registri o schermate.

Codex normalmente salva i file di configurazione in:

  • macOS / Linux: ~/.codex/
  • Windows: %userprofile%\.codex\

Se la directory o il file di configurazione non esistono, creali prima:

bash
mkdir -p ~/.codex
touch ~/.codex/config.toml

Per Windows CMD:

bat
mkdir %userprofile%\.codex
type nul > %userprofile%\.codex\config.toml

Backup della configurazione

Se hai già usato Codex, esegui prima il backup della configurazione corrente:

bash
cp ~/.codex/config.toml ~/.codex/config.toml.bak
cp ~/.codex/auth.json ~/.codex/auth.json.bak

Aggiornare config.toml

Apri ~/.codex/config.toml, quindi aggiungi o aggiorna questa configurazione:

toml
model_provider = "requestbeam"
model = "gpt-5.4"
review_model = "gpt-5.4"
model_reasoning_effort = "high"
disable_response_storage = true
network_access = "enabled"

[model_providers.requestbeam]
name = "RequestBeam"
base_url = "https://api.apihop.ai/openai"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = true
websocket_connect_timeout_ms = 15000

[features]
responses_websockets = true

La regola di base_url è: l’URL di base dell’API pubblica mostrato in questa pagina + /openai.

Se config.toml contiene già [marketplaces.*], [plugins.*] o altre impostazioni degli strumenti, mantienile e aggiungi o aggiorna solo le impostazioni del fornitore del modello Codex indicate sopra.

Modalità WebSocket

Quando supports_websockets = true e responses_websockets = true sono attivati, Codex usa l’endpoint Responses WebSocket seguente:

text
https://api.apihop.ai/openai/responses

Se l’URL di base dell’API usa https://, Codex usa la corrispondente connessione wss://.

Questa modalità WebSocket è un ponte Responses-over-WebSocket specifico di Codex:

  • Supporta response.create
  • Supporta response.cancel
  • Restituisce response.completed
  • Mantiene anche l’evento di compatibilità response.processed

response.cancelled conferma la richiesta di annullamento locale. Non conferma un rimborso da parte del fornitore a monte. Una richiesta il cui risultato a monte è sconosciuto mantiene la prenotazione finché utilizzo o errore non vengono verificati.

Non è l’API OpenAI Realtime. Non supporta session.update, conversation.item.*, input_audio_buffer.*, streaming audio, messaggi binari o involucri Realtime.

Se un proxy di rete, un gateway aziendale o una versione precedente di Codex non riesce a stabilire connessioni WebSocket, passa temporaneamente a:

toml
[model_providers.requestbeam]
supports_websockets = false

[features]
responses_websockets = false

Codex ripiegherà su HTTP POST https://api.apihop.ai/openai/responses. Compact è una capacità distinta: i cinque modelli GPT attualmente elencati non dispongono di un canale Compact verificato. Passare tra HTTP e WebSocket non abilita la compattazione. Avvia una nuova conversazione prima di superare il limite di contesto del modello; non affidarti alla compattazione automatica dei contesti lunghi con queste route.

Scrivere la chiave API

Sostituisci YOUR_REQUESTBEAM_API_KEY con la tua chiave API RequestBeam:

bash
echo '{"OPENAI_API_KEY":"YOUR_REQUESTBEAM_API_KEY"}' > ~/.codex/auth.json

Per Windows CMD:

bat
echo {"OPENAI_API_KEY":"YOUR_REQUESTBEAM_API_KEY"} > %userprofile%\.codex\auth.json

Riavvio e test

Salva la configurazione, chiudi completamente Codex e riaprilo.

Puoi testare la CLI con:

bash
codex "Reply in one sentence whether the current model is available."

Per l’estensione VS Code o l’app desktop, chiudi completamente l’applicazione, riaprila e avvia una normale chat.

Risoluzione dei problemi

  • base_url deve essere l’URL di base dell’API pubblica mostrato in questa pagina più /openai.
  • wire_api deve essere responses; non cambiarlo in chat.
  • Un errore di indisponibilità di Compact indica che non esiste un canale Compact verificato; modificare una soglia locale di token non può abilitarlo.
  • RequestBeam supporta sia HTTP Responses sia Codex Responses WebSocket. Mantieni per impostazione predefinita supports_websockets = true e responses_websockets = true. Se la versione di Codex o il proxy di rete non supporta WebSocket, imposta temporaneamente supports_websockets = false per ripiegare su HTTP.
  • auth.json deve essere JSON valido e il nome della chiave deve essere OPENAI_API_KEY.
  • Se ricevi 401 o invalid key, verifica che la chiave API sia valida e non sia stata sovrascritta da una chiave locale precedente.
  • Se il modello non è disponibile, controlla GET https://api.apihop.ai/v1/models e imposta model e review_model su un modello GPT visibile. L’esempio predefinito usa gpt-5.4; gpt-5.3-codex e gpt-5.6-luna non sono attualmente abilitati.
  • Chiudi completamente e riapri Codex dopo aver modificato la configurazione. Chiudere solo la finestra potrebbe non ricaricare auth.json.
  • POST https://api.apihop.ai/openai/responses: endpoint RequestBeam compatibile con Responses consigliato.
  • POST https://api.apihop.ai/openai/responses/compact: richiede un canale Compact esplicitamente abilitato; altrimenti restituisce 503 prima della prenotazione. Un canale supportato restituisce response.compaction.
  • WS /openai/responses: endpoint compatibile con Responses WebSocket. Supporta response.create e response.cancel, restituisce response.completed e mantiene l’evento di compatibilità response.processed.
  • WS /openai/responses/compact: usa lo stesso controllo della capacità Compact e lo stesso endpoint. Il solo handshake WebSocket non prova il supporto del modello.