Riferimento API
L'API di Hello Worker permette di integrare le funzionalità del worker nelle tue applicazioni. L'endpoint principale gestisce le conversazioni in streaming.
Autenticazione
L'API utilizza l'autenticazione JWT fornita da Supabase. Ogni richiesta deve includere un token di accesso valido nell'header Authorization.
Header di autenticazione:
Authorization: Bearer <SUPABASE_JWT_TOKEN>
Per ottenere un token JWT, autenticati tramite il client Supabase:
import { createClient } from "@supabase/supabase-js";
const supabase = createClient(
"https://IL_TUO_PROGETTO.supabase.co",
"LA_TUA_ANON_KEY"
);
const { data } = await supabase.auth.signInWithPassword({
email: "utente@esempio.it",
password: "la-tua-password",
});
const token = data.session?.access_token;Endpoint Chat
POST /api/chat/v2
Invia un messaggio al worker e ricevi la risposta in streaming. Il formato segue lo standard Vercel AI SDK.
Corpo della richiesta
{
"messages": [
{
"role": "user",
"content": "Quali sono i vostri orari di apertura?"
}
],
"workerId": "wkr_abc123def456",
"channel": "web"
}Parametri
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| messages | array | Si | Array di oggetti messaggio con role e content |
| workerId | string | Si | L'ID del worker a cui inviare il messaggio |
| channel | string | No | Canale di origine: web o telegram. Default: web |
| sessionId | string | No | ID di sessione per mantenere il contesto tra più messaggi |
Risposta
La risposta viene inviata in streaming con Content-Type: text/plain; charset=utf-8. Il formato segue il protocollo stream del Vercel AI SDK.
Esempio di risposta (stream):
0:"I "
0:"nostri "
0:"orari "
0:"di "
0:"apertura "
0:"sono "
0:"dal "
0:"lunedì "
0:"al "
0:"venerdì, "
0:"dalle "
0:"9:00 "
0:"alle "
0:"18:00."
e:{"finishReason":"stop","usage":{"promptTokens":350,"completionTokens":25}}Limiti di frequenza
Per garantire la stabilità del servizio, l'API applica limiti di frequenza per account:
| Piano | Richieste/minuto | Richieste/giorno |
|---|---|---|
| Starter | 20 | 500 |
| Pro | 60 | 2.000 |
| Business | 120 | 10.000 |
| Enterprise | Personalizzato | Personalizzato |
Quando superi il limite, l'API restituisce un errore 429 Too Many Requests. Attendi prima di riprovare.
Codici di errore
| Codice | Significato | Azione consigliata |
|---|---|---|
| 400 | Richiesta non valida | Verifica il formato del corpo della richiesta |
| 401 | Non autenticato | Controlla il token JWT nell'header Authorization |
| 403 | Non autorizzato | L'utente non ha accesso a questo worker |
| 429 | Troppe richieste | Attendi e riprova. Considera un upgrade di piano |
| 500 | Errore interno | Riprova dopo qualche secondo. Se persiste, contatta il supporto |
| 503 | Servizio non disponibile | Il servizio AI è temporaneamente sovraccarico. Riprova tra poco |