Pi

Pi può collegarsi a HiAPI tramite models.json. I passaggi seguenti usano deepseek-v4.1-flash come esempio; questo tutorial è stato verificato su Mac con Pi 1.3.0. Su Windows installa prima Git Bash (passaggio 3).

1. Installare Node.js

Installa LTS 22.19 o successivo come descritto in Configurazione di Node.js e saltalo se ce l’hai già. Poi esegui i due comandi seguenti in un terminale; basta vedere i numeri di versione:

node --version
npm --version

In Windows PowerShell, nei comandi npm / npx più avanti in questa guida scrivi npm.cmd / npx.cmd.

2. Installare Pi

Esegui ciascuna riga in un terminale:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent@1.3.0
pi --version

Basta vedere 1.3.0. In Windows PowerShell usa npm.cmd install -g --ignore-scripts @earendil-works/pi-coding-agent@1.3.0 e pi.cmd --version.

3. Su Windows installare prima Git Bash (salta su Mac)

1. Apri la pagina di download di Git for Windows, scarica l’installer per la tua architettura ed eseguilo. Mantieni la directory di installazione C:\Program Files\Git, scegli l’opzione PATH consigliata Git from the command line and also from 3rd-party software e fai clic su Install → Finish. Salta questo passaggio se hai già Git Bash.
2. Chiudi la vecchia finestra PowerShell, riaprila e verifica il percorso di Bash:

& 'C:\Program Files\Git\bin\bash.exe' --version

Basta vedere una versione di GNU bash. Se hai installato altrove, trova il vero bin\bash.exe in Esplora file e sostituisci il percorso nel comando.

3. Di solito Pi trova Git Bash automaticamente. Solo se dopo l’avvio dice ancora che Bash non viene trovato, apri %USERPROFILE%\.pi\agent\settings.json nel Blocco note (prima fai il backup di un file esistente), aggiungi o aggiorna il campo shellPath e mantieni gli altri campi:

{
  "shellPath": "C:\\Program Files\\Git\\bin\\bash.exe"
}

Usa il tuo percorso di installazione reale e scrivi le barre rovesciate due volte. In Save as scegli “All files”, UTF-8, nome file settings.json, poi riapri Pi dopo aver salvato.

4. Ottenere una chiave API HiAPI

Prepara una chiave come descritto in Ottieni una chiave API, fai clic sull’icona di copia accanto alla chiave e copia la chiave API HiAPI completa; ti servirà al passaggio 7.

5. Aprire il file di configurazione dei modelli

Su Mac esegui ciascuna riga in un terminale (un models.json esistente viene prima salvato automaticamente come backup):

mkdir -p "$HOME/.pi/agent"
if [ -f "$HOME/.pi/agent/models.json" ]; then cp "$HOME/.pi/agent/models.json" "$HOME/.pi/agent/models.json.bak-$(date +%Y%m%d-%H%M%S)"; fi
nano "$HOME/.pi/agent/models.json"

Windows PowerShell:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.pi\agent"
if (Test-Path "$env:USERPROFILE\.pi\agent\models.json") { Copy-Item "$env:USERPROFILE\.pi\agent\models.json" "$env:USERPROFILE\.pi\agent\models.json.bak-$(Get-Date -Format yyyyMMdd-HHmmss)" }
notepad "$env:USERPROFILE\.pi\agent\models.json"

Se hai impostato PI_CODING_AGENT_DIR, modifica models.json in quella directory; altrimenti usa la directory predefinita qui sopra.

6. Aggiungere la configurazione DeepSeek e salvare

1. Scrivi il contenuto seguente in models.json (non eseguirlo riga per riga nel terminale). Per un file nuovo incollalo tutto; se il file esiste, unisci solo hiapi-deepseek dentro i providers esistenti, mantieni gli altri provider e lascia un solo providers di primo livello.

{
  "providers": {
    "hiapi-deepseek": {
      "baseUrl": "https://api.hiapi.ai/v1",
      "api": "openai-completions",
      "apiKey": "${HIAPI_API_KEY}",
      "models": [
        {
          "id": "deepseek-v4.1-flash",
          "name": "DeepSeek V4.1 Flash (HiAPI)",
          "api": "openai-completions",
          "reasoning": true,
          "input": [
            "text"
          ],
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "thinkingLevelMap": {
            "minimal": null,
            "low": "low",
            "medium": null,
            "high": "high",
            "xhigh": null,
            "max": "max"
          },
          "compat": {
            "thinkingFormat": "deepseek",
            "maxTokensField": "max_tokens",
            "supportsReasoningEffort": true
          }
        }
      ]
    }
  }
}

2. In apiKey, ${HIAPI_API_KEY} è il modo in cui Pi legge una variabile d’ambiente; lascialo così e imposta la chiave nel passaggio successivo. Usa virgolette doppie e virgole nel JSON, nessuna virgola finale dopo l’ultimo elemento e nessun commento.

① Aggiungi l’intero oggetto hiapi-deepseek sotto providers; ② mantieni il segnaposto della variabile d’ambiente in apiKey. Gli altri provider già presenti nello screenshot possono restare.

3. Salva: nel nano di Mac premi Ctrl+O → Enter → Ctrl+X; nel Blocco note di Windows scegli Save as, “All files”, UTF-8, e chiama il file esattamente models.json, non .json.txt.

7. Impostare la chiave API e avviare Pi

1. Su Mac esegui questo nello stesso terminale in cui avvierai Pi (sostituisci YOUR_HIAPI_API_KEY con la tua chiave API HiAPI e mantieni le virgolette):

export HIAPI_API_KEY="YOUR_HIAPI_API_KEY"

2. Vai nella cartella del tuo progetto e avvia Pi, oppure crea prima una directory vuota:

mkdir -p "$HOME/hiapi-project"
cd "$HOME/hiapi-project"
pi

Windows PowerShell:

$env:HIAPI_API_KEY="YOUR_HIAPI_API_KEY"
New-Item -ItemType Directory -Force "$env:USERPROFILE\hiapi-project"
Set-Location "$env:USERPROFILE\hiapi-project"
pi.cmd

3. La variabile d’ambiente vale solo per il terminale corrente; impostala di nuovo dopo aver chiuso il terminale. Con HiAPI non devi eseguire /login in Pi.

8. Scegliere un modello e verificare

1. Nella casella di input di Pi digita /model e premi Invio, cerca hiapi, usa i tasti freccia per selezionare DeepSeek V4.1 Flash (HiAPI) (provider hiapi-deepseek) e premi Enter.

① Spostati sulla riga DeepSeek con i tasti freccia; ② premi Enter per selezionarla.

2. Digita /thinking e premi Invio, scegli uno tra off / low / high / max e premi Enter; per un primo tentativo scegli low.

① Scegli uno tra off, low, high, max; ② premi Enter per applicarlo alla sessione corrente.

3. Invio vale solo per la sessione corrente; per rendere questo livello il valore predefinito delle sessioni future, premi Ctrl+S come suggerisce il menu.

4. Invia “Ciao, presentati in una frase.” Una risposta normale significa che il collegamento funziona. Se i Registri delle richieste nella console HiAPI mostrano questa richiesta, sta passando da HiAPI.

Risoluzione dei problemi

Qui sono elencati solo i problemi specifici di Pi. Per gli errori comuni come 401, 404 e 429, vedi Errori comuni.