TanStack AI + Gonka — Aplicaciones de IA en TypeScript por centavos

Instalación de paquetes (núcleo + adaptador OpenAI, que contiene openaiCompatible):

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

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

Para la interfaz de chat en React, añada el cliente y los hooks:

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

Clave API de JoinGonka: si aún no tiene una, regístrese en gate.joingonka.ai/register, obtenga 10M de tokens gratuitos y cree una clave jg-xxx en el Dashboard → API Keys. Una sola clave y un solo saldo funcionan tanto para el formato OpenAI como para el formato Anthropic.

En TanStack AI, el proveedor personalizado compatible con OpenAI se configura con la función openaiCompatible(): establezca baseURL, apiKey y la lista de modelos una vez, y luego seleccione el modelo para cada llamada. Nuestro Gateway utiliza el formato de "Chat Completions", por lo que dejamos api: 'chat-completions' (este es el valor predeterminado).

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

// Proveedor Gonka — configurado una vez
export const gonka = openaiCompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY!, // jg-tu-clave
  api: 'chat-completions',
  models: [
    'Qwen/Qwen3-235B-A22B-Instruct-2507-FP8', // por defecto
    'moonshotai/Kimi-K2.6',
    'MiniMaxAI/MiniMax-M2.7',
  ],
})

Chat en streaming en el servidor (por ejemplo, un controlador de ruta en cualquier framework fullstack o TanStack Start). La longitud de la respuesta se establece a través de modelOptions; este es el único punto para los parámetros "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 }, // límite de Qwen a través de Gateway
  })

  return toServerSentEventsResponse(stream)
}

Cliente React a través del hook useChat, transmite las respuestas del servidor a la interfaz de usuario:

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('¿Qué es Gonka?')}>
        Preguntar
      </button>
    </div>
  )
}

Sin servidor: el mismo proveedor funciona en un script o backend directamente – llame a chat() y lea el flujo. La conexión a Gonka es la misma para todas las opciones.

Parámetros de los modelos a través de Gateway: el contexto de los tres modelos es de 128K tokens. Límite de max_tokens: Qwen3-235B – 8192, Kimi K2.6 – 3072, MiniMax-M2.7 – 4096. Si max_tokens no se especifica, el valor predeterminado para no-streaming es 1500, por lo que para respuestas largas, especifíquelo explícitamente.

TanStack AI funciona igualmente bien con tarifas directas de OpenAI/Anthropic y a través de Gonka — solo cambia la baseURL. Pero el precio difiere por órdenes de magnitud. Compare las cargas típicas de una aplicación de producción en TanStack AI:

El enfoque agnóstico del proveedor de TanStack AI significa que cambiar a Gonka es un cambio de una sola línea (baseURL), no una reescritura de código. Sus herramientas tipadas, salida estructurada y hooks de React permanecen sin cambios. Para una aplicación con miles de usuarios, la diferencia es de decenas de miles de dólares al mes.

Precio de Gonka: entrada ~$0.0005 por 1 millón de tokens, salida ×3. Esto es cientos a miles de veces más barato que las tarifas directas de OpenAI y Anthropic.

La característica principal de TanStack AI es el contrato unificado toolDefinition(): la herramienta se describe una vez (entrada/salida a través de Zod, ArkType, Valibot o JSON Schema), y la implementación se vincula en el servidor o cliente. Qwen3-235B, Kimi K2.6 y MiniMax-M2.7 admiten la invocación de herramientas nativa a través de Gonka, por lo que los agentes funcionan de manera confiable, sin analizar las respuestas de texto.

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

const getWeather = toolDefinition({
  name: 'getWeather',
  description: 'Obtener el clima en una ciudad',
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ tempC: z.number() }),
}).server(async ({ city }) => {
  return { tempC: 21 } // su llamada a la API real
})

const stream = chat({
  adapter: gonka('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
  messages: [{ role: 'user', content: '¿Qué tiempo hace en Moscú?' }],
  tools: [getWeather],
  modelOptions: { max_tokens: 8192 },
})

Qué modelo elegir:

• Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 — por defecto. El techo de respuesta más grande (8192) y una potente invocación de herramientas. Adecuado para agentes y salida estructurada.
• moonshotai/Kimi-K2.6 — excelente para diálogos largos y razonamiento. Techo de respuesta 3072.
• MiniMaxAI/MiniMax-M2.7 — equilibrio de velocidad y calidad, techo 4096.

Gracias al cambio de adaptador en tiempo de ejecución en TanStack AI, puede mantener los tres modelos en un solo proveedor y cambiar entre ellos sobre la marcha, por ejemplo, tareas de agente pesadas en Qwen, respuestas rápidas en MiniMax.