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 o baseURL, o apiKey e a lista de modelos uma vez e, em seguida, seleciona o modelo para cada chamada. Nosso Gateway fala o formato Chat Completions, por isso mantemos api: 'chat-completions' (este é o valor padrão).

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

// Provedor Gonka — configurado uma vez
export const gonka = openaiCompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY!, // jg-sua-chave
  api: 'chat-completions',
  models: [
    'MiniMaxAI/MiniMax-M2.7', // padrão
    'deepseek-ai/DeepSeek-V4-Flash-0731',
    'zai-org/GLM-5.3-Flash', // modelo de raciocínio
  ],
})

Chat com streaming no servidor (por exemplo, um route handler em qualquer framework fullstack ou TanStack Start). O tamanho da resposta é definido através de modelOptions — este é o ponto único para 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 }, // limite de saída através do Gateway
  })

  return toServerSentEventsResponse(stream)
}

Cliente React através do hook useChat — transmite 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('O que é Gonka?')}>
        Perguntar
      </button>
    </div>
  )
}

Sem servidor: o mesmo provedor funciona em um script ou backend diretamente — invoque chat() e leia o fluxo. A conexão com a Gonka é a mesma para todas as variantes.

Parâmetros dos modelos via Gateway: o contexto é de 200K tokens para o MiniMax M2.7, 380K para o DeepSeek V4 Flash e 390K para o GLM-5.3 Flash. O limite max_tokens é de 8192 para o MiniMax M2.7 e GLM-5.3 Flash, e 32768 para o DeepSeek V4 Flash. Se max_tokens não for especificado, o padrão para non-stream é 1500; portanto, 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.0069 por 1M de tokens, saída ×3. Isso é centenas a milhares de vezes mais barato do que as tarifas diretas da OpenAI e Anthropic.

A principal vantagem do TanStack AI é um contrato unificado toolDefinition(): a ferramenta é descrita uma vez (entrada/saída via Zod, ArkType, Valibot ou JSON Schema) e a implementação é vinculada no servidor ou cliente. MiniMax M2.7, DeepSeek V4 Flash e GLM-5.3 Flash suportam tool calling nativo via Gonka, por isso os agentes funcionam de forma confiável, sem necessidade de analisar respostas de texto.

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

const getWeather = toolDefinition({
  name: 'getWeather',
  description: 'Obter o clima em uma cidade',
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ tempC: z.number() }),
}).server(async ({ city }) => {
  return { tempC: 21 } // sua chamada real de API
})

const stream = chat({
  adapter: gonka('MiniMaxAI/MiniMax-M2.7'),
  messages: [{ role: 'user', content: 'Qual é o clima em Moscou?' }],
  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 8192.
• deepseek-ai/DeepSeek-V4-Flash-0731 — um dos contextos mais longos da rede (380K), prompts grandes baratos. Limite de resposta 32768.
• zai-org/GLM-5.3-Flash — modelo de raciocínio: raciocina antes de responder, é forte em lógica complexa; o contexto mais longo da rede (390K). Limite de resposta 8192; o raciocínio consome parte dos max_tokens.

Graças ao runtime adapter switching no TanStack AI, você pode manter todos os três modelos em um único provedor e alternar entre eles dinamicamente — por exemplo, tarefas de raciocínio no GLM-5.3 Flash, respostas rápidas no MiniMax.