Pi

Pi puede conectarse a HiAPI mediante models.json. Los pasos siguientes usan deepseek-v4.1-flash como ejemplo; este tutorial se verificó en Mac con Pi 1.3.0. En Windows, instala Git Bash primero (paso 3).

1. Instala Node.js

Instala LTS 22.19 o posterior como se describe en Instalación de Node.js, y sáltalo si ya lo tienes. Después ejecuta los dos comandos siguientes en una terminal; basta con ver números de versión:

node --version
npm --version

En Windows PowerShell, escribe los comandos npm / npx que aparecen más adelante en esta guía como npm.cmd / npx.cmd.

2. Instala Pi

Ejecuta cada línea en una terminal:

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

Basta con ver 1.3.0. En Windows PowerShell, usa npm.cmd install -g --ignore-scripts @earendil-works/pi-coding-agent@1.3.0 y pi.cmd --version.

3. Instala Git Bash primero en Windows (sáltalo en Mac)

1. Abre la página de descarga de Git para Windows, descarga el instalador de tu arquitectura y ejecútalo. Mantén el directorio de instalación como C:\Program Files\Git, elige la opción de PATH recomendada Git from the command line and also from 3rd-party software y haz clic en Install → Finish. Salta esto si ya tienes Git Bash.
2. Cierra la ventana de PowerShell antigua, vuelve a abrirla y confirma la ruta de Bash:

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

Basta con ver una versión de GNU bash. Si lo instalaste en otro sitio, busca el bin\bash.exe real en el Explorador de archivos y sustituye la ruta del comando.

3. Pi suele encontrar Git Bash automáticamente. Solo si después de arrancar sigue diciendo que no encuentra Bash, abre %USERPROFILE%\.pi\agent\settings.json en el Bloc de notas (haz primero una copia si el archivo ya existe), añade o actualiza el campo shellPath y conserva los demás campos:

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

Usa tu ruta de instalación real y escribe las barras invertidas dos veces. En Save as, elige “Todos los archivos”, UTF-8, nombre de archivo settings.json, y vuelve a abrir Pi después de guardar.

4. Obtén una HiAPI API key

Prepara una clave como se describe en Obtener una API key, haz clic en el icono de copiar junto a la clave y copia la HiAPI API key completa; la necesitarás en el paso 7.

5. Abre el archivo de configuración de modelos

En un Mac, ejecuta cada línea en una terminal (si ya existe models.json, se hace antes una copia de seguridad automáticamente):

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"

Si has definido PI_CODING_AGENT_DIR, edita models.json en ese directorio; si no, usa el directorio predeterminado de arriba.

6. Añade la configuración de DeepSeek y guarda

1. Escribe el contenido de abajo en models.json (no lo ejecutes línea a línea en la terminal). Para un archivo nuevo, pégalo entero; si el archivo existe, combina solo hiapi-deepseek en el providers existente, conserva los demás proveedores y deja exactamente un providers de nivel superior.

{
  "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. En apiKey, ${HIAPI_API_KEY} es la forma en que Pi lee una variable de entorno; déjalo como está y define la clave en el paso siguiente. Usa comillas dobles y comas en el JSON, sin coma final tras el último elemento y sin comentarios.

① Añade el objeto hiapi-deepseek completo dentro de providers; ② mantén el marcador de variable de entorno en apiKey. Los otros proveedores que ya aparecen en la captura pueden quedarse.

3. Guarda: en nano de Mac pulsa Ctrl+O → Enter → Ctrl+X; en el Bloc de notas de Windows elige Save as, “Todos los archivos”, UTF-8, y pon al archivo exactamente el nombre models.json, no .json.txt.

7. Define la API key e inicia Pi

1. En un Mac, ejecuta esto en la misma terminal en la que vayas a iniciar Pi (sustituye YOUR_HIAPI_API_KEY por tu HiAPI API key y conserva las comillas):

export HIAPI_API_KEY="YOUR_HIAPI_API_KEY"

2. Ve a la carpeta de tu proyecto e inicia Pi, o crea primero un directorio vacío:

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 variable de entorno solo se aplica a la terminal actual; vuelve a definirla después de cerrar la terminal. Con HiAPI no necesitas ejecutar /login en Pi.

8. Elige un modelo y verifica

1. En la caja de entrada de Pi, escribe /model y pulsa Enter, busca hiapi, usa las flechas para seleccionar DeepSeek V4.1 Flash (HiAPI) (proveedor hiapi-deepseek) y pulsa Enter.

① Muévete a la fila de DeepSeek con las flechas; ② pulsa Enter para seleccionarlo.

2. Escribe /thinking y pulsa Enter, elige uno de off / low / high / max y pulsa Enter; para una primera prueba, elige low.

① Elige uno de off, low, high, max; ② pulsa Enter para aplicarlo a la sesión actual.

3. Enter solo se aplica a la sesión actual; para hacer de este nivel el predeterminado en futuras sesiones, pulsa Ctrl+S como sugiere el menú.

4. Envía “Hola, preséntate en una frase.” Una respuesta normal significa que la conexión funciona. Si el Registro de solicitudes de la consola de HiAPI muestra esta solicitud, está pasando por HiAPI.

Solución de problemas

Aquí solo se recogen los problemas propios de Pi. Para errores comunes como 401, 404 y 429, consulta Errores comunes.