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

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

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

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

Para interfaces de chat em React, adicione o cliente e os hooks:

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

Chave API JoinGonka: se ainda não tiver uma — registre-se em gate.joingonka.ai/register, obtenha 10M de tokens gratuitos e crie uma chave jg-xxx no Dashboard → API Keys. Uma única chave e um único saldo funcionam para os formatos OpenAI e 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 vez, e então escolhe o modelo a cada chamada. Nosso Gateway usa 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: [
    'moonshotai/Kimi-K2.6', // padrão
    'MiniMaxAI/MiniMax-M2.7',
  ],
})

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

  return toServerSentEventsResponse(stream)
}

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

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

Parâmetros de modelos via Gateway: o contexto disponível para ambos os modelos é de 200K tokens. O limite max_tokens é 8192 para todos os modelos da rede. 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 de forma equivalente tanto via tarifas diretas da OpenAI/Anthropic quanto via Gonka — apenas a baseURL muda. Mas o preço difere por ordens de grandeza. Vamos comparar as cargas típicas de uma aplicação de produção no TanStack AI:

A abordagem agnóstica a provedor do TanStack AI significa que mudar para o Gonka é apenas editar uma linha (baseURL), sem reescrever o código. Enquanto isso, suas tools 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 do Gonka: entrada ~$0.003 por 1M de tokens, saída ×3. Isso é centenas ou milhares de vezes mais barato que as tarifas diretas da OpenAI e Anthropic.

A principal vantagem do TanStack AI é o contrato único 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. Kimi K2.6 e MiniMax-M2.7 suportam tool calling nativo via Gonka, assim os agentes funcionam de forma confiável — sem a necessidade de processar (análise gramatical) respostas de texto.

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

const getWeather = toolDefinition({
  name: 'getWeather',
  description: 'Descobrir a temperatura na cidade',
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ tempC: z.number() }),
}).server(async ({ city }) => {
  return { tempC: 21 } // sua chamada de API real
})

const stream = chat({
  adapter: gonka('MiniMaxAI/MiniMax-M2.7'),
  messages: [{ role: 'user', content: 'Qual a temperatura em Moscou?' }],
  tools: [getWeather],
  modelOptions: { max_tokens: 8192 },
})

Qual modelo escolher:

• moonshotai/Kimi-K2.6 — forte em programação, raciocínio e cenários de agentes. Limite de resposta 8192.
• MiniMaxAI/MiniMax-M2.7 — padrão, equilíbrio entre velocidade e qualidade, contexto longo. Limite de resposta 8192.

Graças ao runtime adapter switching no TanStack AI, você pode manter ambos os modelos no mesmo provedor e alternar entre eles dinamicamente — por exemplo, tarefas pesadas de agentes no Kimi, respostas rápidas no MiniMax.