Vercel AI SDK + Gonka AI — Aplicaciones de IA en TypeScript por centavos

Clave API de JoinGonka: regístrese en gate.joingonka.ai/register — al inicio le damos 10M de tokens gratuitos. En el Dashboard, cree una clave con el prefijo jg-.

Instalación de paquetes. Para un endpoint personalizado compatible con OpenAI, Vercel AI SDK recomienda el proveedor @ai-sdk/openai-compatible:

npm install ai @ai-sdk/openai-compatible

Conexión mínima: creamos una instancia del proveedor a través de createOpenAICompatible y llamamos a generateText:

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY, // jg-tu-clave
});

const { text } = await generateText({
  model: gonka('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
  prompt: 'Explica qué es una red de inferencia descentralizada',
});

console.log(text);

El parámetro apiKey añade automáticamente el encabezado Authorization: Bearer jg-su-clave; no es necesaria una configuración adicional. Guarde la clave en una variable de entorno GONKA_API_KEY (por ejemplo, en .env.local), no en el código.

Alternativa: el paquete @ai-sdk/openai con la fábrica createOpenAI({ baseURL, apiKey }). Ambos métodos son válidos; para endpoints que no pertenecen a OpenAI, la documentación de AI SDK recomienda @ai-sdk/openai-compatible, ya que no arrastra supuestos innecesarios específicos de OpenAI.

La característica principal de Vercel AI SDK es la entrega de respuestas por streaming. La función streamText comienza a transmitir tokens de inmediato, y el helper toUIMessageStreamResponse() entrega un flujo listo directamente desde el route handler en Next.js App Router.

Handler del servidor app/api/chat/route.ts:

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { streamText, convertToModelMessages, type UIMessage } from 'ai';

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY,
});

// permitimos streaming hasta 30 segundos
export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const result = streamText({
    model: gonka('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
    system: 'Eres un asistente útil. Responde de forma concisa y al grano.',
    messages: convertToModelMessages(messages),
    maxOutputTokens: 8192, // límite de Qwen3-235B a través de Gateway
  });

  return result.toUIMessageStreamResponse();
}

En el cliente, conecte el hook useChat de @ai-sdk/react; este se encargará de comunicarse con /api/chat y renderizar el flujo de mensajes. El backend, en este caso, se comunicará con Gonka, no con OpenAI.

Script sin UI (Node, iterador asíncrono sobre el flujo):

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { streamText } from 'ai';

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY,
});

const result = streamText({
  model: gonka('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
  prompt: 'Escribe un haiku sobre computación distribuida',
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

Parámetros del modelo. A través de Gateway están disponibles tres modelos, todos con un contexto de 128K tokens; el límite de respuesta (maxOutputTokens) varía:

• Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 — predeterminado, hasta 8192 tokens de salida;
• moonshotai/Kimi-K2.6 — hasta 3072 (Kimi K2.6);
• MiniMaxAI/MiniMax-M2.7 — hasta 4096 (MiniMax M2.7).

Si no se especifica maxOutputTokens, para una solicitud no-stream, Gateway devolverá por defecto hasta 1500 tokens; para chats de streaming, es mejor especificar el valor explícitamente.

Vercel AI SDK suele estar detrás de una interfaz interactiva: chat, agente, asistente en la aplicación. Cada mensaje arrastra el historial del diálogo, cada paso del agente, el contexto de las herramientas. Por lo tanto, el coste real se calcula no por una única solicitud, sino por la carga de producción. Comparemos escenarios típicos:

El precio de JoinGonka es de aproximadamente $0.0005 por 1M de tokens de entrada, y la salida es aproximadamente tres veces más cara. Para una aplicación con miles de solicitudes al día, esto es la diferencia entre una factura de cientos de dólares y una factura de céntimos. Los 10M de tokens gratuitos son suficientes para ejecutar y depurar completamente un proyecto antes de lanzarlo a producción.

Vercel AI SDK describe las herramientas de forma declarativa a través del objeto tools y el esquema zod. Qwen3-235B admite function calling nativo, por lo que AI SDK recibe tool_calls estructurados sin analizar respuestas de texto. El parámetro stopWhen: stepCountIs(n) permite varios pasos consecutivos: el modelo llama a la herramienta, obtiene el resultado y continúa.

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText, tool, stepCountIs } from 'ai';
import { z } from 'zod';

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY,
});

const { text } = await generateText({
  model: gonka('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
  stopWhen: stepCountIs(5),
  tools: {
    weather: tool({
      description: 'Obtener el tiempo en la ciudad',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ city, tempC: 17 }),
    }),
  },
  prompt: '¿Qué tiempo hace en Madrid? Responde en una frase.',
});

console.log(text);

El modelo invoca la herramienta weather, obtiene el resultado y formula la respuesta final. Todo el ciclo cuesta alrededor de $0.00001 a través de Gonka en comparación con $0.03-0.10 con Anthropic u OpenAI. Para aplicaciones de agentes, donde cada consulta del usuario se desglosa en 5-10 pasos, el ahorro en producción se mide en miles de dólares al mes.

Si está construyendo una aplicación de IA en Python, consulte la guía de LangChain; allí se aplica el mismo enfoque a través de una clase compatible con OpenAI.