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

Chiave API di JoinGonka: registrati su gate.joingonka.ai/register — per iniziare ti regaliamo 3M token gratis. Nella Dashboard crea una chiave con il prefisso jg-.

Installazione dei 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 con createOpenAICompatible e chiamiamo 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-your-key
});

const { text } = await generateText({
  model: gonka('MiniMaxAI/MiniMax-M2.7'),
  prompt: 'Explain what a decentralized inference network is',
});

console.log(text);

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

In alternativa — il pacchetto @ai-sdk/openai con la factory createOpenAI({ baseURL, apiKey }). Entrambi gli approcci funzionano; per endpoint non di proprietà di OpenAI, però, la documentazione di AI SDK consiglia proprio @ai-sdk/openai-compatible — non si porta dietro assunzioni specifiche di OpenAI superflue.

Il punto di forza di Vercel AI SDK è la restituzione in streaming della risposta. La funzione streamText inizia a fare streaming dei token immediatamente, e l'helper toUIMessageStreamResponse() restituisce uno stream già pronto direttamente dal route handler in Next.js App Router.

Handler lato server 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,
});

// allow streaming for up to 30 seconds
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: 'You are a helpful assistant. Answer briefly and to the point.',
    messages: convertToModelMessages(messages),
    maxOutputTokens: 8192, // Gateway output cap
  });

  return result.toUIMessageStreamResponse();
}

Sul client collega l'hook useChat da @ai-sdk/react — si occupa da solo di chiamare /api/chat e di renderizzare lo stream dei messaggi. Il backend, nel frattempo, parla con Gonka, non 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: 'Write a haiku about distributed computing',
});

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

Parametri dei modelli. Tramite il Gateway sono disponibili tre modelli: contesto da 180K token per MiniMax M2.7, 380K per DeepSeek V4 Flash e 390K per GLM-5.3 Flash; il tetto della risposta (maxOutputTokens) è 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 reasoning — ragiona prima di rispondere).

Se maxOutputTokens non è specificato, per una richiesta non-stream il Gateway restituisce di default fino a 1500 token — per le chat in streaming è meglio indicare 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.0062 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 native function calling, quindi l'AI SDK riceve tool_calls strutturate senza dover fare il parsing delle risposte testuali. Il parametro stopWhen: stepCountIs(n) consente più passaggi consecutivi — il modello chiama uno 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: 'Get the weather in a city',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ city, tempC: 17 }),
    }),
  },
  prompt: 'What is the weather in Moscow? Answer in one sentence.',
});

console.log(text);

Il modello chiama lo strumento weather, riceve 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 agentiche, 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 — lì trovi lo stesso approccio tramite la classe compatibile con OpenAI.