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, o provedor customizado compatível com OpenAI é configurado pela função openaiCompatible(): você define baseURL, apiKey e a lista de modelos uma vez, e depois seleciona o modelo para cada chamada. Nosso Gateway fala no formato Chat Completions, então 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: [
    'Qwen/Qwen3-235B-A22B-Instruct-2507-FP8', // padrão
    'moonshotai/Kimi-K2.6',
    'MiniMaxAI/MiniMax-M2.7',
  ],
})

Chat em streaming no servidor (por exemplo, um route handler em qualquer framework fullstack ou TanStack Start). Definimos o comprimento da resposta via modelOptions — este é o único ponto para parâmetros de wire nativos (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('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
    messages,
    modelOptions: { max_tokens: 8192 }, // limite Qwen via Gateway
  })

  return toServerSentEventsResponse(stream)
}

Cliente React via hook useChat — transmite as 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 fluxo. A conexão com o Gonka é a mesma para todas as opções.

Parâmetros do modelo via Gateway: o contexto de todos os três modelos é de 128K tokens. O limite de max_tokens: Qwen3-235B — 8192, Kimi K2.6 — 3072, MiniMax-M2.7 — 4096. Se max_tokens não for especificado, o padrão para não-stream é 1500, portanto, para respostas longas, defina-o explicitamente.

O TanStack AI funciona igualmente bem com as taxas diretas da OpenAI/Anthropic e através do Gonka — apenas a baseURL muda. Mas o preço difere em ordens de magnitude. Vamos comparar as cargas típicas de aplicativos de produção no TanStack AI:

A abordagem agnóstica do provedor do TanStack AI significa que mudar para o Gonka é uma mudança de uma linha (baseURL), não uma reescrita de código. Suas ferramentas type-safe, saída estruturada e hooks do React permanecem inalterados. Para um aplicativo com milhares de usuários, a diferença é de dezenas de milhares de dólares por mês.

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

A principal característica do TanStack AI é o 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. Qwen3-235B, Kimi K2.6 e MiniMax-M2.7 suportam tool calling nativo via Gonka, então os agentes funcionam de forma confiável — sem 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 de API real
})

const stream = chat({
  adapter: gonka('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
  messages: [{ role: 'user', content: 'Qual a previsão do tempo em Moscou?' }],
  tools: [getWeather],
  modelOptions: { max_tokens: 8192 },
})

Qual modelo escolher:

• Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 — padrão. O maior limite de resposta (8192) e forte tool calling. Adequado para agentes e saída estruturada.
• moonshotai/Kimi-K2.6 — excelente para longos diálogos e raciocínio. Limite de resposta 3072.
• MiniMaxAI/MiniMax-M2.7 — equilíbrio de velocidade e qualidade, limite 4096.

Graças à troca de adaptador em tempo de execução no TanStack AI, você pode manter os três modelos em um provedor e alternar entre eles facilmente — por exemplo, tarefas de agente pesadas no Qwen, respostas rápidas no MiniMax.