Vercel AI SDK + Gonka AI — Applicazioni AI in TypeScript a basso costo

API-key JoinGonka: registrati su gate.joingonka.ai/register — all'inizio ti diamo 3M di token gratuiti. Nella Dashboard, crea una chiave con il prefisso jg-.

Installazione pacchetti. Per un endpoint personalizzato compatibile con OpenAI, Vercel AI SDK consiglia il provider @ai-sdk/openai-compatible:

npm install ai @ai-sdk/openai-compatible

Connessione minima — creiamo un'istanza del provider tramite createOpenAICompatible e invochiamo generateText:

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY, // jg-la-tua-chiave
});

const { text } = await generateText({
  model: gonka('MiniMaxAI/MiniMax-M2.7'),
  prompt: 'Spiega cos\'è una rete di inferenza decentralizzata',
});

console.log(text);

Il parametro apiKey aggiunge automaticamente l'header Authorization: Bearer jg-la-tua-chiave — non serve una configurazione separata. Conserva la chiave in una variabile d'ambiente GONKA_API_KEY (ad esempio nel .env.local) e non nel codice.

Alternativa — il pacchetto @ai-sdk/openai con la factory createOpenAI({ baseURL, apiKey }). Entrambi i metodi funzionano; per gli endpoint non appartenenti a OpenAI, la documentazione dell'AI SDK consiglia proprio @ai-sdk/openai-compatible, poiché non include assunzioni specifiche per OpenAI.

La funzionalità principale di Vercel AI SDK è lo streaming della risposta. La funzione streamText inizia a trasmettere i token immediatamente, mentre l'helper toUIMessageStreamResponse() restituisce il flusso pronto direttamente dal route handler in Next.js App Router.

Server handler app/api/chat/route.ts:

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { streamText, convertToModelMessages, type UIMessage } from 'ai';

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY,
});

// consentiamo lo streaming fino a 30 secondi
export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const result = streamText({
    model: gonka('MiniMaxAI/MiniMax-M2.7'),
    system: 'Sei un assistente utile. Rispondi in modo breve e pertinente.',
    messages: convertToModelMessages(messages),
    maxOutputTokens: 8192, // limite di output tramite Gateway
  });

  return result.toUIMessageStreamResponse();
}

Sul client, collega l'hook useChat da @ai-sdk/react: gestirà autonomamente la chiamata a /api/chat e il rendering del flusso di messaggi. Il backend, nel frattempo, comunica con Gonka anziché con OpenAI.

Script senza UI (Node, async-iterator sullo stream):

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { streamText } from 'ai';

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY,
});

const result = streamText({
  model: gonka('MiniMaxAI/MiniMax-M2.7'),
  prompt: 'Scrivi un haiku sul calcolo distribuito',
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

Parametri dei modelli. Tramite il Gateway sono disponibili tre modelli: contesto di 200K token per MiniMax M2.7, 380K per DeepSeek V4 Flash e 390K per GLM-5.3 Flash; il limite della risposta (maxOutputTokens) è di 8192 per MiniMax M2.7 e GLM-5.3 Flash, 32768 per DeepSeek V4 Flash:

• MiniMaxAI/MiniMax-M2.7 — default (MiniMax M2.7);
• deepseek-ai/DeepSeek-V4-Flash-0731 (DeepSeek V4 Flash, contesto 380K);
• zai-org/GLM-5.3-Flash (GLM-5.3 Flash, modello di reasoning — riflette prima di rispondere).

Se maxOutputTokens non è impostato, per le richieste non-stream il Gateway restituirà per default fino a 1500 token; per le chat in streaming è meglio specificare il valore esplicitamente.

Vercel AI SDK si trova solitamente dietro un'interfaccia interattiva: chat, agenti, assistenti in un'app. Ogni messaggio trascina con sé la cronologia della conversazione, ogni passaggio dell'agente — il contesto degli strumenti. Pertanto, il costo reale non viene calcolato per singola richiesta, ma in base al carico di produzione. Confrontiamo alcuni scenari tipici:

Il prezzo di JoinGonka è di circa $0.0069 per 1M di token in entrata, l'uscita costa circa tre volte tanto. Per un'app con migliaia di richieste al giorno, questa è la differenza tra un conto da centinaia di dollari e un conto da pochi centesimi. I 3M di token gratuiti sono sufficienti per avviare le prime richieste del progetto.

Vercel AI SDK descrive gli strumenti in modo dichiarativo tramite l'oggetto tools e lo schema zod. I modelli della rete supportano il function calling nativo, quindi l'AI SDK riceve tool_calls strutturati senza fare parsing delle risposte testuali. Il parametro stopWhen: stepCountIs(n) consente più passaggi consecutivi: il modello richiama lo strumento, riceve il risultato e continua.

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText, tool, stepCountIs } from 'ai';
import { z } from 'zod';

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY,
});

const { text } = await generateText({
  model: gonka('MiniMaxAI/MiniMax-M2.7'),
  stopWhen: stepCountIs(5),
  tools: {
    weather: tool({
      description: 'Узнать погоду в городе',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ city, tempC: 17 }),
    }),
  },
  prompt: 'Какая погода в Москве? Ответь одним предложением.',
});

console.log(text);

Il modello richiama lo strumento weather, ottiene il risultato e genera la risposta finale. L'intero ciclo costa circa $0.000048 tramite Gonka contro $0.03-0.10 di Anthropic o OpenAI. Per le applicazioni basate su agenti, dove ogni richiesta dell'utente si sviluppa in 5-10 passaggi, il risparmio in produzione si misura in migliaia di dollari al mese.

Se stai costruendo un'applicazione AI in Python, dai un'occhiata alla guida su LangChain: utilizza lo stesso approccio tramite una classe compatibile con OpenAI.