TanStack AI + Gonka — aplikacje AI w TypeScript za grosze

Instalacja pakietów (rdzeń + adapter OpenAI, w którym znajduje się openaiCompatible):

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

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

Dla interfejsu czatu w React dodaj klienta i hooki:

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

Klucz API JoinGonka: jeśli jeszcze go nie masz — zarejestruj się na gate.joingonka.ai/register, odbierz 3M darmowych tokenów i utwórz klucz jg-xxx w Dashboard → API Keys. Jeden klucz i jedno saldo działają zarówno dla formatu OpenAI, jak i Anthropic.

W TanStack AI niestandardowego providera zgodnego z OpenAI konfiguruje się funkcją openaiCompatible(): raz ustawiasz baseURL, apiKey i listę modeli, a potem wybierasz model przy każdym wywołaniu. Nasz Gateway mówi w formacie Chat Completions, więc zostawiamy api: 'chat-completions' (to wartość domyślna).

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 streamingowy na serwerze (np. route handler w dowolnym frameworku fullstack lub TanStack Start). Długość odpowiedzi ustawiamy przez modelOptions — to jedyne miejsce na natywne parametry wire (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)
}

Klient React przez hook useChat — streamuje odpowiedzi z serwera do UI:

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>
  )
}

Bez serwera: ten sam provider działa bezpośrednio w skrypcie lub backendzie — wywołujesz chat() i czytasz strumień. Połączenie z Gonka wygląda identycznie w każdym wariancie.

Parametry modeli przez Gateway: kontekst to 180K tokenów dla MiniMax M2.7, 380K dla DeepSeek V4 Flash i 390K dla GLM-5.3 Flash. Limit max_tokens to 8192 dla MiniMax M2.7 i GLM-5.3 Flash, 32768 dla DeepSeek V4 Flash. Jeśli max_tokens nie jest podany, domyślna wartość dla non-stream to 1500, więc przy długich odpowiedziach ustawiaj go wprost.

TanStack AI działa równie wygodnie zarówno przez bezpośrednie taryfy OpenAI/Anthropic, jak i przez Gonka — zmienia się tylko baseURL. Ale cena różni się o rzędy wielkości. Porównajmy typowe obciążenia aplikacji produkcyjnej na TanStack AI:

Podejście Provider-agnostic w TanStack AI oznacza, że przejście na Gonka to edycja jednej linii (baseURL), a nie przepisywanie kodu. Jednocześnie twoje bezpieczne typowo narzędzia, ustrukturyzowane wyjście i hooki React pozostają bez zmian. Dla aplikacji z tysiącami użytkowników różnica to dziesiątki tysięcy dolarów miesięcznie.

Cena Gonka: wejście ~$0.0062 za 1M tokenów, wyjście ×3. To setki–tysiące razy taniej niż bezpośrednie taryfy OpenAI i Anthropic.

Kluczową zaletą TanStack AI jest jednolity kontrakt toolDefinition(): narzędzie opisujesz raz (wejście/wyjście przez Zod, ArkType, Valibot lub JSON Schema), a implementację podpinasz po stronie serwera lub klienta. MiniMax M2.7, DeepSeek V4 Flash i GLM-5.3 Flash obsługują natywne wywoływanie narzędzi przez Gonka, dzięki czemu agenci działają niezawodnie — bez parsowania odpowiedzi tekstowych.

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 },
})

Który model wybrać:

• MiniMaxAI/MiniMax-M2.7 — domyślny, balans szybkości i jakości, długi kontekst. Limit odpowiedzi 8192.
• deepseek-ai/DeepSeek-V4-Flash-0731 — jeden z najdłuższych kontekstów w sieci (380K), tanie duże prompty. Limit odpowiedzi 32768.
• zai-org/GLM-5.3-Flash — model reasoning: rozumuje przed odpowiedzią, mocny w złożonej logice; najdłuższy kontekst w sieci (390K). Limit odpowiedzi 8192; rozumowanie zużywa część max_tokens.

Dzięki runtime adapter switching w TanStack AI możesz trzymać wszystkie trzy modele u jednego providera i przełączać się między nimi w locie — na przykład zadania z rozumowaniem na GLM-5.3 Flash, szybkie odpowiedzi na MiniMax.