APIMaster.ai
Documentazione APIMaster.ai
Quick startAPIMaster.aiMarketplace

Configurazione chiave API OpenCode AI — Compatibile con OpenAI

Come configurare OpenCode AI con una chiave API personalizzata da APIMaster.ai. Aggiungi APIMaster come provider compatibile con OpenAI in opencode.jsonc e accedi a Claude, GPT-5.5 e DeepSeek con input immagine (Vision) e livelli Reasoning opzionali.

OpenCode Desktop è il client grafico per OpenCode (attualmente in beta): sessioni agente locali, modifiche ai file ed esecuzione di comandi shell. APIMaster.ai è compatibile con OpenAI — aggiungilo in Impostazioni → Providers → Provider personalizzato.

Ottieni la tua chiave API. Usa il segnaposto your_apimaster_key di seguito; gli screenshot nascondono le chiavi reali.

Prerequisiti

  1. OpenCode Desktop installato da opencode.ai/download.
    • Windows: opencode-desktop-win-x64.exe
    • macOS: brew install --cask opencode-desktop o .dmg
    • Linux: .deb / .rpm / AppImage
  2. Chiave API APIMaster dalla console.

Passo 1 — Apri Provider

  1. Avvia OpenCode Desktop e apri un workspace.
  2. Clicca sull'icona a forma di ingranaggio (in basso a sinistra).
  3. Seleziona Providers nella barra laterale.
  4. Scorri fino a Provider personalizzato (Aggiungi un provider compatibile con OpenAI tramite URL base).
  5. Clicca su + Connetti.

Impostazioni → Providers → Provider personalizzato

Passo 2 — Modulo provider personalizzato

Campo Valore
ID provider apimaster
Nome visualizzato APIMaster.ai
URL base https://apimaster.ai/v1
Chiave API La tua chiave APIMaster

Modulo provider personalizzato

Lascia vuoto Headers a meno che non autentichi solo tramite header.

Passo 3 — Aggiungi modelli e Invia

Nella schermata successiva, mappa i modelli (sinistra = etichetta in OpenCode, destra = id modello inviato ad APIMaster — di solito uguali):

Sinistra Destra
gpt-5.4 gpt-5.4
claude-sonnet-4-6 claude-sonnet-4-6
  1. Clicca su + Aggiungi modello per più righe.
  2. Clicca su Invia.

Aggiungi modelli e Invia

Scegli gli id dal marketplace. Evita modelli solo generazione di immagini (es. gpt-image-2) per la chat agente.

Ti serve il riconoscimento di immagini (Vision)? gpt-5.5, claude-sonnet-4-6, claude-opus-4-7, claude-opus-4-8 e claude-haiku-4-5 supportano l'input immagine, ma OpenCode necessita di una dichiarazione aggiuntiva della capacità — vedi Abilitare l'input immagine per GPT e Claude.

Passo 4 — Scegli un modello

  1. Avvia o apri una sessione.
  2. Apri il menu a discesa dei modelli sotto l'input.
  3. Sotto APIMaster.ai, seleziona un modello (es. claude-sonnet-4-6).

Selettore modello

Passo 5 — Test

Invia hello o un piccolo compito di coding. Una normale risposta dell'Assistente (modifiche file / shell) significa che APIMaster è connesso.

Test chat

Avanzato: opencode.jsonc e Reasoning

Il flusso dell'interfaccia sopra è sufficiente per un avvio rapido. Per configurare i livelli di Reasoning / thinking effort (low, high, max, …) per lo stesso id modello, modifica opencode.jsonc.

Posizione del file di configurazione

SO Percorso
macOS / Linux ~/.config/opencode/opencode.jsonc
Windows C:\Users\<nomeutente>\.config\opencode\opencode.jsonc

Crea il file se mancante. Riavvia OpenCode Desktop o avvia una nuova sessione dopo aver salvato.

Chiave API (non inserirla in jsonc)

Non memorizzare la tua chiave API in opencode.jsonc.

Usa:

  • /connect nel terminale, oppure
  • Impostazioni → Providers → Connetti Provider (stessi Passi 1–2 sopra).

Tieni i segreti nel vault di autenticazione di OpenCode; jsonc definisce solo provider, modelli e varianti Reasoning.

Provider APIMaster in jsonc

ID provider: apimaster. Pacchetto npm: @ai-sdk/openai-compatible.

baseURL deve essere:

https://apimaster.ai/v1

Non https://apimaster.ai/ — OpenCode aggiunge /chat/completions. Senza /v1 ottieni https://apimaster.ai/chat/completions → 404 Non Trovato.

Nemmeno https://api.apimaster.ai/v1 — l'host con prefisso api. può causare errori TLS / di connessione nei test. L'host corretto è https://apimaster.ai/v1.

Esempio completo con varianti Reasoning — scarica e sovrascrivi la configurazione di OpenCode:

  1. Scarica opencode.jsonc
  2. Sovrascrivi (o salva come):
    • macOS / Linux: ~/.config/opencode/opencode.jsonc
    • Windows: C:\Users\<nomeutente>\.config\opencode\opencode.jsonc
  3. Configura la chiave API tramite /connect o interfaccia (mai in jsonc).
  4. Riavvia OpenCode Desktop o avvia una nuova sessione.

Esegui il backup del file esistente prima di sovrascrivere, oppure unisci solo il blocco provider.apimaster.

Struttura minima:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "apimaster": {
      "name": "APIMaster.ai",
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "https://apimaster.ai/v1" },
      "models": {
        "gpt-5.5": {
          "name": "gpt-5.5",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "high": { "reasoningEffort": "high" }
          }
        }
      }
    }
  }
}

I campi attachment e modalities su gpt-5.5 qui sopra abilitano l'input immagine (Vision) — vedi Abilitare l'input immagine per GPT e Claude. Omettili se ti serve solo la chat testuale.

Principi di Reasoning

  • variants = più livelli di Reasoning per un id modello nell'interfaccia.
  • Per API compatibili con OpenAI, OpenCode mappa reasoningEffort → reasoning_effort nel corpo della richiesta.
  • I nomi delle varianti devono corrispondere al parametro reale (high → "reasoningEffort": "high").
  • Ogni modello supporta livelli diversi — configura secondo la documentazione ufficiale; nessun rimappaggio nascosto.

Livelli di Reasoning per modello

Modello Varianti Reasoning Note
gpt-5.4 low, medium, high, xhigh Reasoning GPT
gpt-5.5 low, medium, high, xhigh Reasoning GPT
deepseek-v4-flash high, max Pensiero DeepSeek (consigliato)
deepseek-v4-pro high, max Pensiero DeepSeek (consigliato)
claude-sonnet-4-6 low, medium, high, max Sforzo Claude Sonnet
claude-opus-4-7 low, medium, high, xhigh, max Sforzo Claude Opus
claude-opus-4-8 low, medium, high, xhigh, max Sforzo Claude Opus
claude-haiku-4-5 nessuno Nessun livello di sforzo confermato
minimax-m3 nessuno Nessun livello di sforzo confermato

Vedi opencode.jsonc per il file completo.

Cambiare Reasoning in OpenCode

  1. Salva opencode.jsonc, poi riavvia o nuova sessione.
  2. Usa il menu a discesa del modello / Reasoning (es. gpt-5.4 / high).
  3. Se supportato nella tua build: Ctrl + Maiusc + D cicla i livelli di Reasoning.

Abilitare l'input immagine per GPT e Claude

I modelli di APIMaster.ai come gpt-5.5, claude-sonnet-4-6, claude-opus-4-7, claude-opus-4-8 e claude-haiku-4-5 supportano l'input immagine / Vision — leggere screenshot, foto, grafici per riconoscimento, descrizione, OCR o coding a partire da un'immagine.

Un modello che supporta le immagini ≠ OpenCode che invia l'immagine. Anche se il modello di APIMaster.ai supporta di per sé la vision, devi dichiarare la capacità in opencode.jsonc. Altrimenti OpenCode potrebbe non inviare l'immagine come input multimodale — inserisce solo il nome dell'allegato / del file nel prompt, e il modello risponde qualcosa come "il modello attuale non supporta l'input immagine".

I due campi da dichiarare

Per ogni modello che vuoi usare con le immagini, aggiungi:

"attachment": true,
"modalities": {
  "input": ["text", "image"],
  "output": ["text"]
}
  • attachment: true dice a OpenCode che questo modello accetta allegati.
  • modalities.input che contiene "image" dice a OpenCode che questo modello supporta l'input immagine, così OpenCode converte l'immagine in contenuto multimodale image_url.

Esempio completo (GPT e Claude)

Scarica opencode.jsonc (campi già inclusi), oppure unisci il blocco provider.apimaster qui sotto nella tua configurazione esistente:

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": [],
  "provider": {
    "apimaster": {
      "name": "APIMaster.ai",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://apimaster.ai/v1"
      },
      "models": {
        "gpt-5.5": {
          "name": "gpt-5.5",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "xhigh": { "reasoningEffort": "xhigh" }
          }
        },
        "claude-sonnet-4-6": {
          "name": "claude-sonnet-4-6",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "max": { "reasoningEffort": "max" }
          }
        },
        "claude-opus-4-7": {
          "name": "claude-opus-4-7",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "xhigh": { "reasoningEffort": "xhigh" },
            "max": { "reasoningEffort": "max" }
          }
        },
        "claude-opus-4-8": {
          "name": "claude-opus-4-8",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "xhigh": { "reasoningEffort": "xhigh" },
            "max": { "reasoningEffort": "max" }
          }
        },
        "claude-haiku-4-5": {
          "name": "claude-haiku-4-5",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          }
        }
      }
    }
  }
}

Note:

  • Per abilitare l'input immagine solo per gpt-5.5, aggiungi attachment e modalities solo a gpt-5.5; lascia gli altri invariati.
  • Per abilitare solo Claude, aggiungi questi campi solo ai modelli Claude.
  • Mantieni le varianti Reasoning esistenti di ogni modello (low / medium / high / xhigh / max) — i campi immagine e Reasoning non sono in conflitto.
  • Dopo aver modificato opencode.jsonc, chiudi completamente e riavvia OpenCode, o almeno avvia una nuova sessione, così la configurazione viene ricaricata.
  • Non inserire mai la chiave API in questo file — configurala tramite /connect o l'interfaccia (vedi Sicurezza più sotto).

Origine dell'immagine: preferisci l'upload locale / base64

  • Consigliato: carica un file PNG / JPG locale in OpenCode. Idealmente OpenCode lo converte in un data URL base64 (data:image/png;base64,...) prima di inviarlo ad APIMaster — questo è il percorso verificato che funziona.
  • Passare direttamente un URL pubblico di immagine può fallire. APIMaster / l'upstream potrebbe non riuscire a scaricare un'immagine pubblica per motivi di rete, formato, dimensione, MIME o protezione hotlink, restituendo:
    Error while downloading file. Upstream status code: 400.
    In tal caso, usa un data URL base64 o l'upload locale invece di fare affidamento sul lato modello per scaricare un URL pubblico.

Verificare che il riconoscimento immagini funzioni

Opzione A — Test in OpenCode

  1. Passa a apimaster/gpt-5.5 o apimaster/claude-sonnet-4-6 nel menu a discesa dei modelli.
  2. Carica un'immagine PNG / JPG.
  3. Digita:
    Describe the main content of this image.
  • Con la configurazione corretta, il modello dovrebbe descrivere il contenuto dell'immagine.
  • Se il modello menziona solo un nome di file / allegato, o risponde "image input not supported", probabilmente OpenCode non sta inviando il contenuto dell'immagine — controlla i campi attachment e modalities del modello e riavvia OpenCode.

Opzione B — Test direttamente tramite l'API

Utile per distinguere un problema del modello APIMaster da un problema dell'adattatore OpenCode. Non inserire mai una chiave reale nel codice — usa una variabile d'ambiente.

Linux / macOS:

export APIMASTER_API_KEY="your APIMaster API key"

curl https://apimaster.ai/v1/chat/completions \
  -H "Authorization: Bearer $APIMASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Describe this image." },
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,YOUR_IMAGE_BASE64"
            }
          }
        ]
      }
    ],
    "max_tokens": 1000
  }'

Sostituisci model con claude-sonnet-4-6 per testare Claude allo stesso modo (verificato HTTP 200 con riconoscimento immagini).

Windows PowerShell:

$env:APIMASTER_API_KEY = "your APIMaster API key"
# Convert a local image to base64, put it into image_url.url as data:image/png;base64,...
# Then call https://apimaster.ai/v1/chat/completions with the same JSON body.

Una risposta 200 che descrive l'immagine significa che l'input immagine funziona dal lato APIMaster; se OpenCode continua a fallire, il problema è nella configurazione attachment / modalities di OpenCode o in un riavvio mancante.

Risoluzione dei problemi

Configurazione interfaccia

Problema Soluzione
401 Controlla la chiave; ruotala se esposta
Modello non trovato L'URL base deve essere https://apimaster.ai/v1; l'id modello deve corrispondere al marketplace
Nessun modello APIMaster Modifica il provider in Impostazioni → aggiungi mappature → Invia
Lento / timeout Prova un altro modello; usa API Key Tester

Reasoning / jsonc

Perché solo high e max per DeepSeek?
Lo sforzo di pensiero ufficiale compatibile con OpenAI per DeepSeek è high e max. Evita low / medium / xhigh che vengono rimappati in modo imprevedibile.

Perché max per Claude Sonnet e non xhigh?
Il livello massimo di Sonnet è max; xhigh è per Opus (claude-opus-4-7 / claude-opus-4-8).

Perché nessuna variante per Haiku o MiniMax M3?
Senza valori documentati di reasoningEffort, salta le varianti — il modello funziona comunque; l'interfaccia semplicemente non mostrerà sottolivelli di Reasoning.

Ricevi ancora errore 400?

  1. baseURL = https://apimaster.ai/v1 (non root del sito).
  2. L'ortografia dell'id modello corrisponde al marketplace.
  3. Chiave configurata tramite /connect o interfaccia.
  4. Rimuovi temporaneamente le variants — se le richieste semplici funzionano, il reasoning_effort scelto potrebbe non essere supportato per quel modello.

Input immagine / Vision

Perché OpenCode dice "the current model does not support image input"?

  • gpt-5.5 e vari modelli Claude di APIMaster.ai supportano l'input immagine; questo messaggio di solito significa che OpenCode non sta inviando l'immagine come input multimodale.
  • Verifica che il modello in opencode.jsonc abbia:
    "attachment": true,
"modalities": {
  "input": ["text", "image"],
  "output": ["text"]
}
  • Conferma di aver riavviato OpenCode dopo la modifica.
  • Conferma che baseURL sia https://apimaster.ai/v1.
  • Conferma che la chiave API APIMaster sia valida.
  • Se un URL pubblico di immagine fallisce, usa un data URL base64 o l'upload locale.

Perché il modello vede solo il nome dell'allegato, non l'immagine?

  • Di solito OpenCode non ha letto e convertito l'allegato in input immagine — ha solo inserito il nome del file / allegato nel prompt.
  • Abilita attachment: true e modalities.input: ["text", "image"], e usa un modello che supporta l'input immagine.

Perché un URL pubblico di immagine dà errore?

  • APIMaster o l'upstream potrebbero essere limitati da rete, formato, dimensione del file, MIME, protezione hotlink o proxy durante il download di un'immagine pubblica.
  • In caso di Error while downloading file. Upstream status code: 400., passa a un data URL base64.

Ancora non funziona dopo aver aggiunto attachment?

  1. Chiudi completamente e riavvia OpenCode.
  2. Avvia una nuova sessione per testare.
  3. Conferma che il modello attivo della sessione sia quello configurato con i campi immagine.
  4. Conferma che la chiave API sia valida.
  5. Controlla i log di OpenCode per errori 401 / 400 / unsupported image / invalid content type.
  6. Usa Opzione B — Test direttamente tramite l'API con un'immagine base64 per separare un problema del modello APIMaster da un problema dell'adattatore OpenCode.

Sicurezza

  • Non inserire la chiave API APIMaster in opencode.jsonc; quel file contiene solo provider, modelli, capacità immagine e Reasoning.
  • Non incollare la chiave in chat, screenshot, issue, documentazione pubblica o repository di codice.
  • Ruota le chiavi apparse in screenshot o log — revocale e rigenerale nella console, poi aggiorna il provider in OpenCode.
  • Preferisci il flusso /connect di OpenCode, le variabili d'ambiente o l'archiviazione locale delle credenziali per gestire la chiave API.
  • OpenCode può leggere/scrivere file ed eseguire comandi shell — usa solo workspace fidati.

Checklist

  • OpenCode Desktop installato
  • Provider personalizzato connesso oppure apimaster in opencode.jsonc
  • URL base / baseURL = https://apimaster.ai/v1 (non https://apimaster.ai/)
  • Chiave API tramite /connect o interfaccia (non in jsonc)
  • Almeno un modello chat mappato
  • (Opzionale) Varianti Reasoning corrispondenti ai livelli ufficiali
  • Messaggio di test completato con successo

Checklist input immagine

  • baseURL è https://apimaster.ai/v1 (non https://api.apimaster.ai/v1)
  • Usi un modello con capacità vision, es. gpt-5.5 o un modello Claude con capacità Vision
  • Il modello ha attachment: true
  • Il modalities.input del modello contiene "image"
  • OpenCode riavviato dopo la modifica di opencode.jsonc
  • La chiave API è valida
  • L'immagine di test è in un formato comune (PNG / JPG)
  • Se un URL pubblico di immagine fallisce, hai provato un data URL base64

Riepilogo

  • Chiavi: baseURL (https://apimaster.ai/v1), id modello, chiave API (/connect o interfaccia), varianti Reasoning opzionali.
  • Nomi delle varianti = valori effettivi di reasoning_effort.
  • Configura i livelli per modello; salta le varianti quando non supportate (Haiku, MiniMax M3).

Vedi anche