NexusAI API

Szybki Start

Pierwsze zapytanie do API NexusAI w 2 minuty.

# Wyślij wiadomość do AI
curl https://nexus-ai.click/api/tenant-panel/ai/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: twoj-slug" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 256
  }'

# pip install nexusai-python
from nexusai import NexusAI

client = NexusAI(
    api_key="YOUR_API_KEY",
    tenant="twoj-slug"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    max_tokens=256
)

print(response.choices[0].message.content)

// npm install @nexusai/sdk
import { NexusAI } from '@nexusai/sdk'

const client = new NexusAI({
  apiKey: 'YOUR_API_KEY',
  tenant: 'twoj-slug'
})

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
  maxTokens: 256
})

console.log(response.choices[0].message.content)

// composer require nexusai/sdk
use NexusAIClient;

$client = new Client([
    'api_key' => 'YOUR_API_KEY',
    'tenant'  => 'twoj-slug',
]);

$response = $client->chat->completions->create([
    'model'      => 'gpt-4o',
    'messages'   => [['role'=>'user','content'=>'Hello!']],
    'max_tokens' => 256,
]);

echo $response->choices[0]->message->content;

// go get github.com/nexusai/go-sdk
package main

import (
    "context"
    nexus "github.com/nexusai/go-sdk"
)

func main() {
    client := nexus.NewClient("YOUR_API_KEY", "twoj-slug")
    resp, _ := client.Chat.Complete(context.Background(), nexus.ChatRequest{
        Model:    "gpt-4o",
        Messages: []nexus.Message{{Role: "user", Content: "Hello!"}},
        MaxTokens: 256,
    })
    fmt.Println(resp.Choices[0].Message.Content)
}

Uwierzytelnianie

NexusAI używa kluczy API przekazywanych w nagłówku Authorization.

{
  "access_token": "eyJ...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Chat Completions

Główny endpoint do komunikacji z modelami AI.

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "Jesteś asystentem."
    },
    {
      "role": "user",
      "content": "Pomóż mi napisać email"
    }
  ],
  "max_tokens": 512,
  "temperature": 0.7,
  "stream": false
}

{
  "id": "chatcmpl-abc123",
  "model": "gpt-4o",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Cześć! Jak mogę..."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 87,
    "total_tokens": 111
  }
}

Streaming SSE

Odpowiedź AI w czasie rzeczywistym przez Server-Sent Events. Ustaw stream: true w body zapytania.

// Browser EventSource example
const es = new EventSource('/api/tenant-panel/chat/stream?token=xxx');
es.onmessage = e => {
  const chunk = JSON.parse(e.data);
  process.stdout.write(chunk.delta || '');
  if (chunk.done) es.close();
};

// Node.js fetch streaming
const res = await fetch('/api/tenant-panel/chat', {
  method: 'POST',
  headers: { Authorization: 'Bearer xxx', 'Content-Type': 'application/json' },
  body: JSON.stringify({ model: 'gpt-4o', message: 'Hello', stream: true })
});
const reader = res.body.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(new TextDecoder().decode(value));
}

{
  "delta": "czę",
  "done": false,
  "tokens": 3
}

Embeddings

Generuj wektory semantyczne dla RAG, wyszukiwania i klasyfikacji treści.

{
  "model": "text-embedding-3-small",
  "input": "Tekst do embeddingu",
  "encoding_format": "float"
}

{
  "data": [{
    "embedding": [0.123, -0.456, ...],
    "index": 0
  }],
  "usage": { "total_tokens": 12 }
}

Image Generation

Generuj obrazy przez DALL-E 3 lub Stable Diffusion.

{
  "url": "https://...cdn.../img.png",
  "revised_prompt": "...",
  "model": "dall-e-3"
}

Speech-to-Text

Transkrypcja audio przez Whisper-1. Obsługa: mp3, mp4, mpeg, mpga, m4a, wav, webm.

# cURL example
curl https://nexus-ai.click/api/audio/transcriptions \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "file=@audio.mp3" \
  -F "model=whisper-1" \
  -F "language=pl"

# Response
{ "text": "Transkrypcja audio...", "duration": 3.24 }

Tenants API

Zarządzanie organizacjami (multi-tenancy).

Webhooks

Zdarzenia wysyłane do Twojego endpointu. Weryfikacja przez X-Nexus-Signature (HMAC-SHA256).

// POST https://twoja-domena.pl/webhook
{
  "event": "ai.quota_exceeded",
  "tenant": "twoj-slug",
  "timestamp": "2025-07-14T10:00:00Z",
  "data": {
    "used": 1000,
    "limit": 1000,
    "model": "gpt-4o"
  }
}

Users API

Zarządzanie użytkownikami w ramach tenanta.

Billing API

Zarządzanie subskrypcjami, fakturami i płatnościami przez Stripe.

Usage & Analytics

Metryki użycia AI, tokenów i aktywnościplatformy.

Addons / Marketplace API

Instalacja i zarządzanie dodatkami z Marketplace per tenant. Limity: Starter=2, Business=10, Enterprise=∞.

{
  "addon_id": "ai-chat",
  "config": { "model": "gpt-4o", "temperature": 0.7 }
}
// Response 201
{
  "ok": true,
  "addon_id": "ai-chat",
  "installed_at": "2026-07-16T10:00:00Z"
}

Architektura Platformy

NexusAI działa w 100% na Cloudflare Workers — edge runtime, zero cold starts, globalny deployment.

Bezpieczeństwo

Enterprise-grade security wbudowane w każdą warstwę platformy.

{
  "id": 42,
  "user_id": 7,
  "tenant_slug": "acme",
  "action": "CREATE",
  "resource": "tenant",
  "detail": "Created tenant: acme (business)",
  "ip": "1.2.3.4",
  "created_at": "2026-07-16T10:00:00Z"
}

Multi-Tenancy

Każdy tenant ma izolowany zakres danych w tej samej bazie D1. Identyfikacja przez tenant_slug.

White-Label Customization

Każdy tenant może w pełni dostosować branding — kolory, logo, domeny, e-maile nadawcze.

{
  "primaryColor": "#6366f1",
  "accentColor":  "#a78bfa",
  "logoUrl":      "https://cdn.example.com/logo.png",
  "customDomain": "app.twoja-firma.pl",
  "senderName":   "Twoja Firma AI",
  "senderEmail":  "noreply@twoja-firma.pl",
  "footerText":   "© 2026 Twoja Firma. Powered by NexusAI."
}

Health Score API

Algorytm 5-sygnałowy (0–100 pkt) oceniający kondycję tenanta. Przeliczany automatycznie (cron) i on-demand.

{
  "healthScore":  73,
  "healthGrade":  "Fair",
  "healthStatus": "🟡",
  "signals": {
    "ai_activity":    24,
    "quota_util":     20,
    "team_size":      10,
    "webhooks":       15,
    "onboarding":     4
  }
}

Cron & Scheduled Jobs

Automatyczne zadania uruchamiane przez Cloudflare Workers Cron Triggers i endpoint HTTP.

"triggers": {
  "crons": ["0 3 * * *", "0 */6 * * *"]
}

Migracje Bazy Danych

Cloudflare D1 — migracje przez wrangler CLI. Środowiska: local (SQLite) i production (D1).

# Zastosuj migracje lokalnie (dev)
npx wrangler d1 migrations apply webapp-production --local

# Zastosuj migracje do produkcji
npx wrangler d1 migrations apply webapp-production

# Uruchom seed danych testowych
npx wrangler d1 execute webapp-production --local --file=./seed.sql

# Zapytanie ad-hoc do produkcyjnej D1
npx wrangler d1 execute webapp-production --command="SELECT COUNT(*) FROM tenants"

CREATE TABLE tenants (
  slug TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  plan TEXT DEFAULT 'starter',
  status TEXT DEFAULT 'trial',
  billing_email TEXT,
  ai_model TEXT,
  ai_provider TEXT DEFAULT 'openai',
  quota INTEGER DEFAULT 1000,
  tokens_used INTEGER DEFAULT 0,
  trial_ends_at TEXT,
  health_score INTEGER DEFAULT 0,
  created_at TEXT DEFAULT (datetime('now'))
);

CREATE TABLE tenant_addons (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  tenant_slug TEXT NOT NULL,
  addon_id TEXT NOT NULL,
  config TEXT,
  installed_at TEXT DEFAULT (datetime('now')),
  UNIQUE(tenant_slug, addon_id)
);

Self-Hosting Guide

Wdrożenie własnej instancji NexusAI na koncie Cloudflare. Wymaga: konto Cloudflare (free tier wystarczy).

git clone https://github.com/nexusai/platform.git
cd platform
npm install
cp .dev.vars.example .dev.vars
# Edytuj .dev.vars — ustaw STRIPE_SECRET_KEY, RESEND_API_KEY etc.

# Zaloguj się do Cloudflare
npx wrangler login

# Utwórz bazę D1
npx wrangler d1 create nexusai-production

# Skopiuj database_id do wrangler.jsonc
# Zastosuj migracje
npx wrangler d1 migrations apply nexusai-production

npx wrangler secret put STRIPE_SECRET_KEY
npx wrangler secret put RESEND_API_KEY
npx wrangler secret put JWT_SECRET
npx wrangler secret put CRON_SECRET

# Build i deploy
npm run build
npx wrangler pages deploy dist --project-name nexusai

RBAC — Role i uprawnienia

NexusAI stosuje 5-poziomowy RBAC (Role-Based Access Control). Każdy endpoint sprawdza rolę przez middleware requireRole().

// Definicja poziomów (im wyższy numer, tym więcej uprawnień)
const ROLE_LEVELS: Record<string, number> = {
  viewer: 0, member: 1, partner: 2, admin: 3, tenant_admin: 3, superadmin: 99
};

function requireRole(minRole: string) {
  return async (c: Context, next: Next) => {
    const payload = verifyJWT(c.req.header('Authorization'));
    if (!payload) return c.json({ error: 'Unauthorized' }, 401);
    if (ROLE_LEVELS[payload.role] < ROLE_LEVELS[minRole]) {
      return c.json({ error: 'Forbidden' }, 403);
    }
    c.set('user', payload);
    await next();
  };
}

Refresh Tokens

NexusAI implementuje rotating refresh tokens — access token wygasa po 24h, refresh token po 30 dniach i jest rotowany przy każdym użyciu.

// Request
{ "refreshToken": "eyJhb..." }

// Response 200
{
  "accessToken":  "eyJhbGci...",  // wygasa za 24h
  "refreshToken": "d8f3a1...",   // wygasa za 30 dni (nowy!)
  "expiresIn":    86400
}

// Error — token wygasły lub użyty ponownie
{ "error": "Invalid or expired refresh token" }  // HTTP 401

2FA TOTP — Implementacja

NexusAI wspiera TOTP (Time-based One-Time Password) zgodny z RFC 6238 — kompatybilny z Google Authenticator, Authy, 1Password.

{
  "secret":     "JBSWY3DPEHPK3PXP",            // base32 secret
  "qrDataUrl": "data:image/png;base64,...",  // PNG QR code
  "otpauthUrl": "otpauth://totp/NexusAI%20Platform:user@email.pl?secret=..."
}

-- Kolumny w tabeli users
ALTER TABLE users ADD COLUMN totp_secret TEXT DEFAULT NULL;
ALTER TABLE users ADD COLUMN totp_verified INTEGER DEFAULT 0;
-- Kody odzysku (generowane po stronie klienta, 8 kodów XXXX-XXXX)
-- Nie przechowywane w DB — użytkownik sam je zapisuje

Rate Limiting — Internals

Rate limiting implementowany przez middleware w Cloudflare Workers używając in-memory Map (per Worker instance). Limit per IP i per tenant.

const RATE_LIMITS = {
  auth:    { maxRequests: 10,  windowSec: 60  },  // Login / register
  ai:      { maxRequests: 100, windowSec: 60  },  // AI chat completions
  api:     { maxRequests: 300, windowSec: 60  },  // Ogólne API
  contact: { maxRequests: 5,   windowSec: 300 },  // Formularz kontaktowy
  profile: { maxRequests: 30,  windowSec: 60  },  // Aktualizacja profilu
  admin:   { maxRequests: 200, windowSec: 60  },  // Panel admina
};

// Nagłówki HTTP zwracane przy każdym odpowiedzi:
X-RateLimit-Limit:     100   // max requestów w oknie
X-RateLimit-Remaining: 87    // pozostało w bieżącym oknie
X-RateLimit-Reset:     1720000060  // Unix timestamp resetu

Webhook Signature Verification

Każdy webhook wysyłany przez NexusAI jest podpisany HMAC-SHA256. Weryfikacja chroni przed fałszywymi requestami i replay attacks.

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');
  // timingSafeEqual — ochrona przed timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signature)
  );
}

app.post('/webhooks/nexusai', (req, res) => {
  const sig = req.headers['x-nexusai-signature'];
  if (!verifyWebhook(req.rawBody, sig, process.env.WEBHOOK_SECRET))
    return res.status(401).json({ error: 'Invalid signature' });
  // Przetwórz zdarzenie...
});

import hmac, hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Zmienne środowiskowe

Kompletna lista zmiennych wymaganych do uruchomienia NexusAI. Przechowywane jako Cloudflare Workers Secrets.

npx wrangler secret put JWT_SECRET
> Enter a secret value: ••••••••••••••••
✓ Success! Uploaded secret JWT_SECRET

npx wrangler secret put STRIPE_SECRET_KEY
npx wrangler secret put RESEND_API_KEY
npx wrangler secret put OPENAI_API_KEY

# Lista wszystkich ustawionych sekretów
npx wrangler secret list

Pełne API — tabela endpointów

Kompletna lista endpointów. Base URL: https://nexus-ai.click/api

Rate Limits

Kody błędów

SDK & Biblioteki

Oficjalne SDK do integracji z NexusAI API.