Heli + Vercel AI SDK: провайдер OpenAI Compatible в Next.js

Подготовка

• Зарегистрируйтесь на getheli.ru (подтверждение почты или вход через Google / Яндекс ID) и создайте ключ на вкладке «Ключи» кабинета.
• Установите пакеты: npm install ai @ai-sdk/openai-compatible.
• Положите ключ в переменную окружения HELI_API_KEY — в .env.local для разработки и в настройках окружения на хостинге. Без префикса NEXT_PUBLIC_: ключ должен оставаться только на сервере.
• Создайте экземпляр провайдера с name, baseURL https://getheli.ru/v1 и apiKey. SDK сам добавит заголовок Authorization: Bearer.
• Вызывайте модели только из серверного кода: route handler, server action или отдельный backend.

Пример: route handler в Next.js

Для чата с хуком useChat используйте streamText с тем же провайдером и хелпер отдачи UI-стрима из вашей версии AI SDK: их имена менялись между мажорными версиями, актуальный вариант — в разделе Chatbot документации SDK. Флаг supportsStructuredOutputs включайте, только если выбранная модель поддерживает JSON Schema.

// lib/heli.ts
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";

export const heli = createOpenAICompatible({
  name: "heli",
  baseURL: "https://getheli.ru/v1",
  apiKey: process.env.HELI_API_KEY,
  includeUsage: true,
});

// app/api/summary/route.ts
import { generateText } from "ai";
import { heli } from "@/lib/heli";

export async function POST(req: Request) {
  const { text } = await req.json();
  const result = await generateText({
    model: heli("google/gemini-3.5-flash"),
    prompt: "Кратко перескажи текст в трёх пунктах:\n" + text,
    maxRetries: 2,
    abortSignal: AbortSignal.timeout(60_000),
  });
  return Response.json({ summary: result.text });
}

Какие модели выбрать

В веб-приложении важна задержка первого токена, поэтому для пользовательских функций чаще берут быстрые модели, а сильные оставляют для сложных сценариев и агентов с инструментами.

Gemini 3.5 Flash — суммаризация, чат, классификация.

GPT-5.4 mini — недорогой tool calling и structured output.

Claude Sonnet 5 — агенты и длинные документы.

Частые ошибки

• 401 — HELI_API_KEY не задан в окружении деплоя или ключ отозван; проверьте переменную на хостинге и пересоберите проект.
• 402 insufficient_balance — закончился баланс; пополните его в кабинете.
• Модель не найдена — передавайте полный слаг с префиксом вендора, как в GET /v1/models.
• Таймауты на хостинге — у serverless-функций есть свой лимит длительности; для длинных ответов используйте стриминг.
• Ключ виден в браузере — провайдер создан в клиентском компоненте; перенесите вызов на сервер.
• Ответ не появляется по частям — route handler возвращает обычный JSON; для потокового вывода нужен streamText и потоковый ответ.

Документация API

Оплата — пополнение баланса.

Node.js и TypeScript + Heli