TanStack AI + Gonka — Aplicativos de IA em TypeScript por centavos

Instalação de pacotes (núcleo + adaptador OpenAI, onde reside openaiCompatible):

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

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

Para uma interface de chat no React, adicione o cliente e os hooks:

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

API-key da JoinGonka: se ainda não tiver — registre-se em gate.joingonka.ai/register, obtenha 3M de tokens gratuitos e crie uma chave jg-xxx no Dashboard → API Keys. Uma chave e um saldo funcionam tanto para o formato OpenAI quanto para o Anthropic.

No TanStack AI, um provedor personalizado compatível com OpenAI é configurado com a função openaiCompatible(): você define baseURL, apiKey e a lista de modelos uma única vez, e depois escolhe o modelo a cada chamada. Nosso Gateway fala o formato Chat Completions, então mantemos api: 'chat-completions' (esse é o valor padrão).

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 com streaming no servidor (por exemplo, um route handler em qualquer framework fullstack ou no TanStack Start). O comprimento da resposta é definido em modelOptions — o único ponto para os parâmetros nativos de 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)
}

Cliente React por meio do hook useChat — faz streaming das respostas do servidor para a 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>
  )
}

Sem servidor: o mesmo provedor funciona diretamente em um script ou no backend — chame chat() e leia o stream. A conexão com a Gonka é idêntica em todos os casos.

Parâmetros dos modelos pelo Gateway: o contexto é de 180K tokens no MiniMax M2.7, 380K no DeepSeek V4 Flash e 390K no GLM-5.3 Flash. O teto de max_tokens é 8192 no MiniMax M2.7 e no GLM-5.3 Flash, e 32768 no DeepSeek V4 Flash. Se max_tokens não for informado, o padrão para non-stream é 1500, então, para respostas longas, defina-o explicitamente.

O TanStack AI funciona igualmente bem através das tarifas diretas da OpenAI/Anthropic e através da Gonka — apenas o baseURL muda. Mas o preço difere por ordens de magnitude. Vamos comparar cargas típicas de uma aplicação de produção no TanStack AI:

A abordagem provider-agnostic do TanStack AI significa que mudar para a Gonka é apenas editar uma linha (baseURL), e não reescrever o código. Ao mesmo tempo, suas ferramentas com segurança de tipos, saída estruturada e hooks de React permanecem inalterados. Para uma aplicação com milhares de usuários, a diferença é de dezenas de milhares de dólares por mês.

Preço da Gonka: entrada ~$0.0062 por 1M de tokens, saída ×3. Isso é centenas a milhares de vezes mais barato do que as tarifas diretas da OpenAI e Anthropic.

O grande destaque do TanStack AI é o contrato único toolDefinition(): a ferramenta é descrita uma única vez (entrada/saída via Zod, ArkType, Valibot ou JSON Schema) e a implementação é vinculada no servidor ou no cliente. MiniMax M2.7, DeepSeek V4 Flash e GLM-5.3 Flash suportam tool calling nativo através do Gonka, então os agentes funcionam de forma confiável — sem precisar fazer parsing de respostas em texto.

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

Qual modelo escolher:

• MiniMaxAI/MiniMax-M2.7 — padrão, equilíbrio entre velocidade e qualidade, contexto longo. Limite de resposta de 8192.
• deepseek-ai/DeepSeek-V4-Flash-0731 — um dos contextos mais longos da rede (380K), prompts grandes e baratos. Limite de resposta de 32768.
• zai-org/GLM-5.3-Flash — modelo de reasoning: raciocina antes de responder e é forte em lógica complexa; o contexto mais longo da rede (390K). Limite de resposta de 8192; o raciocínio consome parte de max_tokens.

Com o runtime adapter switching do TanStack AI, você pode manter os três modelos em um único provedor e alternar entre eles na hora — por exemplo, tarefas de raciocínio com o GLM-5.3 Flash e respostas rápidas com o MiniMax.