TanStack AI + Gonka — Applicazioni AI in TypeScript a basso costo

Installazione pacchetti (core + OpenAI-adapter, in cui risiede openaiCompatible):

# pnpm
pnpm add @tanstack/ai @tanstack/ai-openai

# npm
npm install @tanstack/ai @tanstack/ai-openai

Per un'interfaccia chat su React, aggiungi il client e gli hook:

pnpm add @tanstack/ai-client @tanstack/ai-react

API-key JoinGonka: se non ne hai ancora una, registrati su gate.joingonka.ai/register, ottieni 3M di token gratuiti e crea una chiave jg-xxx nella Dashboard → API Keys. Una sola chiave e un solo saldo funzionano sia per il formato OpenAI che per quello Anthropic.

In TanStack AI un provider personalizzato compatibile con OpenAI si configura con la funzione openaiCompatible(): imposti una volta sola baseURL, apiKey e la lista dei modelli, poi scegli il modello a ogni chiamata. Il nostro Gateway parla il formato Chat Completions, quindi lasciamo api: 'chat-completions' (è il valore predefinito).

import { openaiCompatible } from '@tanstack/ai-openai'

// Gonka provider: configured once
export const gonka = openaiCompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY!, // jg-your-key
  api: 'chat-completions',
  models: [
    'MiniMaxAI/MiniMax-M2.7', // default
    'deepseek-ai/DeepSeek-V4-Flash-0731',
    'zai-org/GLM-5.3-Flash', // reasoning model
  ],
})

Chat in streaming sul server (ad esempio un route handler in qualsiasi framework fullstack o TanStack Start). La lunghezza della risposta si imposta tramite modelOptions: è l'unico punto per i parametri wire nativi (max_tokens, temperature):

import { chat, toServerSentEventsResponse } from '@tanstack/ai'
import { gonka } from './gonka'

export async function POST(request: Request) {
  const { messages } = await request.json()

  const stream = chat({
    adapter: gonka('MiniMaxAI/MiniMax-M2.7'),
    messages,
    modelOptions: { max_tokens: 8192 }, // Gateway output cap
  })

  return toServerSentEventsResponse(stream)
}

Client React tramite l'hook useChat: fa streaming delle risposte dal server all'interfaccia:

import { useChat } from '@tanstack/ai-react'

function Chat() {
  const { messages, sendMessage, status } = useChat({ api: '/api/chat' })

  return (
    <div>
      {messages.map((m) => (
        <p key={m.id}><b>{m.role}:</b> {m.content}</p>
      ))}
      <button onClick={() => sendMessage('What is Gonka?')}>
        Ask
      </button>
    </div>
  )
}

Senza server: lo stesso provider funziona direttamente in uno script o in un backend: chiamate chat() e leggete lo stream. La connessione a Gonka è identica in tutti i casi.

Parametri dei modelli tramite Gateway: contesto di 180K token per MiniMax M2.7, 380K per DeepSeek V4 Flash e 390K per GLM-5.3 Flash. Il limite di max_tokens è 8192 per MiniMax M2.7 e GLM-5.3 Flash, 32768 per DeepSeek V4 Flash. Se max_tokens non viene specificato, il default per il non-stream è 1500, quindi per risposte lunghe impostatelo esplicitamente.

TanStack AI funziona comodamente sia tramite le tariffe dirette di OpenAI/Anthropic che tramite Gonka: cambia solo il baseURL. Ma il prezzo differisce di ordini di grandezza. Confrontiamo i carichi tipici di un'applicazione in produzione su TanStack AI:

L'approccio provider-agnostic di TanStack AI significa che passare a Gonka richiede solo la modifica di una riga (baseURL), senza riscrivere il codice. Nel frattempo, i tuoi strumenti type-safe, l'output strutturato e i React hook rimangono invariati. Per un'app con migliaia di utenti, la differenza è di decine di migliaia di dollari al mese.

Prezzo Gonka: ingresso ~$0.0062 per 1M di token, uscita ×3. È centinaia o migliaia di volte più economico delle tariffe dirette di OpenAI e Anthropic.

Il punto di forza di TanStack AI è il contratto unico toolDefinition(): uno strumento si descrive una volta sola (input/output tramite Zod, ArkType, Valibot o JSON Schema) e l'implementazione si aggancia sul server o sul client. MiniMax M2.7, DeepSeek V4 Flash e GLM-5.3 Flash supportano il native tool calling attraverso Gonka, quindi gli agenti lavorano in modo affidabile — senza dover fare il parsing delle risposte testuali.

import { chat, toolDefinition } from '@tanstack/ai'
import { gonka } from './gonka'
import { z } from 'zod'

const getWeather = toolDefinition({
  name: 'getWeather',
  description: 'Get the weather in a city',
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ tempC: z.number() }),
}).server(async ({ city }) => {
  return { tempC: 21 } // your real API call
})

const stream = chat({
  adapter: gonka('MiniMaxAI/MiniMax-M2.7'),
  messages: [{ role: 'user', content: 'What is the weather in Moscow?' }],
  tools: [getWeather],
  modelOptions: { max_tokens: 8192 },
})

Quale modello scegliere:

• MiniMaxAI/MiniMax-M2.7 — il default, equilibrio tra velocità e qualità, contesto lungo. Limite di risposta 8192.
• deepseek-ai/DeepSeek-V4-Flash-0731 — uno dei contesti più lunghi della rete (380K), prompt grandi a basso costo. Limite di risposta 32768.
• zai-org/GLM-5.3-Flash — modello di reasoning: ragiona prima di rispondere, forte sulla logica complessa; il contesto più lungo della rete (390K). Limite di risposta 8192; il ragionamento consuma parte dei max_tokens.

Grazie al runtime adapter switching di TanStack AI puoi tenere tutti e tre i modelli su un unico provider e passare dall'uno all'altro al volo — per esempio, i task che richiedono ragionamento su GLM-5.3 Flash e le risposte rapide su MiniMax.