Documentazione

API Reference
Alice

API OpenAI-compatibile. Integra Alice in qualsiasi applicazione in pochi minuti.

⚡ OpenAI-compatible 🔒 Token + Machine ID 🌐 REST / Streaming
Inizia
Quick Start Autenticazione Base URL
Endpoint
Chat Completions Models Token Validate
Integrazioni
Python SDK Node.js Continue.dev VS Code
Riferimento
Codici di errore Limiti
Inizia

Quick Start

L'API di Alice è completamente compatibile con lo standard OpenAI. Se usi già il client OpenAI ufficiale, basta cambiare base_url e aggiungere il tuo token.

1
Ottieni il tuo token
Contatta il team Synapse per ricevere un token di accesso. Ogni token è legato al tuo Machine ID — non è trasferibile.
2
Nota il tuo Machine ID
Il Machine ID identifica univocamente il dispositivo autorizzato. Puoi copiarlo dall'estensione VS Code oppure calcolarlo con il tool CLI.
3
Prima chiamata API
Sostituisci i placeholder con il tuo token e Machine ID, poi esegui il codice qui sotto.
curl https://api.synapsecorp.org/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Machine-ID: YOUR_MACHINE_ID" \
  -d '{
    "model": "alice",
    "messages": [
      {"role": "user", "content": "Ciao Alice!"}
    ]
  }'
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_TOKEN",
    base_url="https://api.synapsecorp.org/v1",
    default_headers={
        "X-Machine-ID": "YOUR_MACHINE_ID"
    }
)

response = client.chat.completions.create(
    model="alice",
    messages=[
        {"role": "user", "content": "Ciao Alice!"}
    ]
)
print(response.choices[0].message.content)
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_TOKEN",
  baseURL: "https://api.synapsecorp.org/v1",
  defaultHeaders: {
    "X-Machine-ID": "YOUR_MACHINE_ID"
  }
});

const response = await client.chat.completions.create({
  model: "alice",
  messages: [
    { role: "user", content: "Ciao Alice!" }
  ]
});
console.log(response.choices[0].message.content);
Autenticazione

Token + Machine ID

Ogni richiesta richiede due identificatori: un token Bearer e un Machine ID. Il sistema verifica che il token sia valido e che provenga dal dispositivo autorizzato. Non è possibile usare un token su un dispositivo non registrato.

⚠️

Token non trasferibile. Il token è legato a un singolo Machine ID. L'uso su un dispositivo non autorizzato causa la revoca automatica e permanente del token.

Headers richiesti

HeaderObbligatorioDescrizione
Authorization required Bearer <token> — il tuo token di accesso personale.
X-Machine-ID required UUID del dispositivo registrato. Recuperabile dall'estensione VS Code.
Content-Type optional application/json (predefinito)

Trovare il tuo Machine ID

→
VS Code Extension
Apri la palette comandi (Ctrl+Shift+P) e cerca Synapse: Copy Machine ID. Il Machine ID viene copiato negli appunti.
→
API Validate
Chiama POST /auth/validate con il tuo token — la risposta include il Machine ID registrato e la data di scadenza.
Base URL

API Endpoint

Tutti gli endpoint usano questa base URL. L'API è completamente compatibile con il client OpenAI ufficiale — basta impostare baseURL.

URL
https://api.synapsecorp.org/v1
ℹ️

L'infrastruttura è completamente on-premise. Nessun dato transita su cloud pubblici.

Endpoint

POST /v1/chat/completions

Endpoint principale per conversazioni con Alice. Supporta modalità streaming e non-streaming. Compatibile al 100% con openai.ChatCompletion.create().

Parametri della richiesta

ParametroTipoObbl.Descrizione
model string required Usa alice come nome del modello.
messages array required Array di oggetti {role, content}. Role può essere system, user, assistant.
stream boolean optional Se true, abilita la risposta in streaming SSE. Default: false.
temperature number optional Creatività della risposta, da 0.0 a 2.0. Default: 0.7.
max_tokens integer optional Numero massimo di token nella risposta. Default: 2048.
top_p number optional Nucleus sampling. Alternativa a temperature. Default: 1.0.
system string optional Prompt di sistema di Alice. Se omesso, usa la personalità predefinita.

Esempio: Streaming

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_TOKEN",
    base_url="https://api.synapsecorp.org/v1",
    default_headers={"X-Machine-ID": "YOUR_MACHINE_ID"}
)

with client.chat.completions.stream(
    model="alice",
    messages=[{"role": "user", "content": "Scrivimi un haiku sul networking"}],
) as stream:
    for chunk in stream:
        print(chunk.choices[0].delta.content or "", end="", flush=True)
const stream = await client.chat.completions.create({
  model: "alice",
  messages: [{ role: "user", content: "Scrivimi un haiku" }],
  stream: true
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
console.log();

GET /v1/models

Restituisce l'elenco dei modelli disponibili sull'istanza. Compatibile con il formato OpenAI standard.

cURL
curl https://api.synapsecorp.org/v1/models \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Machine-ID: YOUR_MACHINE_ID"
Risposta
{
  "object": "list",
  "data": [
    {
      "id": "alice",
      "object": "model",
      "created": 1720000000,
      "owned_by": "synapse"
    }
  ]
}

POST /auth/validate

Verifica la validità del token e restituisce le informazioni sul dispositivo registrato e la data di scadenza.

curl -X POST https://api.synapsecorp.org/auth/validate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Machine-ID: YOUR_MACHINE_ID"
{
  "valid": true,
  "machine_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "expires_at": "2026-12-31T23:59:59Z",
  "plan": "professional"
}
Integrazioni

Python

Usa il client ufficiale openai — nessuna libreria aggiuntiva necessaria. Installa con pip e punta il client all'API Synapse.

bash
pip install openai
python
from openai import OpenAI
import os

# Leggi token e machine ID da variabili d'ambiente
client = OpenAI(
    api_key=os.environ["SYNAPSE_TOKEN"],
    base_url="https://api.synapsecorp.org/v1",
    default_headers={
        "X-Machine-ID": os.environ["SYNAPSE_MACHINE_ID"]
    }
)

# Conversazione con memoria
messages = [
    {"role": "system", "content": "Sei Alice, assistente AI di Synapse."},
    {"role": "user", "content": "Analizza questo codice Python..."}
]

response = client.chat.completions.create(
    model="alice",
    messages=messages,
    temperature=0.7,
    max_tokens=4096
)

answer = response.choices[0].message.content
messages.append({"role": "assistant", "content": answer})

Node.js / TypeScript

Funziona con openai npm package versione 4+. Supporta TypeScript nativamente.

bash
npm install openai
typescript
import OpenAI from "openai";

const alice = new OpenAI({
  apiKey: process.env.SYNAPSE_TOKEN!,
  baseURL: "https://api.synapsecorp.org/v1",
  defaultHeaders: {
    "X-Machine-ID": process.env.SYNAPSE_MACHINE_ID!
  }
});

async function chat(prompt: string): Promise<string> {
  const res = await alice.chat.completions.create({
    model: "alice",
    messages: [{ role: "user", content: prompt }],
    stream: false
  });
  return res.choices[0].message.content ?? "";
}

// Express.js example
app.post("/chat", async (req, res) => {
  const reply = await chat(req.body.message);
  res.json({ reply });
});

Continue.dev

Continue è un'estensione AI per VS Code e JetBrains. Puoi configurarla manualmente per usare Alice, oppure usare l'estensione Synapse che la configura automaticamente.

💡

Configurazione automatica. Installa l'estensione Alice AI — Synapse da VS Marketplace e inserisci il token nel wizard: Continue.dev viene configurato automaticamente.

Configurazione manuale

Modifica il file ~/.continue/config.json:

json — ~/.continue/config.json
{
  "models": [
    {
      "title": "Alice (Synapse)",
      "provider": "openai",
      "model": "alice",
      "apiBase": "https://api.synapsecorp.org/v1",
      "apiKey": "YOUR_TOKEN",
      "requestOptions": {
        "headers": {
          "X-Machine-ID": "YOUR_MACHINE_ID"
        }
      }
    }
  ]
}

VS Code Extension

L'estensione Alice AI — Synapse semplifica l'intera configurazione: genera il Machine ID, valida il token, configura Continue.dev automaticamente e mostra lo stato nella status bar.

1
Installa l'estensione
Cerca Alice AI Synapse su VS Marketplace (ID: synapseresearch.aliceaisynapse) oppure installa il .vsix manualmente.
2
Apri il wizard
Usa Ctrl+Shift+P → Synapse: Configure Alice. Il wizard mostra il tuo Machine ID e ti chiede di incollare il token.
3
Verifica lo stato
La status bar mostra ✦ Alice se il token è valido. Continue.dev è già configurato — riavvia VS Code se necessario.

Comandi disponibili

ComandoDescrizione
Synapse: Configure AliceApre il wizard di configurazione.
Synapse: Check StatusVerifica che il token sia valido e connesso.
Synapse: Open ChatApre la chat web di Alice nel browser.
Synapse: Copy Machine IDCopia il Machine ID negli appunti.
Riferimento

Codici di errore

L'API restituisce errori nel formato standard OpenAI: {error: {message, type, code}}.

Codice HTTP Tipo Causa
200 success Richiesta completata con successo.
400 invalid_request_error Body JSON malformato o parametri mancanti.
401 authentication_error Token mancante o non valido nell'header Authorization.
403 permission_error Machine ID non corrisponde al token. Dispositivo non autorizzato.
404 not_found_error Endpoint o modello non trovato.
429 rate_limit_error Limite di richieste superato. Riprova dopo il reset.
500 server_error Errore interno del server. Controlla la pagina Status.
503 service_unavailable Il modello è in caricamento o il server è in manutenzione.
Esempio di risposta di errore
{
  "error": {
    "message": "Machine ID does not match token binding",
    "type": "permission_error",
    "code": "machine_id_mismatch"
  }
}

Limiti e quote

I limiti dipendono dal piano attivato sul tuo token. I limiti attuali sono indicativi — contatta il team per configurazioni enterprise.

ParametroValoreNote
Context window 128 000 token Input + output combinati.
Max output tokens 8 192 Configurabile con max_tokens.
Req / minuto 60 RPM Piano professional. Contattare per aumentare.
Timeout 120 s Timeout massimo per richiesta non-streaming.
Dispositivi per token 1 Un token = un Machine ID. Contattare per licenze multi-seat.
ℹ️

Enterprise. Per deployment on-premise su infrastruttura propria, istanze dedicate o licenze multi-seat contatta il team Synapse.