☁️ TorqueMind Docs

Backend self-hosted stile Firebase. Auth, Database, Storage, Cloud Functions, Hosting, AI Services, Security Rules e App Android in un unico server Node.js.

Node.jsSQLiteREST API WebSDKReact Native SDKSSE Realtime API KeysLLM LocaleVision AIWeb SearchRAG PDFVideo AIWebRTCRetrace IAAppDB/AppAuth/AppFnSongForgeImageGenVideoGenGeocodingUser ConsoleApp AndroidPush NotificationsHTTPS

📖 Introduzione

TorqueMind è un backend-as-a-service che replica le funzionalità di Firebase: autenticazione JWT, database Firestore-like, storage file, cloud functions eseguibili via HTTP, hosting di webapp statiche e regole di sicurezza.
🚧 Beta — TorqueMind è in fase beta pubblica: le API descritte qui possono cambiare e i servizi possono avere limiti di disponibilità. Le breaking changes vengono comunicate tramite gli avvisi in piattaforma.
🔐

Authentication

JWT-based. Login, register, verifica email, reset password, sessioni persistenti.

🗃️

Firestore

Database documenti con collezioni, query, batch write e SSE realtime.

📦

Storage

Upload/download file per bucket. Base64 o binary. Metadata e statistiche.

⚡

Functions

Codice JS eseguito in sandbox isolato. fetch, env vars, async/await, Gemini AI.

🌐

Hosting

Deploy webapp statiche via file, ZIP o cartella. History e rollback istantaneo.

🔔

Messaging

Push notifications Web Push (VAPID) e polling mobile con topic e storico.

🔑

API Keys & AI

Chiavi API Firebase-style per LLM, Vision, TTS, STT e Web Search con permessi granulari.

🎨

Creative Suite

ImgGen, VidGen, SongForge (musica IA), TrackForge (DAW), TorqueConvert, TorqueVideos — UI dedicate per ogni strumento, stesso account.

👤

User Console

Ogni utente ha Firestore, Storage e Hosting isolati con console grafica.

🛡️

Security Rules

Regole di sicurezza JSON stile Firebase per proteggere DB e storage. Individuali per utente.

📱

App Android

Registra le tue app Android con package name e SHA-256. Associa API key per i servizi AI.

📷

Profilo & Avatar

Foto profilo, nome visualizzato, cambio password ed eliminazione account self-service. Avatar distribuito via SDK.

📦 Installare l'SDK

L'SDK Web è un singolo file JavaScript che funziona sia come script tag nel browser che come modulo Node.js/ES.

Browser (tag script)

html
<!-- Hosted direttamente su TorqueMind -->
<script src="https://torquemind.org/sdk/trubaxcloud.js"></script>
<script>
  const app = TorqueMind.initializeApp({
    url: 'https://torquemind.org'
  });
</script>

React Native / Node.js

Per React Native copia il file sdk/trubaxcloud.js nel tuo progetto come src/services/trubaxCloud.js oppure usa direttamente le API REST.
javascript
const TorqueMind = require('./trubaxcloud');
// oppure
import TorqueMind from './trubaxcloud';

const app = TorqueMind.initializeApp({
  url: 'https://torquemind.org'
});

🚀 Quickstart

In 5 righe di codice hai autenticazione, lettura DB e chiamata a una Cloud Function.
javascript — completo
// 1. Inizializza
const app = TorqueMind.initializeApp({ url: 'https://torquemind.org' });

// 2. Login
const user = await app.auth.login('[email protected]', 'password123');

// 3. Leggi dal DB
const result = await app.db.collection('prodotti').doc('abc123').get();
console.log(result.doc);

// 4. Chiama una Cloud Function
const risposta = await app.functions.call('magic', { image: base64 });
console.log(risposta.analysis);

🔐 Authentication

Sistema JWT con sessioni persistenti, verifica email, reset password e listener di stato.

Registrazione e Login

Campi registrazione A differenza di Firebase, TorqueMind richiede username (unico), email, password e opzionalmente displayName.
// Registra nuovo utente (REST API)
const res = await fetch('/auth/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'mario_rossi',      // obbligatorio, unico
    email: '[email protected]',    // obbligatorio, unico
    password: 'password123',      // obbligatorio, min 6 caratteri
    displayName: 'Mario Rossi'    // opzionale
  })
});

// Login
const user = await app.auth.login('[email protected]', 'password');

// Logout
await app.auth.logout();

// Ascolta cambio stato auth (come Firebase)
const unsub = app.auth.onAuthStateChanged(user => {
  if (user) console.log('Loggato:', user.displayName);
  else console.log('Non autenticato');
});
unsub(); // rimuove listener

Metodi disponibili

MetodoRitornaDescrizione
auth.login(email, pass)Promise<User>Login, salva token in localStorage
auth.register(email, pass, name?)Promise<User>Registra e fa login automatico
auth.logout()Promise<void>Revoca token lato server
auth.getUser()Promise<User|null>Utente corrente dal server
auth.currentUserUser|nullUtente sincrono (può essere stale)
auth.onAuthStateChanged(cb)() => voidListener, ritorna funzione di cleanup
auth.updateProfile(data)Promise<User>Aggiorna displayName, avatar
auth.changePassword(old, new)PromiseCambio password autenticato
auth.uploadAvatar(file)PromiseUpload foto profilo (max 5MB)
auth.removeAvatar()PromiseRimuovi foto profilo
auth.deleteAccount(password)PromiseElimina account (irreversibile)

REST API diretta

POST /auth/register          { username, email, password, displayName? }
POST /auth/login             { email, password }  // email può essere anche username
POST /auth/logout            Authorization: Bearer <token>
GET  /auth/me                Authorization: Bearer <token>
PUT  /auth/me                { displayName } — aggiorna nome visualizzato
DELETE /auth/me              { password } — elimina il proprio account (irreversibile)
PUT  /auth/password           { currentPassword, newPassword }
POST /auth/me/avatar         multipart/form-data — upload foto profilo (max 5MB)
GET  /auth/avatar/:id         pubblica, cached 1h — scarica avatar utente
DELETE /auth/me/avatar        rimuovi foto profilo
POST /auth/verify             { token } — verifica token per app esterne
POST /auth/sdk/user           { appSecret, userId } — dati utente per app SDK
POST /auth/send-verification  invia email di verifica (auth)
POST /auth/verify-email       { token } — verifica email
POST /auth/reset-password     { token, newPassword } — reset password con token

🗃️ Firestore Database

Database documenti NoSQL con collezioni, documenti, query e aggiornamenti realtime via SSE. API identica a Firebase Firestore (semplificata).

CRUD documenti

const db = app.db;

// Scrivi documento
await db.collection('utenti').doc('user123').set({
  nome: 'Mario',
  eta: 30,
  createdAt: new Date().toISOString()
});

// Leggi documento
const { doc } = await db.collection('utenti').doc('user123').get();
console.log(doc.nome); // Mario

// Aggiorna (merge parziale)
await db.collection('utenti').doc('user123').update({ eta: 31 });

// Elimina
await db.collection('utenti').doc('user123').delete();

// Aggiungi con ID auto
await db.collection('log').add({ evento: 'login', timestamp: Date.now() });

Query su collezione

// Lista tutti i documenti
const { docs } = await db.collection('prodotti').get();

// Con limite
const { docs } = await db.collection('prodotti').get({ limit: 20 });

// Con filtro where (REST diretta)
GET /db/prodotti?where=[["prezzo",">","10"]]&orderBy=prezzo&order=asc&limit=50

Realtime onSnapshot

// Ascolta aggiornamenti in realtime (SSE)
const unsub = db.collection('messaggi').onSnapshot(payload => {
  console.log('Evento:', payload.type, payload.docId, payload.doc);
});

unsub(); // chiude la connessione SSE

Batch write

await db.batch([
  { type: 'set',    collection: 'items', id: 'a', data: { val: 1 } },
  { type: 'set',    collection: 'items', id: 'b', data: { val: 2 } },
  { type: 'delete', collection: 'items', id: 'c' },
]);

📦 Storage

Upload e download di file organizzati in bucket. Supporta binary, base64 e File/Blob del browser.
const storage = app.storage;

// Upload da input file del browser
const file = document.getElementById('fileInput').files[0];
await storage.ref('immagini', 'user123/avatar.jpg').upload(file, {
  contentType: 'image/jpeg'
});

// Ottieni URL di download
const url = storage.ref('immagini', 'user123/avatar.jpg').getDownloadURL();
// → https://torquemind.org/storage/immagini/user123/avatar.jpg

// Elimina file
await storage.ref('immagini', 'user123/avatar.jpg').delete();

// REST: Lista file in bucket
GET /storage-meta/immagini?prefix=user123/
Upload base64 via REST POST /storage/:bucket/:path con body { data: "<base64>", contentType: "image/jpeg" }

⚡ Cloud Functions

Funzioni JavaScript eseguite in un sandbox isolato (vm.runInContext). Supportano async/await, fetch verso API esterne, variabili d'ambiente e accesso a DB e Auth.

Creare una funzione (Admin Console)

Vai in Admin → Cloud Functions

Clicca "+ Nuova Funzione", scegli il tipo: HTTP (callable), Trigger (su evento DB/Auth/Storage) o Scheduled (periodica).

Scrivi il codice

Il codice è JavaScript normale con await. Usa context per leggere la request e response per rispondere.

Configura le Env Vars

Scroll in basso → pannello "🔑 Variabili d'Ambiente" → aggiungi le chiavi (es. GEMINI_API_KEY).

Testa con "▶️ Esegui Test"

Esegui la funzione dalla console e leggi i log in tempo reale.

API disponibili nel sandbox

// ── CONTEXT (request HTTP) ──
context.method    // GET, POST, PUT, DELETE
context.headers   // headers della richiesta
context.query     // query string params
context.body      // body JSON della richiesta
context.ip        // IP del chiamante

// ── RESPONSE ──
response.status = 200;
response.body = { messaggio: 'ok' };
response.headers['X-Custom'] = 'valore';
__result = { qualsiasi: 'oggetto' }; // per test console

// ── FETCH (API esterne) ──
const res = await fetch('https://api.esempio.com/data', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ chiave: 'valore' })
});
const data = await res.json();

// ── ENV VARS ──
const apiKey = env.get('GEMINI_API_KEY'); // da Admin → Env Vars

// ── DATABASE ──
const { doc } = await db.get('collezione', 'doc-id');
await db.set('collezione', 'doc-id', { campo: 'valore' });
const { docs } = await db.list('collezione', { limit: 10 });
await db.delete('collezione', 'doc-id');

// ── MESSAGING ──
await messaging.sendEmail('[email protected]', 'Oggetto', '<p>HTML</p>');

// ── BUFFER / BASE64 ──
const buf = Buffer.from(base64String, 'base64');
const b64 = buf.toString('base64');

Esempio: funzione che chiama un'API esterna

cloud function — tipo: HTTP, id: magic
const apiKey = env.get('GEMINI_API_KEY');
if (!apiKey) {
  response.status = 500;
  response.body = { error: 'GEMINI_API_KEY non configurata' };
  return;
}
const { image, mimeType } = context.body || {};
const geminiRes = await fetch(
  `https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=${apiKey}`,
  { method: 'POST', headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ contents: [{ parts: [
      { text: 'Descrivi questa immagine in italiano' },
      { inline_data: { mime_type: mimeType, data: image } }
    ]}]})
  }
);
const result = await geminiRes.json();
const text = result.candidates?.[0]?.content?.parts?.[0]?.text;
response.status = 200;
response.body = { success: true, analysis: text };

Endpoint pubblica

// Chiama funzione HTTP pubblica
POST /fn/<id-funzione>
Content-Type: application/json
{ "campo": "valore" }

// Via SDK
const res = await app.functions.call('magic', { image: base64 });

🌐 Hosting

Deploy di webapp statiche (HTML/CSS/JS, React build, Vue dist, ecc.) con history dei deploy e rollback istantaneo. Ogni sito è servito a /sites/:slug/.

Metodi di deploy

3 modi per deployare 1. Admin Console (consigliato): trascina il file ZIP o seleziona la cartella
2. Script Node.js: leggi i file e chiama la REST API
3. curl / API: upload ZIP diretto via HTTP

1 — Deploy dalla console (drag & drop)

Apri la console → Hosting

Clicca sul sito di destinazione oppure crea un nuovo sito con "+ Nuovo Sito".

Trascina il file ZIP o la cartella

Puoi trascinare un file .zip oppure selezionare una cartella intera con il pulsante "📁 Cartella".

Guarda il progresso

Il pannello mostra in tempo reale: Upload → Estrazione → Deploy → ✅ Live.

2 — Deploy via script

javascript — deploy-script.js
const fs = require('fs');
const CLOUD_URL = 'https://torquemind.org';

// 1. Login con il tuo account
const { token } = await (await fetch(`${CLOUD_URL}/auth/login`, {
  method: 'POST', headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: '[email protected]', password: 'LA_TUA_PASSWORD' })
})).json();

// 2. Deploy file HTML singolo
await fetch(`${CLOUD_URL}/hosting/mio-sito/deploy`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: 'Deploy v1.0',
    files: [
      { path: 'index.html', content: fs.readFileSync('./dist/index.html', 'utf8') },
      { path: 'style.css',  content: fs.readFileSync('./dist/style.css', 'utf8') },
    ]
  })
});

3 — Deploy ZIP via curl

shell
# Zippa la cartella dist/
zip -r dist.zip dist/

# Ottieni il token
TOKEN=$(curl -s -X POST https://torquemind.org/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"LA_TUA_PASSWORD"}' | jq -r .token)

# Deploy ZIP
curl -X POST https://torquemind.org/hosting/mio-sito/deploy-zip \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/zip" \
  -H "X-Deploy-Message: Deploy v1.0" \
  --data-binary @dist.zip
Nota sul prefisso ZIP Se il ZIP contiene una cartella radice (es. dist/), il sistema la strip automaticamente. I file vengono serviti dalla root del sito.

Rollback

// Dalla console: sezione "📋 Deploy History" → clicca "↩️ Rollback"
// Via API:
POST /hosting/:id/rollback
{ "deployId": "deploy_1700000000000" }

📈 Market Data (quote & candele)

Dati finanziari reali e keyless: crypto da Binance pubblico, azioni/forex/indici/materie prime/ETF da Yahoo Finance. Per dashboard trading, portfolio, widget prezzi nelle tue app.

Endpoint pubblici (x-api-key o Bearer)

HTTP
GET /api/market/quote?s=SIMBOLO
    → {sym, src, name, price, chg24|chgSess, high, low, vol, ts}
GET /api/market/candles?s=SIMBOLO&interval=1h|4h|1d|1w&n=120
    → {sym, src, candles:[{t,o,h,l,c,v}]}  (OHLCV, ordinati crescenti)
GET /api/market/search?q=testo → {results:[{sym,label,kind}]}
Simboli capiti automaticamente crypto: BTC/BTCUSDT, ETH, SOL, DOGE… · azioni US: AAPL, TSLA, NVDA, MSFT… · Borsa Italiana: UCG.MI, ENEL.MI, ENI.MI, ISP.MI, RACE.MI · forex: EURUSD, GBPUSD, USDJPY · materie: oro→GC=F, argento→SI=F, petrolio→CL=F · indici: sp500→^GSPC, nasdaq→^NDX, dow jones→^DJI, dax→^GDAXI

Realtime crypto (diretto dal browser, CORS aperto)

javascript
// Klines storiche senza proxy:
const k = await (await fetch('https://api.binance.com/api/v3/klines?symbol=BTCUSDT&interval=1h&limit=120')).json();
// Tick live:
const ws = new WebSocket('wss://stream.binance.com:9443/ws/btcusdt@trade');
ws.onmessage = e => tick(+JSON.parse(e.data).p);

Account broker personale — READ-ONLY

L'utente salva le SUE API key (Binance / Alpaca paper / Alpaca live) sul suo account TorqueMind: le chiavi restano nel DB server, mai restituite. Gli endpoint di lettura firmano la richiesta e riportano posizioni/saldi — nessun ordine per design.
HTTP (Bearer JWT utente)
POST /api/market/broker/keys {service:"binance"|"alpaca"|"alpaca-live", apiKey, apiSecret, label?}
GET  /api/market/broker/keys → {keys:[{service,key:"abcd…xy"}]} (mascherata)
GET  /api/market/broker/account?service=binance|alpaca
    → alpaca: {equity,cash,buyingPower,pnlDay,positions:[{sym,qty,avg,price,pnl,pnlPct}]}
    → binance: {balances:[{asset,free,locked}]}
DELETE /api/market/broker/keys/:service
Ritardi & onestà — Yahoo è ritardato ~15 min su azioni (dillo sempre all'utente); Binance è live. Su dashboard trading il disclaimer "non consulenza finanziaria" è d'obbligo.

🔔 Messaging

Sistema di notifiche push e in-app. Invia notifiche a dispositivi registrati con Web Push (VAPID) o polling. Supporta topic per segmentare gli utenti.

Concetti chiave

📲

Subscription

I dispositivi si registrano con un endpoint push e i topic di interesse.

📤

Send

L'admin invia una notifica che viene salvata e pushata ai dispositivi.

🏷️

Topics

Segmenta le notifiche: all, updates, alerts, promo.

📡

Polling

Per mobile nativo, chiama /messaging/poll ogni 30s per ricevere le ultime notifiche.

Registrare un dispositivo

// Web Push — registra il service worker e invia la subscription
POST /messaging/subscribe
Authorization: Bearer <token>
{
  "subscription": { // PushSubscription dal browser
    "endpoint": "https://fcm.googleapis.com/...",
    "keys": { "auth": "...", "p256dh": "..." }
  },
  "topics": ["all", "updates"]
}

Polling (React Native / Mobile)

// Chiama ogni 30s per nuove notifiche
GET /messaging/poll?since=2025-01-01T00:00:00Z&topics=all,updates
Authorization: Bearer <token>

// Risposta
{
  "notifications": [
    { "id": "...", "title": "Update", "body": "Nuova versione!", "topic": "updates" }
  ]
}

Inviare notifica (Admin)

POST /messaging/send
Authorization: Bearer <admin-token>
{
  "title": "Aggiornamento v2.0",
  "body": "Nuove funzionalità disponibili!",
  "topic": "updates",
  "url": "https://tuodominio.com/changelog",
  "icon": "/favicon.ico"
}

// Risposta
{ "success": true, "push": { "sent": 12, "errors": 0 } }

SDK (esempio mobile)

// React Native — polling-based
const TorqueMind Messaging = {
  async poll(since, topics = ['all']) {
    const qs = `since=${since}&topics=${topics.join(',')}`;
    const res = await fetch(`${CLOUD_URL}/messaging/poll?${qs}`, {
      headers: { Authorization: `Bearer ${token}` }
    });
    return res.json();
  }
};

🔑 API Keys & AI Services

Sistema di chiavi API stile Firebase per accedere ai servizi AI di TorqueMind: LLM locale (Ollama), Vision, TTS, STT e Web Search. Ogni chiave ha permessi granulari per servizio, scadenza configurabile e tracking utilizzo.

Concetti chiave

🔑

API Key

Formato tc_live_ + 48 hex chars. Univoca per utente. Gestibile da dashboard, da /services/apikeys e dentro Retrace Pro (menu utente → 🔑 Chiavi API).

⚙

Servizi

Ogni chiave abilita servizi specifici: LLM, Vision, TTS, STT, Web Search, ImageGen, VideoGen, MediaDNA (analisi audio/video). Configurabili singolarmente.

⏰

Scadenza

Default: mai. Configurabile a 7, 30, 90, 365 giorni. Chiavi scadute rifiutate automaticamente.

📊

Tracking

Contatore utilizzi, ultimo uso, proprietario. Admin vede tutte le chiavi, utenti solo le proprie.

📈

Usage dettagliato

Per chiave: chiamate per servizio, token LLM consumati, piattaforme (app mobile, desktop, browser, script) e ultime 40 chiamate.

🌐

Pagina dedicata

/apikeys.html — genera chiavi e monitora l'utilizzo. In Retrace Pro desktop: Impostazioni → Chiavi API TorqueMind (stessa gestione, in-app). Nel gestionale: tab "API Keys" (superuser vede tutti gli utenti).

Autenticazione con API Key

http headers
// Metodo 1: Header x-api-key
x-api-key: tc_live_abc123def456...

// Metodo 2: Bearer token
Authorization: Bearer tc_live_abc123def456...

// Metodo 3: JWT utente (dalla dashboard)
Authorization: Bearer eyJhbGciOi...

Gestione chiavi (REST API)

// Genera nuova chiave (qualsiasi utente autenticato)
POST /api/keys/generate
Authorization: Bearer <token>
{
  "name": "La Mia App",
  "services": {              // opzionale, default: tutti abilitati
    "llm": true,
    "vision": true,
    "tts": false,
    "stt": false,
    "webSearch": true,
    "imageGen": true,       // /api/gen/image — ComfyUI + Qwen-Image-Edit
    "videoGen": false,      // /api/gen/video
    "videoHD": false,       // video qualita' alta (LTXV-13B)
    "gen3d": false,         // /api/gen/3d — TRELLIS.2 image/text→3D GLB
    "mediaDNA": true,       // /api/media/analyze — stems+Whisper+DNA
    "musicGen": false       // /api/media/track — SSE motore musicale
  },
  "expiresAt": null          // null = mai, oppure ISO date string
}

// Risposta
{
  "success": true,
  "apiKey": {
    "id": "uuid-xxx",
    "key": "tc_live_abc123def456...",  // mostrata UNA VOLTA sola
    "name": "La Mia App",
    "services": { ... },
    "enabled": true,
    "expiresAt": null
  }
}

Endpoint gestione chiavi

EndpointMetodoDescrizione
POST /api/keys/generatePOSTGenera nuova chiave (auth utente)
GET /api/keys/listGETLista chiavi (admin: tutte, user: proprie)
GET /api/keys/usage?days=30GETConsumi API SQLite: token input/output, richieste riuscite, servizi, piattaforme, chiavi e limiti del piano. JWT richiesto; utente: solo propri dati, admin: tutti gli utenti. Intervallo 1–120 giorni.
GET /api/keys/reveal/:idGETRivela chiave completa (owner/admin)
PUT /api/keys/update/:idPUTAggiorna nome, servizi, scadenza
PUT /api/keys/toggle/:idPUTAbilita/disabilita chiave
DELETE /api/keys/client/:idDELETEElimina chiave (owner/admin)

Consumi e limiti disponibili anche in Gestisci e nella pagina API Keys. Le chiamate pubbliche AI via JWT o API key condividono il piano del proprietario; quota esaurita o abbonamento scaduto restituiscono HTTP 429 prima di avviare il servizio. I contatori storici JSON delle chiavi non vengono retrodatati nel ledger SQLite. I token visualizzati sono quelli comunicati dal modello; STT/TTS non sono token LLM.

Campi uso tracciati per chiave

CampoContenuto
usageCountChiamate totali autenticate con la chiave
usageByServiceConteggi per servizio: {llm, vision, tts, stt, webSearch, imageGen, imagePro, videoGen, videoHD, gen3d, mediaDNA, musicGen, other}
platformsPiattaforme rilevate dallo User-Agent: mobile-app, desktop-app, browser, cli/script…
tokensUsedToken LLM consumati (prompt + eval, da Ollama)
recentUltime 40 chiamate: {at, service, platform, tokens}
lastUsedAtTimestamp ultima chiamata
Visibilità — l'utente registrato vede solo le proprie chiavi e il proprio uso. Il superuser (admin) vede tutte le chiavi, chi le possiede, quali piattaforme le usano e i token consumati.

Servizi AI disponibili

LLM Chat (testo)

POST /api/ai/chat
x-api-key: tc_live_xxx
{
  "messages": [
    { "role": "user", "content": "Cos'e un interruttore differenziale?" }
  ],
  "model": "qwen3:8b",           // opzionale, default: auto-fallback
  "temperature": 0.7,            // opzionale
  "maxTokens": 2048              // opzionale
}

// Modelli disponibili: llama3.1:8b (default), qwen2.5-coder:7b, qwen3:8b, deepseek-r1:8b
// Il sistema prova i modelli in sequenza fino a trovarne uno disponibile (fallback automatico)

Vision (analisi immagini)

POST /api/ai/vision
x-api-key: tc_live_xxx
{
  "image": "data:image/jpeg;base64,/9j/...",  // o URL http
  "prompt": "Descrivi questa immagine"       // opzionale
}

// Modello: minicpm-v (locale via Ollama)

Web Search Smart v4.0

Cache + DDG + SerpAPI La ricerca web usa un sistema a 3 livelli: 1) cache locale (7 giorni, istantanea) → 2) DuckDuckGo con rate-limit 5s → 3) SerpAPI fallback. Le query ripetute sono servite dalla cache a costo zero. Il campo source nella risposta indica quale livello ha servito la query.
GET /api/web-search?q=TorqueMind&max=8
x-api-key: tc_live_xxx

// Risposta
{
  "query": "TorqueMind",
  "results": [
    { "title": "...", "url": "https://...", "snippet": "..." }
  ],
  "count": 8,
  "source": "cache"    // "cache" | "ddg" | "serpapi" | "none"
}

// source: indica quale livello ha servito la query
//   "cache"   → risultato dalla cache locale (0ms, gratis)
//   "ddg"     → DuckDuckGo live (rate-limited 5s tra chiamate)
//   "serpapi" → SerpAPI fallback (quando DDG è bloccato)
//   "none"    → nessun risultato disponibile

Ricerca Immagini v4.0

Richiede SerpAPI — La ricerca immagini usa esclusivamente SerpAPI. Configura la chiave nel pannello admin Server.
GET /api/web-search?q=arduino+relay&type=images&max=6
x-api-key: tc_live_xxx

// Risposta
{
  "query": "arduino relay",
  "type": "images",
  "results": [
    {
      "title": "...",
      "url": "https://...full-image.jpg",
      "thumbnail": "https://...thumb.jpg",
      "source": "example.com",
      "width": 1200,
      "height": 800
    }
  ],
  "count": 6,
  "source": "serpapi"
}

Ricerca Video v4.0

GET /api/web-search?q=come+installare+differenziale&type=videos&max=6
x-api-key: tc_live_xxx

// Risposta
{
  "query": "come installare differenziale",
  "type": "videos",
  "results": [
    {
      "title": "...",
      "url": "https://youtube.com/...",
      "thumbnail": "https://...thumb.jpg",
      "duration": "12:34",
      "source": "youtube.com",
      "snippet": "..."
    }
  ],
  "count": 6,
  "source": "serpapi"
}
Parametro type Valori ammessi: web (default), images, videos. Se omesso, la ricerca è di tipo web. Immagini e video sono serviti solo tramite SerpAPI e cachati per 7 giorni come le ricerche web.

Estrazione Documenti v4.0

Formati supportati: PDF, DOCX, XLSX, PPTX, CSV, TXT, JSON, XML, HTML. Per immagini → usa Vision. Per ZIP/APK/binari → download con metadati archivio.
GET /api/extract?url=https://example.com/manual.pdf&chunk_size=3000&chunk=0
x-api-key: tc_live_xxx

// Risposta
{
  "url": "https://example.com/manual.pdf",
  "fileType": "pdf",
  "filename": "manual.pdf",
  "size": 2456789,
  "extractable": true,
  "totalChunks": 12,
  "totalLength": 35420,
  "chunks": ["...testo chunk 0...", "...chunk 1..."],
  "hasMore": true,         // usa ?chunk=N per i successivi
  "pages": 24,
  "info": { "Title": "...", "Author": "..." }
}

Download File v4.0

GET /api/download?url=https://example.com/firmware.zip
x-api-key: tc_live_xxx

// Risposta
{
  "success": true,
  "filename": "firmware.zip",
  "fileType": "zip",
  "size": 15000000,
  "downloadUrl": "/api/download/file/dl_17...",
  "archiveContents": [
    { "name": "readme.txt", "size": 1024 },
    { "name": "firmware.bin", "size": 14000000 }
  ]
}

Deep Search (Ricerca + Analisi) v4.0

Pipeline completa: Cerca sul web → scarica le fonti → estrae il contenuto (anche da PDF e documenti) → invia tutto al LLM per un'analisi mirata con citazioni dalle fonti. Timeout 4 minuti per analisi complesse. Fallback automatico se modello richiesto fallisce.
POST /api/web-search/deep
x-api-key: tc_live_xxx
{
  "query": "manuale inverter ABB ACS580",
  "maxSources": 3,       // max 5 fonti
  "model": "qwen3:8b"    // opzionale, usa default
}

// Risposta
{
  "query": "manuale inverter ABB ACS580",
  "answer": "Dall'analisi delle fonti trovate...",
  "model": "qwen3:8b",
  "sources": [{ "title": "...", "url": "..." }],
  "extractedContent": [{
    "url": "...", "fileType": "pdf",
    "pages": 120,
    "textPreview": "...primi 500 caratteri..."
  }],
  "sourcesCount": 3
}

Stato servizi

GET /api/ai/status

// Risposta
{
  "ollama": { "available": true, "models": [...] },
  "strategy": "local-only",
  "textModels": ["llama3.1:8b", "qwen2.5-coder:7b", "qwen3:8b", "deepseek-r1:8b"],
  "defaultModel": "llama3.1:8b",  // configurabile da admin
  "visionModel": "minicpm-v",
  "apiKeys": { "total": 5, "active": 4 }
}

Esempio completo: integrazione in app

javascript
const API_KEY = 'tc_live_abc123def456...';
const BASE_URL = 'https://torquemind.org';

// Chat con LLM locale
async function askAI(question) {
  const res = await fetch(`${BASE_URL}/api/ai/chat`, {
    method: 'POST',
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      messages: [{ role: 'user', content: question }]
    })
  });
  const data = await res.json();
  return data.message.content;
}

// Ricerca web
async function webSearch(query) {
  const res = await fetch(
    `${BASE_URL}/api/web-search?q=${encodeURIComponent(query)}`,
    { headers: { 'x-api-key': API_KEY } }
  );
  return (await res.json()).results;
}
Servizi TTS e STT I servizi Text-to-Speech e Speech-to-Text sono predisposti nel sistema di permessi delle chiavi API. Quando saranno attivati, basterà abilitarli sulla chiave esistente senza generarne una nuova.
Sicurezza La chiave API viene mostrata una sola volta al momento della generazione. Copiala subito. Non condividere mai le chiavi in repository pubblici. Usa variabili d'ambiente nelle tue app.

Parametri configurabili

// /api/ai/chat accetta:
{ "messages": [{ "role": "user", "content": "…" }],
  "model": "",                    // vuoto = default
  "systemInstruction": "…",  // prompt di sistema custom
  "temperature": 0.7,          // 0 = deterministico, 0.7 = conversazionale
  "maxTokens": 2048,
  "format": "json" }            // opzionale: forza output JSON

// Vision: /api/ai/vision  { image: base64, prompt, provider }
// Video:  /api/ai/vision/video  { video: base64, prompt, provider }
// RAG:    /api/ai/rag-pdf { pdf_url, domanda, systemInstruction }
// Deep:   /api/web-search/deep { query, maxSources, model }
// Estrazione documenti: GET /api/extract?url=&chunk_size=&chunk=

📡 WebRTC

TorqueMind fornisce credenziali ICE temporanee (STUN/TURN, RFC 5389) per le tue app WebRTC: videochiamate, screen sharing e peer-to-peer anche attraverso NAT e firewall aziendali.
Come funziona
STUN = dice al client il suo IP pubblico (leggero, veloce).
TURN = fa da relay quando la connessione diretta P2P fallisce (NAT simmetrici, firewall). Più pesante ma essenziale per affidabilità.

Ottenere credenziali ICE (Client)

Ogni client autenticato (JWT o API Key) richiede credenziali temporanee per la connessione WebRTC:

POST /api/webrtc/credentials
// Richiesta
POST /api/webrtc/credentials
Authorization: Bearer <token> | X-API-Key: <api_key>

// Risposta
{
  "iceServers": [
    { "urls": ["stun:torquemind.org:3478"] },
    {
      "urls": [
        "turn:torquemind.org:3478?transport=udp",
        "turn:torquemind.org:3478?transport=tcp"
      ],
      "username": "1713398400:[email protected]",
      "credential": "base64_hmac_password"
    }
  ],
  "ttl": 86400
}

Uso nel frontend (React Native / Web)

JavaScript — WebRTC con credenziali TorqueMind
// 1. Ottieni credenziali dal server
const res = await fetch('https://torquemind.org/api/webrtc/credentials', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer ' + token }
});
const { iceServers } = await res.json();

// 2. Crea connessione WebRTC con le credenziali
const pc = new RTCPeerConnection({ iceServers });

// 3. Usa normalmente (addTrack, createOffer, etc.)
const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
stream.getTracks().forEach(track => pc.addTrack(track, stream));

Endpoint

MetodoEndpointDescrizione
POST/api/webrtc/credentialsGenera credenziali ICE temporanee (auth richiesta)
GET/api/webrtc/statusStato del servizio (auth richiesta)
Sicurezza
Le credenziali TURN sono temporanee (HMAC, con scadenza). Ogni utente riceve credenziali uniche che non possono essere riutilizzate dopo la scadenza.

📍 Geo Services

Geocoding, reverse geocoding, distanze, percorsi con tempo/carburante e navigazione turn-by-turn. Usa Nominatim (OpenStreetMap) e OSRM — nessuna API key esterna richiesta.

Endpoint API

MetodoEndpointDescrizione
GET/api/geo/geocode?q=&limit=Indirizzo → coordinate (lat/lng)
GET/api/geo/reverse?lat=&lng=Coordinate → indirizzo completo
GET/api/geo/distance?lat1=&lng1=&lat2=&lng2=Distanza tra 2 punti
GET/api/geo/route?lat1=&lng1=&lat2=&lng2=Percorso stradale: tempo, km, stima carburante
GET/api/geo/navigate?lat1=&lng1=&lat2=&lng2=&destName=Navigazione turn-by-turn con indicazioni stradali + geometria GeoJSON
GET/api/geo/timezone?lat=&lng=Fuso orario da coordinate

Navigazione Turn-by-Turn

L'endpoint /api/geo/navigate restituisce indicazioni stradali passo-passo con icone manovra, GeoJSON per disegnare il percorso su mappa, stima carburante e tempo.
Esempio risposta /api/geo/navigate
{
  "destination": "Via Roma",
  "distance": { "km": 12.3, "text": "12.3km" },
  "duration": { "minutes": 18, "text": "18 min" },
  "fuelEstimate": { "liters": 1.0, "costEur": 1.85 },
  "steps": [
    { "step": 1, "icon": "🚗", "instruction": "Parti su Via Napoli", "distance": { "text": "200m" } },
    { "step": 2, "icon": "➡️", "instruction": "right su SS18", "distance": { "text": "5.2km" } },
    { "step": 3, "icon": "🏁", "instruction": "Arrivo a Via Roma", "distance": { "text": "50m" } }
  ],
  "geometry": { "type": "LineString", "coordinates": [[14.23, 40.83], ...] }
}
Nella tua app
Chiama /api/geo/navigate, ricevi gli step, e puoi mostrare:
1. Lista indicazioni come Google Maps (icone manovra + strada + distanza)
2. Mappa con polyline usando la geometry GeoJSON (Leaflet/MapLibre)
3. Aggiornamento live: ricalcola ogni N secondi con nuova posizione GPS
Il server fornisce i dati — il frontend renderizza la UI navigatore.
Fair use
Le API geo usano servizi pubblici con rate limit. Per uso intensivo implementa una cache lato client.

🆚 TorqueMind vs Google Firebase

Confronto funzionalità per funzionalità. TorqueMind è 100% self-hosted e gratuito.
FunzionalitàGoogle FirebaseTorqueMindStato
AuthenticationFirebase Auth (OAuth, email, phone)JWT Auth (email, password, verifica email, reset)✅ Parità
Firestore DatabaseCloud Firestore (NoSQL, realtime)SQLite Firestore-like (CRUD, SSE realtime)✅ Parità
StorageCloud Storage (GCS buckets)File Storage (upload, download, list, quota)✅ Parità
Cloud FunctionsCloud Functions (Node.js, Python)Cloud Functions (JS sandbox, HTTP trigger)✅ Parità
HostingFirebase Hosting (CDN global)Self-hosted (Caddy + sites)✅ Parità
Push NotificationsFirebase Cloud Messaging (FCM)Web Push (VAPID) + Mobile polling✅ Parità
Security RulesFirestore Security RulesCustom Security Rules per collection✅ Parità
AI/MLVertex AI, ML KitLLM locale (Ollama), Gemini, Vision, Video AI, RAG PDF, Deep Search✅ Superiore
GeocodingGoogle Maps Geocoding API ($$$)Nominatim (OpenStreetMap, GRATIS)✅ Parità
Directions/NavigationGoogle Maps Directions API ($$$)OSRM turn-by-turn (GRATIS)✅ Parità
WebRTC TURN/STUNNon inclusoCredenziali ICE temporanee via API✅ Esclusivo
Web SearchNon disponibileDuckDuckGo scraper + Deep Search AI✅ Esclusivo
AnalyticsGoogle Analytics (completo)Stats base (utenti, storage, funzioni)⚠️ Base
Remote ConfigFirebase Remote Configserver-config endpoint⚠️ Base
CrashlyticsFirebase CrashlyticsNon disponibile❌ Manca
A/B TestingFirebase A/B TestingNon disponibile❌ Manca
Dynamic LinksFirebase Dynamic Links (deprecato)Non necessario➖ N/A
Costo$0.06/100K reads, $0.18/100K writes, Maps APIs $$$€0 — GRATIS per sempre✅ Imbattibile
Risultato
TorqueMind offre tutto ciò che serve per app web e mobili. Le funzionalità mancanti (Crashlytics, A/B Testing) sono di nicchia e non bloccanti. Con AI integrata e Geo services gratuiti, TorqueMind è un'alternativa self-hosted a Firebase.

👤 User Console API

Ogni utente registrato ha la propria console dove gestisce Firestore, Storage e Hosting isolati per account. I dati sono completamente separati da quelli degli altri utenti e da quelli globali del server.

Come funziona l'isolamento

ServizioNamespaceEsempio
Firestoreu_<uid>_<collection>Utente crea "prodotti" → salvato come u_abc123_prodotti
StorageBucket user_<uid>File caricati in user_abc123
HostingCampo owner = uidL'utente vede solo i siti dove owner = il suo ID

Endpoint User Console

── USER FIRESTORE ────────────────────────────────────
GET    /user/firestore                    lista collection utente
GET    /user/firestore/:col               documenti in collection
POST   /user/firestore/:col/:docId?       crea/aggiorna documento
PUT    /user/firestore/:col/:docId        aggiorna documento
DELETE /user/firestore/:col/:docId        elimina documento
DELETE /user/firestore/:col               elimina collection

── USER STORAGE ──────────────────────────────────────
GET    /user/storage                      lista file + stats
POST   /user/storage/upload               upload file (multipart)
GET    /user/storage/file/:path           download file
DELETE /user/storage/file/:path           elimina file

── USER HOSTING ──────────────────────────────────────
GET    /user/hosting                      lista siti utente
POST   /user/hosting                      crea sito
POST   /user/hosting/:id/deploy-zip       deploy ZIP
DELETE /user/hosting/:id                  elimina sito

── USER STATS ────────────────────────────────────────
GET    /user/stats                        statistiche utente
GET    /user/notifications                notifiche utente

Esempio: creare una collection e aggiungere un documento

// 1. Crea collection aggiungendo il primo doc
const res = await fetch('/user/firestore/prodotti', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ nome: 'Widget', prezzo: 9.99 })
});
// Documento salvato in u_<tuo-uid>_prodotti

// 2. Lista tutti i tuoi documenti
const docs = await (await fetch('/user/firestore/prodotti', {
  headers: { Authorization: `Bearer ${token}` }
})).json();
Dashboard utente Vai a /dashboard.html per la console grafica completa con sidebar, CRUD Firestore, upload Storage, deploy Hosting e gestione profilo. Funziona identicamente alla Admin Console ma con dati isolati per il tuo account.

🛡️ Security Rules

Regole JSON stile Firebase per proteggere Firestore e Storage. Definisci chi può leggere/scrivere/eliminare ogni risorsa.

Struttura regole Firestore

json — admin → security rules → firestore
{
  "rules": {
    "collections": {
      "utenti": {
        "read":   "auth",        // solo utenti autenticati
        "write":  "owner",       // solo il proprietario del doc
        "delete": "admin"        // solo admin
      },
      "prodotti": {
        "read":   "public",      // chiunque
        "write":  "admin",
        "delete": "admin"
      },
      "feed_pubblico": {
        "read":   "public",
        "write":  "public"       // accessibile a chiunque (es. feed pubblico)
      }
    },
    "default": {
      "read":  "auth",
      "write": "admin"
    }
  }
}

Valori permission

ValoreChi può accedere
publicChiunque, anche senza token
authQualsiasi utente autenticato con token valido
ownerSolo l'utente il cui UID corrisponde al campo userId del documento
adminSolo utenti con ruolo admin
false / denyNessuno (accesso negato)

Regole utente (per-user rules)

Ogni utente puo definire le proprie regole di sicurezza per le collezioni e lo storage nel proprio namespace. Le regole utente si applicano solo ai dati isolati (u_<uid>_*).
rest api — user rules
// Leggi le tue regole
GET /user/rules
Authorization: Bearer <token>

// Aggiorna regole Firestore
PUT /user/rules/firestore
Authorization: Bearer <token>
{ "rules": "{ \"rules\": { \"*\": { \".read\": \"auth != null\", \".write\": \"auth != null\" } } }" }

// Aggiorna regole Storage
PUT /user/rules/storage
Authorization: Bearer <token>
{ "rules": "{ \"rules\": { \"*\": { \".read\": true, \".write\": \"auth != null\" } } }" }
Dashboard utente Nella sezione Security Rules della dashboard utente puoi modificare graficamente le regole Firestore e Storage con un editor di testo e salvarle con un click.

📱 Registrazione App Android

Registra le tue app Android per collegare i servizi TorqueMind. Inserisci il package name e opzionalmente la SHA-256 del certificato di firma. Puoi associare un'API Key per accedere ai servizi AI dall'app.

Concetti chiave

📦

Package Name

Identificativo univoco dell'app (es. com.example.myapp). Deve essere unico per utente.

🔑

SHA-256

Fingerprint del certificato di firma (opzionale). Serve per verificare l'identita dell'app.

🔗

API Key

Associa un'API key per abilitare i servizi AI (LLM, Vision, Web Search) dall'app.

⚙

Dashboard

Gestisci le tue app dalla sezione "App Android" nella console utente.

Registrare un'app (REST API)

// Registra una nuova app Android
POST /user/apps/android
Authorization: Bearer <token>
{
  "appName": "La Mia App",
  "packageName": "com.example.myapp",
  "sha256": "AA:BB:CC:DD:..."   // opzionale
}

// Risposta
{
  "success": true,
  "app": {
    "id": "uuid-xxx",
    "packageName": "com.example.myapp",
    "appName": "La Mia App",
    "sha256": "AA:BB:CC:DD:...",
    "platform": "android",
    "apiKeyId": null
  }
}

Endpoint App Android

EndpointMetodoDescrizione
POST /user/apps/androidPOSTRegistra nuova app (auth utente)
GET /user/appsGETLista app dell'utente
PUT /user/apps/:idPUTAggiorna nome, SHA-256 o API key associata
DELETE /user/apps/:idDELETEElimina app registrata

Ottenere la SHA-256

bash — terminale Android Studio
# Debug key
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android

# Release key
keytool -list -v -keystore <percorso-keystore> -alias <alias>

# Cerca la riga: SHA256: AA:BB:CC:DD:EE:FF:...

Integrazione nell'app Android

kotlin — TorqueMindService.kt
object TorqueMind {
    private const val BASE_URL = "https://torquemind.org"
    private const val API_KEY  = "tc_live_xxx..."

    suspend fun chat(prompt: String): String {
        val client = OkHttpClient()
        val json = """{"messages":[{"role":"user","content":"$prompt"}]}"""
        val body = json.toRequestBody("application/json".toMediaType())
        val request = Request.Builder()
            .url("$BASE_URL/api/ai/chat")
            .addHeader("x-api-key", API_KEY)
            .post(body).build()
        return client.newCall(request).execute().body!!.string()
    }
}
Indirizzo HTTPS L'indirizzo pubblico di TorqueMind è: https://torquemind.org
Le API sono accessibili a: https://torquemind.org/api/ai/chat, /api/web-search, ecc.

🔄 TorqueConvert — Convertitore Multiformato NEW

Conversione audio e video online, gratis fino a 100 MB: MP3, WAV, FLAC, AIFF, M4A, MP4. Elaborazione server-side TorqueMind — niente attese locali, le conversioni continuano anche se chiudi la pagina e le ritrovi pronte.

Pagina: /services/convert (alias: /services/converter). Richiede solo l'account TorqueMind — nessuna registrazione extra.

Come funziona

  • Carichi il file, scegli il formato di destinazione, la conversione gira sul server.
  • Job persistente: se vai via e torni, trovi il risultato pronto — come Studio IA.
  • Formati coperti: audio MP3/WAV/FLAC/AIFF/M4A, video MP4 — estrazione audio da video inclusa.

📺 TorqueVideos — Video di Artisti Emergenti e IA NEW

La piattaforma video TorqueMind per produzioni indipendenti, casalinghe e generate con IA. Carica, guarda, scarica — i creator al centro. Player dedicato con coda di riproduzione, scorciatoie da tastiera e anteprima del prossimo video.

Pagine: /services/tube (alias: /services/mtube, /services/torquetube).

Player

  • Seek rapido: ⏪/⏩ ±10s, timeline con anteprima, coda dei prossimi video.
  • ⏮ torna all'inizio della coda, ⏭ salta al video successivo.
  • Upload riservato ai creator: pubblichi i tuoi video e restano nel tuo canale.

🎛️ TrackForge — DAW Online con IA NEW

Studio audio completo nel browser: editing multitraccia su timeline, separazione stem (demucs), analisi musicale IA, e voice conversion — scrivi il testo e cantalo con la tua voce clonata. La DAW gratuita online di TorqueMind.

Pagina: /services/musicstudio (alias: /services/musiclab, /services/studio, /services/daw). Servizio chiave API: musicStudio.

Cosa puoi fare

  • Editing multitraccia: timeline, tagli, mix per-traccia, export del progetto.
  • Separazione stem: split di una traccia in 4 stem (voce/batteria/basso/altro) via demucs.
  • Analisi musicale IA: bpm, tonalita', struttura — direttamente sulla traccia.
  • Voice conversion: sostituisci la voce di una traccia con un profilo voce (vedi Voice Cloning).

🎵 SongForge — Generazione Musica IA NEW

Genera canzoni complete con l'IA: musica, testi e voce — anche con la tua voce clonata (profili Voice Cloning). Motore neurale su GPU locale, nessun limite creativo. Le tracce generate si aprono in TrackForge per l'editing.

Pagina: /services/musicgen. Servizio chiave API: musicGen. Per generare via API vedi la sezione Generazione Media.

Funzioni

  • Brano completo da prompt: strumentale o con testo e voce cantata.
  • Voce clonata: canta il testo con un profilo voce dell'utente.
  • Stem delle tracce generate visibili nel player; export verso TrackForge.
  • Editing delle tracce esistenti (riarrangiamento, estensione, cambio stile).

📚 SDK Web — Riferimento completo

Tutti i metodi esposti dall'SDK JavaScript browser/Node (/sdk/trubaxcloud.js).

initializeApp(config)

const app = TorqueMind.initializeApp({
  url: 'https://torquemind.org'  // URL del servizio TorqueMind
});
// app.auth — servizio autenticazione
// app.db   — servizio database
// app.storage — servizio storage
// app.functions — servizio cloud functions

📱 SDK React Native

Per React Native usa il modulo src/services/torquemind.ts con la stessa API dell'SDK web.
typescript — src/services/torquemind.ts
const CLOUD_URL = 'https://torquemind.org';

export const TorqueMind Functions = {
  async call(functionId: string, data: Record<string, unknown>) {
    const res = await fetch(`${CLOUD_URL}/fn/${functionId}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });
    return res.json();
  }
};

🔌 REST API — Riferimento

Puoi usare TorqueMind senza SDK, chiamando direttamente gli endpoint HTTP.
── AUTH ────────────────────────────────────────────────
POST   /auth/register          { email, password, displayName? }
POST   /auth/login             { email, password }
POST   /auth/logout            Bearer token
GET    /auth/me                Bearer token
PUT    /auth/me                Bearer token + { displayName }
DELETE /auth/me                Bearer token + { password } elimina account
PUT    /auth/password          { currentPassword, newPassword }
POST   /auth/me/avatar         multipart upload foto profilo (max 5MB)
GET    /auth/avatar/:id        scarica avatar utente (pubblico, cached 1h)
DELETE /auth/me/avatar         rimuovi foto profilo
POST   /auth/verify            { token, appSecret? } → user info + avatar (per SDK)
POST   /auth/sdk/user          { appSecret, userId } → dati utente per app SDK
POST   /auth/send-verification  invia email di verifica (auth)
POST   /auth/verify-email       { token } — verifica email
GET    /auth/verify-email       ?token= — verifica via link email
POST   /auth/reset-password     { token, newPassword } — reset con token email

── FIRESTORE ────────────────────────────────────────────
GET    /db/:collection                ?limit=&orderBy=&where=[]
GET    /db/:collection/:docId
PUT    /db/:collection/:docId         body = documento JSON
DELETE /db/:collection/:docId
POST   /db/_batch                     { ops: [{type,collection,id,data}] }
GET    /db/:collection/_listen        SSE stream

── STORAGE ──────────────────────────────────────────────
POST   /storage/:bucket/:path         { data: base64, contentType }
GET    /storage/:bucket/:path         → file binario
DELETE /storage/:bucket/:path
GET    /storage-meta/:bucket          ?prefix=

── CLOUD FUNCTIONS ──────────────────────────────────────
ALL    /fn/:id                        chiamata pubblica HTTP
// Gestione funzioni: dalla tua Console → Cloud Functions

── HOSTING ──────────────────────────────────────────────
GET    /sites/:slug/                  sito live (pubblico)
// Gestione siti utente: vedi sezione USER CONSOLE sotto

── MESSAGING ────────────────────────────────────────────
POST   /messaging/subscribe           registra dispositivo push
GET    /messaging/poll                ?since=&topics=  (polling)
GET    /messaging/vapid-public-key   chiave pubblica VAPID
POST   /messaging/unsubscribe       rimuovi dispositivo
POST   /messaging/read/:id          segna notifica come letta

── API KEYS ─────────────────────────────────────────────
POST   /api/keys/generate         genera chiave (auth utente)
GET    /api/keys/list             lista chiavi (admin: tutte, user: proprie)
GET    /api/keys/reveal/:id       rivela chiave completa (owner/admin)
PUT    /api/keys/update/:id       aggiorna nome, servizi, scadenza
PUT    /api/keys/toggle/:id       abilita/disabilita chiave
DELETE /api/keys/client/:id       elimina chiave (owner/admin)

── AI SERVICES (richiede API Key o JWT) ──────────────────
POST   /api/ai/chat               LLM chat (fallback automatico)
POST   /api/ai/vision             Vision (analisi immagini)
POST   /api/ai/vision/video       Video AI (max 60s)
POST   /api/ai/rag-pdf            RAG PDF (domanda su documento PDF)
GET    /api/ai/status             stato modelli + defaultModel
GET    /api/web-search?q=&max=&type=  ricerca web/images/videos
GET    /api/web-scrape?url=       scraping contenuto HTML pagina

── DOCUMENT EXTRACTION ───────────────────────────────────
GET    /api/extract?url=&chunk_size=&chunk=  estrai testo (PDF/DOCX/XLSX/PPTX/CSV/TXT/HTML)
POST   /api/web-search/deep       { query, maxSources, type, model } ricerca+estrai+analisi LLM

── WEBRTC ────────────────────────────────────────────────
POST   /api/webrtc/credentials    credenziali ICE per WebRTC
GET    /api/webrtc/status         stato servizio

── GEO SERVICES (geocoding, routing, navigazione) ──────────
GET    /api/geo/geocode?q=&limit=  geocoding indirizzo
GET    /api/geo/reverse?lat=&lng=  reverse geocoding
GET    /api/geo/route?lat1=&lng1=&lat2=&lng2=  percorso stradale
GET    /api/geo/navigate?lat1=&lng1=&lat2=&lng2=&destName=  navigazione turn-by-turn

── USER CONSOLE (scoped per utente) ──────────────────────
GET    /user/firestore                lista collection utente
GET    /user/firestore/:col           documenti collection
POST   /user/firestore/:col/:docId?  crea documento
PUT    /user/firestore/:col/:docId   aggiorna documento
DELETE /user/firestore/:col/:docId   elimina documento
DELETE /user/firestore/:col           elimina collection
GET    /user/storage                  lista file utente
POST   /user/storage/upload           upload file (multipart)
GET    /user/storage/file/:path       download file
DELETE /user/storage/file/:path       elimina file
GET    /user/hosting                  lista siti utente
POST   /user/hosting                  crea sito
POST   /user/hosting/:id/deploy-zip   deploy ZIP
DELETE /user/hosting/:id              elimina sito
GET    /user/stats                    statistiche utente
GET    /user/notifications            notifiche utente

── USER SECURITY RULES ──────────────────────────────────
GET    /user/rules                    leggi regole utente
PUT    /user/rules/firestore          aggiorna regole Firestore
PUT    /user/rules/storage            aggiorna regole Storage

── APP ANDROID ──────────────────────────────────────────
POST   /user/apps/android             registra app Android
GET    /user/apps                     lista app utente
PUT    /user/apps/:id                 aggiorna app
DELETE /user/apps/:id                 elimina app

📷 Profilo & Avatar v10.1

Ogni utente può impostare una foto profilo (avatar) che viene automaticamente distribuita a tutte le app che usano TorqueMind come provider di autenticazione, esattamente come Google e i suoi servizi.

Come funziona

L'utente carica un'immagine (JPG, PNG, GIF, WebP, max 5MB) tramite la console o via API. L'immagine è servita pubblicamente a /auth/avatar/{userId}. Quando uno sviluppatore integra l'accesso via TorqueMind, il campo user.avatar viene incluso automaticamente in POST /auth/verify e POST /auth/sdk/user.

Endpoints API

MetodoEndpointDescrizione
POST /auth/me/avatarmultipart avatarUpload foto profilo (max 5MB, JPG/PNG/GIF/WebP)
GET /auth/avatar/:idpublicScarica avatar utente (cacheable 1h, SVG default se assente)
DELETE /auth/me/avatarauthRimuovi foto profilo
PUT /auth/meauth { displayName }Aggiorna nome visualizzato
DELETE /auth/meauth { password }Elimina il proprio account (irreversibile)

Esempio: Upload avatar da frontend

javascript
const formData = new FormData();
formData.append('avatar', fileInput.files[0]);

const res = await fetch('/auth/me/avatar', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer ' + token },
  body: formData
});
const data = await res.json();
// data.avatarUrl → "/auth/avatar/abc123"

Integrazione SDK — Avatar nelle tue app

javascript
// Quando un utente accede alla tua app tramite TorqueMind:
const res = await fetch('https://tuoserver.com/auth/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ token: userToken })
});
const { user } = await res.json();

// user.avatar → "/auth/avatar/abc123" (URL pubblica)
// user.displayName → "Mario Rossi"
// user.email → "[email protected]"

// Mostra avatar nell'app:
document.getElementById('userAvatar').src = serverUrl + user.avatar;

Eliminazione account (self-service)

⚠️ Azione irreversibile L'utente può eliminare il proprio account confermando la password. Vengono eliminati: dati utente, sessioni, avatar e tutte le app registrate. L'endpoint è DELETE /auth/me con body { "password": "..." }.

🔔 Push Notifications v10.0

TorqueMind supporta Web Push (VAPID) per notifiche in tempo reale nel browser e polling per app mobili. Le notifiche sono gestite tramite topic e hanno storico persistente.

Architettura

🌐

Web Push

Service Worker + VAPID. Funziona anche con browser chiuso. Richiede HTTPS.

📱

Mobile Polling

GET /messaging/poll per ricevere notifiche pendenti. Ideale per app React Native.

📋

Storico

Ultime 200 notifiche salvate. Mark-as-read per utente. Topic filtering.

🔑

VAPID

Chiavi generate automaticamente al primo avvio. Nessuna configurazione richiesta.

Endpoints

MetodoEndpointDescrizione
GET /messaging/vapid-public-keypublicOttieni VAPID public key per subscription
POST /messaging/subscribeauth { subscription, topics }Iscriviti a push notifications
POST /messaging/unsubscribeauth { endpoint }Disiscriviti
GET /messaging/pollauthRicevi notifiche pendenti (mobile SDK)
POST /messaging/read/:idauthSegna notifica come letta
POST /messaging/sendadmin { title, body, topic }Invia notifica (admin)

Esempio: Service Worker per Push

javascript — sw-push.js
// File statico servito dal server
self.addEventListener('push', function(e) {
  var d = { title: 'TorqueMind', body: 'Nuova notifica' };
  try { d = Object.assign(d, e.data.json()); } catch(x) {}
  e.waitUntil(self.registration.showNotification(d.title, {
    body: d.body, icon: d.icon || '/favicon.ico'
  }));
});

self.addEventListener('notificationclick', function(e) {
  e.notification.close();
  e.waitUntil(clients.openWindow(e.notification.data?.url || '/'));
});

Esempio: Subscribe da frontend

javascript
// 1. Registra service worker
const reg = await navigator.serviceWorker.register('sw-push.js');
await navigator.serviceWorker.ready;

// 2. Ottieni VAPID key
const vapid = await fetch('/messaging/vapid-public-key').then(r => r.json());

// 3. Subscribe
const sub = await reg.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: urlBase64ToUint8Array(vapid.publicKey)
});

// 4. Invia subscription al server
await fetch('/messaging/subscribe', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
  body: JSON.stringify({ subscription: sub.toJSON(), topics: ['all'] })
});
💡 Nota per HTTPS Le Web Push Notifications funzionano solo su HTTPS. In locale con localhost funzionano senza certificato. Per produzione, usa Caddy o Cloudflare Tunnel per HTTPS automatico. Il service worker deve essere registrato da un file statico (sw-push.js), NON da un blob URL.

⚠️ Codici di errore

StatusErroreCausa
401Token non validoToken scaduto o mancante nell'header
403Accesso negatoRuolo insufficiente o regola di sicurezza
404Non trovatoDocumento, sito o funzione non esistente
400Richiesta non validaCampi mancanti o formato errato
500Errore serverEccezione interna, vedi log server
502API esterna fallitaEs. Gemini API error (vedi error.message)

📁 TorqueMind Drive

File manager stile Google Drive. Upload, download, organizzazione file con 2GB per utente.

Quota Storage

  • 2GB per utente (file Drive)
  • Le immagini delle chat sono escluse dal limite Drive
  • Upload max 50MB per file

API Endpoints

GET  /user/storage?type=drive     // Lista file (escludi chat-images)
POST /user/storage/upload          // Upload file (multipart)
GET  /user/storage/file/:path      // Download file
DELETE /user/storage/file/:path    // Elimina file

// Query params
?type=drive   → solo file Drive
?type=chat    → solo chat-images
?token=JWT    → auth via URL (per img tag)

✉️ TorqueMind Mail

Client email interno. Invia/ricevi tra utenti TorqueMind + SMTP esterno.

Funzionalità

  • Inbox, Sent, Drafts, Trash
  • Invio interno tra utenti TorqueMind
  • Invio esterno via SMTP (se configurato)
  • Starred, Read/Unread

API Endpoints

GET   /user/mail/:box              // box = inbox|sent|drafts|trash
POST  /user/mail/send              // { to, subject, body, html }
PATCH /user/mail/:box/:id          // { read, starred, _delete }

// Response GET
{ "mails": [...], "total": 42 }

// Response POST send
{ "success": true, "mail": {...}, "smtpSent": true|false }
⚠️ SMTP Config Per inviare email esterne, configura SMTP in Admin Console → Email Config.

🗺️ TorqueMind Maps

Mappe e navigazione. Leaflet + OpenStreetMap + OSRM routing. Nessuna dipendenza Google.

Funzionalità

  • Ricerca luoghi (Nominatim geocoding)
  • Calcolo percorsi (OSRM routing)
  • Geolocalizzazione browser
  • Layer dark/light

API Esterne Usate

// Geocoding
https://nominatim.openstreetmap.org/search?q=...

// Routing
https://router.project-osrm.org/route/v1/driving/{lon1},{lat1};{lon2},{lat2}

🤖 TorqueMind IA Chat

Chat IA locale. LLaMA, Qwen, DeepSeek via Ollama. Zero tracking, dati on-premise.

API Endpoint

POST /api/ai/chat
Authorization: Bearer {token}
Content-Type: application/json

{
  "messages": [{ "role": "user", "content": "Ciao" }],
  "model": "llama3.1:8b",
  "temperature": 0.7,
  "maxTokens": 2000
}

// Response
{ "response": "Ciao! Come posso aiutarti?" }

Modelli Disponibili

GET /api/ai/status   // Lista modelli installati

// Response
{ "textModels": ["llama3.1:8b", "qwen2.5:7b", ...] }

🌐 TorqueMind Translate

Traduttore IA. 12 lingue, traduzione contestuale via LLM locale.

Lingue Supportate

Italiano, English, Français, Español, Deutsch, Português, Русский, 中文, 日本語, العربية, 한국어 + rilevamento automatico.

Implementazione

Usa /api/ai/chat con prompt di traduzione. Cronologia salvata in localStorage.

📸 TorqueMind Photos

Galleria foto dal Drive. Lightbox, upload, navigazione tastiera.

Funzionalità

  • Griglia responsive
  • Lightbox con navigazione ←→
  • Upload multiplo in photos/
  • Filtra automaticamente immagini dal Drive

📝 TorqueMind Notes

Note veloci stile Google Keep. Colori, ricerca, salvataggio locale.

Storage

Le note sono salvate in localStorage (chiave: trubax_notes). Non richiede autenticazione.

🧅 TorqueMind Tor

Browser .onion via proxy Tor server-side. Navigazione anonima.

API Endpoints

// Proxy Tor (supporta .onion)
GET /api/tor-proxy?url=http://example.onion

// Check IP
GET /api/ip-check
{ "clientIp": "1.2.3.4", "serverIp": "5.6.7.8" }
⚠️ Privacy Il traffico passa attraverso il server TorqueMind → Tor. Il server può vedere le richieste. Per anonimato completo usa Tor Browser nativo.

🎤 STT/TTS Server-Side

Speech-to-Text e Text-to-Speech server-side per compatibilità iOS Safari.

⚠️ Nota iOS Safari iOS non supporta Web Speech API per STT — per questo la voce passa interamente dal server: il client registra l'audio, lo manda a /api/stt e riproduce l'audio WAV restituito da /api/tts. Funziona così su iOS, Android e desktop senza Web Speech né WebRTC.

Soluzione: API Server-Side

// STT - Speech to Text (upload audio, get text)
POST /api/stt
Content-Type: multipart/form-data
file: audio.webm

{ "text": "Testo riconosciuto", "confidence": 0.95 }

// TTS - Text to Speech (get audio)
POST /api/tts
{ "text": "Ciao mondo", "lang": "it", "voice": "female",
  "profile_id": "u<uid>_…" }  // voce clonata XTTS — vedi Voice Cloning

Response: audio/wav

Implementazione Suggerita

  • STT: Whisper (OpenAI) o Vosk locale
  • TTS: Piper TTS locale o Google Cloud TTS
  • Fallback: Web Speech API su browser supportati
📱 Status Implementazione
  • ✅ POST /api/stt attivo — trascrizione Whisper server-side
  • ✅ POST /api/tts attivo — voci built-in + profile_id = voce clonata (sezione 🧬 Voice Cloning)
  • ✅ POST /api/voice/convert — conversione timbro su qualsiasi audio

🧬 MediaDNA — Analisi Audio/Video NEW

"Orecchio digitale" server-side: carichi un file audio o video (max ~10 min) e ricevi un DNA musicale completo — separazione stem Demucs 4, trascrizione Whisper della voce, analisi musicale librosa (BPM, tonalità, pause, drop, struttura), firma PCL (timbro, spazio, emozione) e descrizione delle scene video via modello vision. Servizio API key: mediaDNA.

POST /api/media/analyze

// File piccoli (≤ ~50MB): upload diretto
POST /api/media/analyze
Authorization: Bearer <token>  — oppure x-api-key: tc_live_… (servizio "mediaDNA")
Content-Type: multipart/form-data

  file       blob audio/video (mp3, wav, mp4, mov…)
  language   'it' (default)

// File grandi (fino a ~1.5GB): upload a chunk — ogni chunk resta
// sotto il limite del proxy (~100MB), il server riassembla.
  file       chunk binario
  uploadId   id univoco dell'upload
  index      indice chunk (0-based)
  total      numero totale chunk
  name       nome file originale
  language   'it'

// Chunk intermedi → {"received":N,"total":M}
// Ultimo chunk / upload diretto → text/event-stream

Risposta SSE — fasi in tempo reale

data: {"phase":"probe","label":"Lettura file"}
data: {"phase":"extract","label":"Estrazione traccia audio"}
data: {"phase":"stems","pct":47,"label":"Separazione tracce"}   ← % reale Demucs
data: {"phase":"voice","label":"Trascrizione voce/testo"}
data: {"phase":"music","label":"Analisi musicale e DNA/PCL"}
data: {"phase":"genre","label":"Valutazione genere"}   ← secondo pass: genere + alternative
data: {"phase":"scenes","label":"Estrazione e analisi scene"}   ← solo video
data: {"phase":"done","result":{…}}
data: {"phase":"error","error":"…"}

Schema risultato

{
  "kind": "audio|video", "duration": 158.2,
  "music": { "bpm": 143.6, "key": "Si maggiore", "style_hint": "…",
             "pauses": [[0.0,1.8]], "drop_at_s": 110.2,
             "stem_energy_pct": {"bass":61,"drums":12,"vocals":14.5,"other":12.5},
             "sections": [[0,32,"quiet"],[32,110,"forte"]] },
  "pcl": {   ← DNA Pulse: timbro + spazio + emozione
    "timbreProfile": {"brightness":0.4,"gravityIndex":0.82,"attackStrength":0.5,
                      "tailPresence":0.99,"harmonicity":0.7,"roughness":0.3,
                      "noisiness":0.2,"stereoWidth":0.19,"spectralCentroid":0.5},
    "spectralSignature": {"subBass":…,"bass":…,"lowMid":…,"mid":…,
                          "highMid":…,"presence":…,"brilliance":…,
                          "spectralTilt":0.5,"rolloff":0.4},
    "spatialSignature": {"stereoWidth":…,"stereoCorrelation":…,"phaseRisk":…},
    "emotion": {"valence":0.73,"arousal":0.64,"label":"energico/euforico"} },
  "genre": { "primary": "trap / hip-hop", "confidence": 0.92,
             "alternatives": [{"genre":"edm / dance / techno","p":0.58}],
             "reasoning": "bassi 61% + sustain 0.99 (808), BPM 144 (half-time 72)…" },
  "transcript": "testo parlato/cantato completo (Whisper su stem vocals)",
  "scenes": ["descrizione scena 1", "…"],     ← solo video
  "stems": ["vocals","drums","bass","other"],
  "report": "testo riassuntivo pronto per il contesto di un LLM"
}
💡 Per le DAW Il campo pcl usa lo schema Pulse (TimbreProfile/SpectralSignature/SpatialSignature): consumabile direttamente per matching timbrico, organizzazione librerie sample, visualizzazioni colore e motori di suggerimento. Il quadrante emozionale (valence/arousal) etichetta il mood del brano.
⚠️ Limiti Max ~10 minuti di durata, ~1.5GB via chunk (70MB per richiesta). Demucs al primo uso scarica il modello (~300MB). La stima genere/stile è euristica (BPM+energia+timbro), non un classificatore dedicato.

🛠️ Retrace IA — Piattaforma App Generata NEW

Retrace IA (/devlab, in beta) genera, edita, fa il preview (Vite+HMR) e pubblica app web complete — e sa studiare codice esistente. Ogni app deployata su /app/<id> o /dev/<slug> ha un ecosistema Firebase-like isolato: database, auth utenti, storage file, cloud functions e proxy verso i servizi AI — tutto con la chiave pubblica window.TM_APP_KEY (pubblica per design come le key Firebase: l'isolamento è per appId).

AppDB — database per-app gratis

// Header obbligatorio su tutte le route app:
x-api-key: window.TM_APP_KEY

GET    /api/appdb/:collection              → lista documenti
POST   /api/appdb/:collection/:docId?    → upsert {…}
GET    /api/appdb/:collection/:docId     → documento
DELETE /api/appdb/:collection/:docId     → elimina

// Namespace isolato appdb_<appId>_<collection> — un'app vede solo i suoi dati.

AppAuth — utenti delle app gratis

MetodoEndpointDescrizione
POST/api/appauth/signup{email,password,name} → {token,user}
POST/api/appauth/login{email,password} → {token,user}
GET/api/appauth/meAuthorization: Bearer <token app> → {user}
POST/api/appauth/updateAggiorna profilo utente app
POST/api/appauth/logoutRevoca sessione
POST/api/appauth/oauth{code,redirect_uri} — login "Accedi con TorqueMind" (secret mai nel browser)
Accedi con TorqueMind — l'app manda l'utente a /oauth/authorize?client_id=<appId>&redirect_uri=<url app>, TorqueMind mostra il consenso e torna con ?code=: l'app lo scambia via /api/appauth/oauth e ottiene lo stesso {token,user} di signup/login.

AppAPI — proxy servizi TorqueMind

POST /api/appapi/<route>      x-api-key: window.TM_APP_KEY

llm/chat   {messages:[{role,content}], model?}   → chat LLM (billing owner)
llm/generate {prompt, model?}                    → completamento
chat       {messages:[…]}                        → alias ai/chat
vision     {images:["<b64>"], prompt}        → analisi immagini
tts        {text, voice?}                        → audio binario
stt        multipart file                        → trascrizione
search     {q}                                   → web search
search/deep {q}                                  → ricerca profonda
image      {prompt, size?}                       → genera immagine

// GEO — gratis, niente billing, 60 req/min per app:
geo/geocode   {q}                  → {results:[{lat,lng,displayName,address}]}
geo/reverse   {lat,lng}            → indirizzo da coordinate
geo/distance  {lat1,lng1,lat2,lng2}→ {distance:{km,meters,text}}
geo/timezone  {lat,lng}            → {utcOffset,localTime}
Billing — i servizi metered passano dal billing gate dell'owner (trial sviluppatori 4 mesi o pay-as-you-go su /gestisci/#billing). Geo, AppDB, AppAuth e AppFile sono gratis: nessuna fatturazione richiesta.

AppFn — cloud functions per-app

// Scrivi functions/<nome>.js nel progetto → al deploy diventa:
POST /api/appfn/<nome>     x-api-key: TM_APP_KEY  (+ Bearer token utente app opzionale)

// Sandbox context.tm:
await context.tm.api('llm/chat', {messages:[…]})    // TUTTI i servizi incl. geo/*
await context.tm.db.set('ordini', id, {…})          // get/set/list/del su appdb dell'app
await context.tm.file.put('img/logo.png', b64)      // → {path, url} pubblico
await context.tm.telegram('sendMessage', {chat_id, text}) // Bot API col bot del progetto
const u = context.tm.telegramUser(context.body.initData)  // valida HMAC initData mini app → {id, username…} o null
context.user   // utente app se Bearer valido — le chiavi private restano QUI, mai nel browser

AppFile — storage file per-app gratis

POST   /api/appfile/<path>          upload (≤25MB) → file pubblico
GET    /api/appfile/<path>?key=TM_APP_KEY  download — usabile in <img src>
DELETE /api/appfile/<path>               rimuovi

Preview & deploy

MetodoEndpointDescrizione
POST/api/projects/:id/agentSSE — l'agente Retrace IA costruisce/modifica l'app (JWT utente)
POST/api/projects/:id/dev/start|stopRunner Vite dev-server con HMR su /run/<id>/
GET/app/:id · /dev/:slug · /<username>/<slug>App deployata pubblica — vanity URL torquemind.org/utente/nome, slug rinominabile dal dialog Deploy (l'appId interno resta stabile: dati, functions e OAuth non si rompono)
GET/api/slug-check?slug=Verifica disponibilità indirizzo (JWT) — usata dal dialog deploy
PUT/api/projects/:id/telegramCollega il bot Telegram dell'utente al progetto — body {token} (da @BotFather); validato con getMe prima del salvataggio
GET/DELETE/api/projects/:id/telegramStato collegamento ({connected, bot}) / scollega — il token non è mai restituito
✈ Telegram Mini Apps & bot — un'app Retrace IA deployata su https://<slug>.torquemind.org è già una mini app Telegram valida (HTTPS). Il frontend include telegram-web-app.js e usa Telegram.WebApp; le functions accedono alla Bot API col bot collegato: context.tm.telegram('setChatMenuButton', …), sendGame/setGameScore per i giochi, e context.tm.telegramUser(initData) per validare l'utente Telegram server-side (HMAC). Il token non lascia mai il server.

🎨 Generazione Media — Immagini, Video, Musica NEW

Suite creativa server-side su GPU locale (ComfyUI + motore neurale): generazione immagini anche con editing a istruzione, video (LTX-Video t2v/i2v/v2v), modelli 3D con texture PBR (TRELLIS.2 image→3D, anche da prompt via txt2img), e musica completa con editing delle tracce. UI dedicate: /imggen, /vidgen, /musicgen, /musiclab (TrackForge DAW). Servizi chiave: imageGen, imagePro, videoGen, videoHD, gen3d, musicGen.

POST /api/gen/image imageGen

{
  "prompt": "un tramonto sul mare, stile acquerello",   // richiesto
  "negative": "", "model": "",
  "width": 1024, "height": 1024,
  "steps": 28, "cfg": 6, "seed": -1,
  "ref": {"filename": "foto.png"},       // img di riferimento (da /api/gen/upload)
  "edit": "cambia lo sfondo in una citta'"  // editing a istruzione (Qwen-Image-Edit)
}
// → {file, url} — servito da GET /api/gen/file?name=…
// Con ref+edit: modifica l'immagine; senza ref: genera da zero.

POST /api/gen/video videoGen / videoHD

{
  "prompt": "un teschio con collane d'oro che fuma, fumo che sale, cinematic",
  "duration": 5,              // secondi (frame-chain oltre 12s)
  "imageData": "base64…",   // i2v: anima questa immagine (anche imageName/ref)
  "videoName": "clip.mp4",  // v2v: video sorgente + denoise
  "quality": "hd|fast"      // hd=LTXV-13B (videoHD), fast=LTXV-2B (videoGen)
}
// → {jobId} → polling GET /api/gen/job/:id → GET /api/gen/file?filename=…
// Senza quality: HD automatico finche' resta quota videoHD, poi standard (degraded).

POST /api/gen/3d gen3d

{
  "prompt": "astronave low-poly stile videogioco",  // text→3D (immagine su :8188, poi TRELLIS.2)
  "imageData": "base64…",   // image→3D diretto (anche imageName)
  "texture": true,             // false = solo mesh bianca
  "targetFaces": 500000,        // semplificazione mesh
  "quality": "media|hd"       // media=shape 512+tex1K (veloce), hd=shape 1024+tex2K
}
// → {jobId} → GET /api/gen/3d/job/:id → GET /api/gen/3d/file?filename=… → GLB texturizzato PBR

POST /api/media/track musicGen — SSE

// text/event-stream: data: {phase, pct?, label?, result?, error?}
{
  "op": "text2music",       // vedi ops sotto
  "prompt": "pop italiano anni 80, synthwave",
  "lyrics": "[Verse]\n…", "vocalLanguage": "it",
  "duration": 180, "srcAudioB64" | "srcFile": "…",
  "start": 30, "end": 60, "strength": 0.6, "coverStrength": 0.5,
  "seed": -1, "steps": 50, "instruction": "…", "mode": "…", "track": "…"
}

// Ops:
//   text2music   prompt+lyrics → brano completo (nessun src richiesto)
//   cover        stessa traccia, nuovo stile (coverStrength)
//   repaint      rigenera SOLO la sezione start..end (strength)
//   extract      estrai uno stem (track: vocals|drums|bass|other)
//   lego         riarrangia partendo da uno stem
//   complete     estendi/continua il brano
//   edit         editing generico con instruction
// srcFile = nome file gia' in data/gen/<uid>/ (evita base64 su WAV lunghi).
// I risultati finiscono nella libreria utente: GET /api/media/files

File e libreria

MetodoEndpointDescrizione
POST/api/gen/uploadCarica sorgente (immagine/audio) per ref/edit
GET/api/gen/file?name= · /api/gen/audio/:fileFile generati
GET/api/gen/job/:id · /api/gen/statusPolling job e stato GPU
GET/api/media/files · /api/media/file/:idLibreria media dell'utente
POST/api/media/generateGenerazione media generica (wrapper)
POST/api/media/web-trackTraccia partendo da URL web mediaDNA
⚠️ GPU — questi servizi passano da un gpu gate: se la GPU è occupata da un altro job, la richiesta aspetta in coda o torna 503. Le operazioni musicGen lunghe (repaint, cover) possono durare minuti: usa sempre lo stream SSE, non timeout brevi.

🧬 Voice Cloning — Profili voce dell'utente NEW

Libreria vocale personale, condivisa tra tutti i servizi TorqueMind e le app Retrace IA: l'utente registra/carica 20–60s di voce pulita (anche in più campioni), il bridge preprocessa (denoise, loudnorm, 22kHz) e calcola i latents XTTS — la voce diventa poi usabile per parlato (TTS clonato) e canto (conversione Seed-VC sul vocal del brano). Ogni profilo è isolato per utente: i pid sono namespaziati u<uid>_<slug>_<rand> e l'ownership è verificata server-side su ogni chiamata.

Gestione profili — /api/voice/profiles

MetodoEndpointDescrizione
GET/api/voice/profilesLista le proprie voci: {pid, name, samples, hasLatents}
POST/api/voice/profiles{name} → crea profilo {pid} (vuoto, poi campioni)
POST/api/voice/profiles/:pid/sampleMultipart file audio (max 60MB) → preprocess + ricalcolo latents → {samples, total_seconds, has_latents}
PUT/api/voice/profiles/:pid{name} → rinomina il profilo (pid/campioni/latents invariati)
DELETE/api/voice/profiles/:pidElimina profilo + campioni + latents
GET/api/voice/profiles/:pid/ref.wavAnteprima audio del campione migliore (anche ?token= per player)
GET/api/voice/profiles/:pidDettaglio: campioni, latents, trained, stato training (running|done|error)
POST/api/voice/profiles/:pid/trainFine-tune XTTS "pro" — dataset whisper + GPTTrainer, 10-30 min in background. Quota voiceTrain. Ritorna 429 a quota esaurita
// 1) Crea il profilo
POST /api/voice/profiles
{ "name": "La mia voce" }  →  { "pid": "u4f5e_…_la-mia-voce_x1y2" }

// 2) Carica 1-3 campioni di 20-60s (parlato o cantato pulito)
POST /api/voice/profiles/<pid>/sample
Content-Type: multipart/form-data
file: voce.webm   →  { "total_seconds": 28.4, "has_latents": true }

Parlato — TTS con voce clonata (XTTS)

POST /api/tts
{ "text": "Buongiorno, sono il segretario di Vasyl",
  "lang": "it",
  "profile_id": "u4f5e_…_la-mia-voce_x1y2",   // solo profili propri
  "params": { "pitch_semitones": 0, "formant_shift": 1.0 } }
// → audio/wav. Senza profile_id: voci built-in (Kokoro/XTTS stock).

Canto — voice conversion sul vocal (Seed-VC)

Passando voiceProfile agli endpoint media, il post-stadio automatico estrae il vocal con demucs, lo converte nel timbro del profilo (Seed-VC DiT f0-conditioned, modello canto 44.1kHz) e lo remixa col backing. Se il brano è strumentale lo skip è automatico.

// Generazione SongForge
POST /api/media/generate     { …, "lyrics": "…", "voiceProfile": "<pid>" }

// Operazioni traccia (SongForge/TrackForge) — op vocali:
// revocal, cover, complete, repaint, lego(vocals), text2music(con lyrics)
POST /api/media/track        { "op":"revocal", …, "voiceProfile": "<pid>" }
POST /api/studio/track       { "op":"…", …, "voiceProfile": "<pid>" }

// Conversione diretta (audio già vocale → timbro profilo)
POST /api/voice/convert
{ "audio_b64": "…", "profile_id": "<pid>",
  "pitch_shift": 0, "steps": 32 }   →  { "audio_b64": "…wav 44.1kHz…" }
💡 Per Retrace IA e Studio IA
  • Le app generative possono offrire "parla/canta con la mia voce": crea profilo → upload campione → poi profile_id in /api/tts o voiceProfile in /api/media/*.
  • /api/voice/convert converte QUALSIASI audio nel timbro clonato (voice conversion zero-shot) — utile per dubbing, assistenti, messaggi vocali.
  • Le API key tc_live_ funzionano: il profilo appartiene all'owner della chiave — isolamento garantito dal prefisso u<uid>_.
  • Il record di onboarding ideale: 20–60s di voce pulita per campione, 1–3 campioni; il ricalcolo latents avviene a ogni upload.
  • Nelle UI: le voci si chiamano anche per nome nei prompt — «cantata con la voce di Marco» seleziona il profilo (SongForge composer, copilot TrackForge con azione voice).

Quote nei piani (mensili)

ServizioFreeStudio ProStudio MaxOfficinaOfficina ProUnlimited
voiceTrain — fine-tune XTTS15151530∞
voiceConvert — conversione Seed-VC (anche voiceProfile nei media)260300300600∞
tts — sintesi (incluse voci clonate)60400150015003000∞

I profili trained usano un checkpoint XTTS dedicato (finetune/model.pth): al TTS e al conditioning la qualità sale a ~95% identità. Il training conta solo all'avvio riuscito; la conversione conta quando il job media termina con voce attiva.

⚠️ Limiti — Primo uso: Seed-VC scarica ~2.3GB di pesi e XTTS ~1.8GB. La conversione cantato aggiunge 15–60s al post-processing (demucs + diffusione). Il fine-tune richiede ≥20s di campioni puliti e gira 10-30 min sulla GPU condivisa (un job alla volta). Profili solo wav preprocessati — niente condivisione tra utenti.

🎭 Personaggi animati — Motion Transfer & Sostituzione NEW

Due pipeline per "far vivere" le immagini: Motion Transfer (una tua foto + un video guida → il soggetto della foto esegue ESATTAMENTE la coreografia della guida) e Sostituzione personaggio (la tua foto prende il posto dell'attore in un video esistente — te a cavallo in un western, il tuo volto in una scena). Funziona da VidGen, Studio IA e Retrace IA (web e desktop).

Motion Transfer — "fai muovere il soggetto come nel mio video"

PassoCosa fareNote
1. Video guidaRegistra TE STESSO che fai il movimento (telefono, anche vestiti)Il video guida decide TUTTO: il modello copia la coreografia, non interpreta il testo. Movimento netto e ripetitivo, persona in piedi frontale, busto+gambe visibili.
2. Foto soggettoAllega una foto (reale o generata in ImageGen/Studio IA)Posa simile alla guida per risultati migliori — il soggetto mantiene identità e aspetto della foto.
3. GeneraVidGen → allega foto+video → "🕺 Anima personaggio". Studio IA → allega entrambi → "anima questa foto col movimento del video". Retrace → allega i file nella build → "mettilo nella hero a loop"Output ~3-5s in pochi minuti. In VidGen il selettore auto riconosce foto+video da solo.

Sostituzione personaggio — "metti me al posto dell'attore"

Allega la tua foto + il video sorgente (film, clip, scena) → il personaggio nel video diventa te, mantenendo movenze e camera originali. VidGen → "🎭 Sostituisci personaggio" o Studio IA con "metti me al posto del protagonista".

💡 Regola d'oro — la qualità della guida = la qualità del risultato. Una ripresa reale di 8-10s col movimento giusto vale più di qualsiasi prompt. Puoi anche riusare una guida buona per tanti soggetti diversi.
⚠️ Limite — il motion transfer è ottimizzato per persone (traccia lo scheletro umano). Animali e oggetti si animano meglio con il video generativo normale (image→video).

🎬 Videoclip IA — il video segue davvero la musica NEW

Da un brano pubblicato su TorqueVideos via SongForge (o TrackForge), "Genera videoclip" produce un video musicale completo: scene generate localmente a tema col testo, tagli sincronizzati sulle battute reali e sui confini strofa/ritornello, momenti eroe in 3D vero, e performer che si muovono a tempo. Nessuna clip stock: tutto generato.

Tipo scenaCosa produceQuando la sceglie la regia
NarrativaScene in sequenza che seguono il testo — stesso protagonista e stile per tutto il branoBrani con testo: il regista legge le strofe e mette in scena i soggetti reali del racconto
PerformerIl protagonista cammina/danza/canta verso cameraRitornelli e momenti performativi — usa la libreria guide di movimento
Eroe 3DIl soggetto iconico diventa un modello 3D vero che ruotaMomenti chiave (ingresso personaggio, hook)
Visual clubCromature liquide, tunnel, geometrie psichedeliche, drift cromaticoBrani strumentali/techno senza testo — niente umani, solo visual ipnotici
HorrorShort horror realistici stile found-footage: tensione crescente, atmosfera scuraBrani/prompt horror — pacing da cortometraggio, mai cartoon

Sync reale: i cambi scena cadono sulle battute rilevate nell'audio e sui confini veri delle sezioni (strofa→ritornello); un effetto "respiro" luminoso pulsa a tempo e flash sui downbeat — diverso per brani pop, club e horror. Le versioni restano editabili scena per scena.

📍 Come — pubblica il brano da SongForge/TrackForge su TorqueVideos → apri il video → "🎬 Genera videoclip" → attendi il job → le versioni prodotte si confrontano e si scelgono nell'editor scene.

🧊 Scansioni 3D — stanze e luoghi navigabili NEW

Carica una serie di foto di un ambiente (stanza, locale, venue, struttura, evento) → fotogrammetria → modello 3D navigabile direttamente nel browser: ruoti, zoomi e "cammini" dentro la scena ricostruita. Le scansioni hanno una cronologia personale e si possono incorporare sotto le mappe dei luoghi nelle pagine generate.

DoveCome
Studio IA📎 → "🧊 Scansione 3D ambiente" → seleziona le foto → card navigabile nella chat (persistente)
Retrace IA (web + desktop)Bottone 🧊 nel composer → upload foto → card con viewer 3D
Viewer/scan.html?id=… — orbiting con il mouse, &embed=1 per l'incorporamento nelle pagine
📸 Foto buone — 25-40 scatti con ~60% di sovrapposizione, camminando intorno/all'interno del soggetto, luce uniforme, niente foto identiche. La ricostruzione gira in coda sulla GPU: la card si aggiorna da sola quando è pronta.

🔞 Studio Adult — contenuti per adulti NEW

Il piano Studio Adult (100€/mese) sblocca la generazione di immagini e video con contenuti espliciti per adulti: modelli dedicati, nessuna censura nel risultato. Richiede due condizioni: la verifica dell'età nel profilo (pagina "Completa il profilo" — data di nascita) e il piano attivo. Senza entrambi i requisiti le richieste esplicite tornano un rifiuto esplicito, non un risultato censurato.

CondizioneCome si ottiene
Verifica etàAl primo login → "Completa il profilo" → data di nascita reale (+ documento opzionale). Obbligatoria per tutti gli account.
Piano Studio AdultAttivazione piano 100€/mese — include le quote della fascia Studio.
⚖️ Note — i contenuti generati restano privati nel tuo spazio; la pubblicazione di materiale esplicito su TorqueVideos e le condivisioni pubbliche seguono le regole della piattaforma e la legge applicabile. Account minorenni: zona adult bloccata permanentemente lato server.

📞 Segretario IA — risposte sui social con la tua voce BETA

Assistente che risponde a messaggi e vocali su WhatsApp, Telegram, Messenger e Instagram con la voce clonata del titolare (XTTS fine-tune) o testo LLM. Multi-tenant: ogni utente ha sessioni, inbox e impostazioni isolate. Le bozze possono essere riviste a mano ("bozze") o inviate in automatico ("auto").

Stato e impostazioni — /api/segretario/*

MetodoEndpointDescrizione
GET/api/segretario/stateStato canali + piano + impostazioni correnti
PUT/api/segretario/settings{business, persona, autoReply: off|draft|auto, voiceReplies, voiceProfile}
GET/api/segretario/inboxUltimi messaggi ?channel=&limit= — con bozza IA e status
POST/api/segretario/inbox/:id/draftGenera bozza risposta IA per il messaggio (quota secMsg)
POST/api/segretario/send{channel, to, text, voice?} — invio manuale/approvato; voice:true = vocale clonato (quota secCall)
POST/api/segretario/channels/:ch/connectwhatsapp (QR) · telegram (token bot) · messenger/instagram (Meta Page Token)
POST/api/segretario/channels/:ch/disconnectScollega il canale
// Collega WhatsApp (QR nella UI /services/segretario)
POST /api/segretario/channels/whatsapp/connect   →  { "state":"qr", "qr":"data:image/png…" }

// Telegram: crea bot su @BotFather e incolla il token
POST /api/segretario/channels/telegram/connect
{ "token": "123456:ABC…" }   →  { "state":"open", "me":"mio_bot" }

// Messenger/Instagram: Page Access Token Meta; configura il webhook su
//   /api/segretario/webhook/meta con il token di verifica mostrato in pagina
POST /api/segretario/channels/messenger/connect
{ "token": "EAA…", "pageId": "123…" }

Canali e quote per piano

Ogni piano sblocca più piattaforme e più risposte. La quota secMsg conta ogni risposta testuale inviata o bozza generata; secCall conta le risposte vocali in "chiamata" (vocale WhatsApp/Telegram con voce clonata).

PianoCanalisecMsg/mesesecCall/mese
FreeWhatsApp408
Studio ProWhatsApp · Telegram40060
Studio MaxWhatsApp · Telegram · Messenger1500200
OfficinaWhatsApp · Telegram · Messenger2500400
Officina ProWhatsApp · Telegram · Messenger · Instagram6000800
Officina UnlimitedTutti∞∞
💡 Integrazione TorqueMind Desktop / app
  • Il segretario usa la stessa voce clonata di SongForge/TrackForge: basta sec.voiceProfile nelle impostazioni o il profilo di default.
  • Le risposte vocali in arrivo vengono trascritte con Whisper e gli escono vocali XTTS clonati (formato ogg/opus per WhatsApp, wav per Telegram).
  • Per TorqueMind Desktop: le API /api/segretario/* sono pronte per il client nativo — il desktop può controllare WhatsApp Web o usare la sessione cloud.
⚠️ Beta — Sessione WhatsApp via libreria non ufficiale (baileys): su numeri principali valutare un numero dedicato. Messenger/Instagram richiedono app Meta verificata con permessi pages_messaging/instagram_manage_messages.

🧠 Sessioni Web & Memoria Condivisa

Sessioni persistenti per-utente per i servizi web (Studio AI, ImageGen, VideoGen…), più una "memoria" interrogabile stile ChatGPT: ogni sessione produce un riassunto + embedding semantico e le chat nuove recuperano i ricordi pertinenti alla domanda. Tutto filtrato per userId: mai dati di altri utenti.

GET    /api/sessions?service=ai              lista sessioni
POST   /api/sessions {service,title}          crea
PATCH  /api/sessions/:id {title}              rinomina
DELETE /api/sessions/:id                      elimina (cascade)
GET    /api/sessions/:id/messages             storico
POST   /api/sessions/:id/messages {role,content,meta}

// Contesto condiviso tra sessioni (stesso utente)
GET    /api/sessions/context?service=ai&q=testo+domanda&exclude=<sessionId>

// → {"history":[{role,content}…],"matched":["riassunto sessione"]}
// Ricerca semantica sulle memorie riassuntive → espande le
// top-3 sessioni pertinenti. Fallback: ultime 2 sessioni.
🔄 Come funziona A ogni risposta assistant la sessione rigenera in background un riassunto (3-5 frasi) + embedding semantico. Una chat nuova interroga le memorie con la prima domanda e inietta nel contesto solo i ricordi pertinenti.
TorqueMind · Sviluppo: trubax86 · torquemind.org