Vercel AI SDK + Gonka AI — Aplicações de IA em TypeScript por centavos

Chave API JoinGonka: registre-se em gate.joingonka.ai/register — no início, damos 10M de tokens gratuitos. No Dashboard, crie uma chave com o prefixo jg-.

Instalação de pacotes. Para um endpoint personalizado compatível com OpenAI, o Vercel AI SDK recomenda o provedor @ai-sdk/openai-compatible:

npm install ai @ai-sdk/openai-compatible

Conexão mínima — criamos uma instância do provedor via createOpenAICompatible e chamamos 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-sua-chave
});

const { text } = await generateText({
  model: gonka('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
  prompt: 'Explique o que é uma rede descentralizada de inferência',
});

console.log(text);

O parâmetro apiKey adiciona automaticamente o cabeçalho Authorization: Bearer jg-sua-chave — nenhuma configuração adicional é necessária. Armazene a chave em uma variável de ambiente GONKA_API_KEY (por exemplo, em .env.local), e não no código.

Alternativa — pacote @ai-sdk/openai com a fábrica createOpenAI({ baseURL, apiKey }). Ambos os métodos funcionam; para endpoints que não pertencem à OpenAI, a documentação do AI SDK recomenda @ai-sdk/openai-compatible — ele não introduz suposições desnecessárias específicas da OpenAI.

A principal característica do Vercel AI SDK é o streaming de resposta. A função streamText começa a transmitir tokens imediatamente, e o helper toUIMessageStreamResponse() entrega o fluxo pronto diretamente do manipulador de rota no Next.js App Router.

Manipulador de 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,
});

// permitir streaming por até 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: 'Você é um assistente útil. Responda de forma concisa e direta.',
    messages: convertToModelMessages(messages),
    maxOutputTokens: 8192, // limite do Qwen3-235B via Gateway
  });

  return result.toUIMessageStreamResponse();
}

No cliente, conecte o hook useChat de @ai-sdk/react — ele mesmo faz a requisição para /api/chat e renderiza o fluxo de mensagens. O backend, por sua vez, acessa a Gonka, e não a OpenAI.

Script sem UI (Node, iterador assíncrono para o fluxo):

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: 'Escreva um haicai sobre computação distribuída',
});

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

Parâmetros do modelo. Três modelos estão disponíveis através do Gateway, todos com contexto de 128K tokens; o limite de resposta (maxOutputTokens) varia:

• Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 — padrão, até 8192 tokens de saída;
• moonshotai/Kimi-K2.6 — até 3072 (Kimi K2.6);
• MiniMaxAI/MiniMax-M2.7 — até 4096 (MiniMax M2.7).

Se maxOutputTokens não for especificado, para uma requisição não-stream o Gateway retornará por padrão até 1500 tokens — para chats de streaming, é melhor especificar o valor explicitamente.

O Vercel AI SDK geralmente é usado para interfaces interativas — chat, agente, assistente no aplicativo. Cada mensagem arrasta consigo o histórico da conversa, cada passo do agente — o contexto das ferramentas. Portanto, o custo real não é calculado por uma única solicitação, mas pela carga de produção. Vamos comparar cenários típicos:

O preço da JoinGonka é de cerca de US$ 0,0005 por 1M de tokens na entrada, a saída é aproximadamente três vezes mais cara. Para um aplicativo com milhares de requisições por dia, isso é a diferença entre uma conta de centenas de dólares e uma conta de centavos. Os 10M de tokens gratuitos são suficientes para executar e depurar completamente o projeto antes de lançá-lo em produção.

O Vercel AI SDK descreve as ferramentas de forma declarativa através do objeto tools e do esquema zod. O Qwen3-235B suporta tool calling nativo, então o AI SDK recebe tool_calls estruturadas sem analisar respostas de texto. O parâmetro stopWhen: stepCountIs(n) permite várias etapas consecutivas — o modelo chama a ferramenta, obtém o resultado e continua.

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: 'Obter previsão do tempo para a cidade',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ city, tempC: 17 }),
    }),
  },
  prompt: 'Qual é a previsão do tempo em Moscou? Responda em uma frase.',
});

console.log(text);

O modelo chama a ferramenta weather, obtém o resultado e forma a resposta final. Todo o ciclo custa cerca de US$ 0,00001 via Gonka contra US$ 0,03-0,10 da Anthropic ou OpenAI. Para aplicativos de agente, onde cada solicitação do usuário se desdobra em 5-10 etapas, a economia na produção é medida em milhares de dólares por mês.

Se você está construindo um aplicativo de IA em Python, consulte o guia sobre LangChain — lá, a abordagem é a mesma, através de uma classe compatível com OpenAI.