Провайдер Vercel AI SDK

@popnow/ai-sdk-provider подключает модели PopNow к Vercel AI SDK. С одним ключом API вы вызываете модели генерации и правки изображений через generateImage, синтез речи через generateSpeech, распознавание речи через transcribe, а чат-модели через generateText и streamText. Всё оплачивается в USD с вашего отдельного баланса API.

Пакет распространяется под лицензией MIT с открытым кодом (GitHub). Он требует AI SDK 7 (ai@^7) и Node.js 22 или новее.

Обзор

Настройка

npm install @popnow/ai-sdk-provider ai

export POPNOW_API_KEY="sk-popnow-..."

import { popnow } from '@popnow/ai-sdk-provider';
import { generateImage } from 'ai';
import fs from 'node:fs';

const { image } = await generateImage({
  model: popnow.image('google/nano-banana-2.1/text-to-image'),
  prompt: 'A cozy reading nook beside a rain-streaked window, warm lamp light',
  aspectRatio: '16:9',
  providerOptions: {
    popnow: { resolution: '2k' },
  },
});

await fs.promises.writeFile('nook.png', image.uint8Array);

Настройки провайдера

Для других настроек создайте собственный экземпляр через createPopNow:

import { createPopNow } from '@popnow/ai-sdk-provider';

const popnow = createPopNow({
  apiKey: process.env.POPNOW_API_KEY, // default: POPNOW_API_KEY
  baseURL: 'https://api.popnow.ai', // default: POPNOW_BASE_URL or https://api.popnow.ai
  headers: { 'X-PopNow-Tags': 'my-app' }, // optional, sent with every request
});

createPopNow также принимает собственную функцию fetch.

Правка изображения

ID моделей правки оканчиваются на /edit. Передавайте исходные изображения, а там, где модель принимает маску, и маску — в промпте:

import { popnow } from '@popnow/ai-sdk-provider';
import { generateImage } from 'ai';

const { image } = await generateImage({
  model: popnow.image('google/nano-banana-2.1/edit'),
  prompt: {
    text: 'Change the jacket to deep forest green; keep the face and background',
    images: ['https://example.com/portrait.jpg'],
  },
});

URL передаются как есть. Изображения в виде байтов или base64 отправляются в запросе напрямую, если это JPEG, PNG, WebP или GIF размером не больше 1 МиБ; в остальных случаях они загружаются в PopNow.

Как настройки соответствуют PopNow

Каждая модель PopNow проверяет свой input по собственной JSON Schema и отклоняет неизвестные поля. Провайдер читает схему модели (GET /api/v1/models/{model}, кэш на десять минут) и отправляет настройку только тогда, когда у модели есть соответствующее поле:

Настройка, которой у модели нет, пропускается и попадает в warnings как unsupported. Любое другое поле модели передаётся в providerOptions.popnow и пишется точно так же, как в схеме модели (snake_case), например resolution, output_format или quality. Эти значения переопределяют сопоставленные.

Синтез речи

import { popnow } from '@popnow/ai-sdk-provider';
import { generateSpeech } from 'ai';
import fs from 'node:fs';

const { audio } = await generateSpeech({
  model: popnow.speech('openai/tts-1/text-to-speech'),
  text: 'Hello from PopNow.',
  voice: 'nova',
  speed: 1.1,
});

await fs.promises.writeFile('hello.mp3', audio.uint8Array);

voice соответствует voice_id, outputFormat — output_format, а instructions, speed и language передаются полям с такими же именами, если они есть у модели. Схема каждой модели перечисляет голоса, которые она принимает.

Распознавание речи

import { popnow } from '@popnow/ai-sdk-provider';
import { transcribe } from 'ai';
import fs from 'node:fs';

const result = await transcribe({
  model: popnow.transcription('openai/whisper-1/speech-to-text'),
  audio: await fs.promises.readFile('meeting.mp3'),
  providerOptions: { popnow: { language: 'en' } },
});

console.log(result.text, result.words);

Аудиобайты сначала загружаются в PopNow (MP3 и WAV, до 90 МиБ). Публичный URL https:// (audio: new URL('https://...')) передаётся в PopNow напрямую, без скачивания.

Чат-модели

PopNow предоставляет чат-модели через совместимый с OpenAI API по адресу https://api.popnow.ai/v1. Для них провайдер использует @ai-sdk/openai-compatible, с тем же ключом API и тем же балансом:

import { popnow } from '@popnow/ai-sdk-provider';
import { generateText } from 'ai';

const { text } = await generateText({
  model: popnow('anthropic/claude-haiku-5.5/chat'),
  prompt: 'Suggest three names for a kite shop by the sea.',
});

С той же моделью работает и streamText:

import { popnow } from '@popnow/ai-sdk-provider';
import { streamText } from 'ai';

const result = streamText({
  model: popnow('anthropic/claude-haiku-5.5/chat'),
  prompt: 'Write a short welcome message for a kite shop.',
});

for await (const delta of result.textStream) process.stdout.write(delta);

Чат-модели тарифицируются за токен, без минимума за запрос. На странице Чат-модели перечислены все модели и параметры, которые они принимают.

ID моделей

ID моделей имеют вид <maker>/<model>/<task>, например google/nano-banana-2.1/text-to-image, openai/tts-1/text-to-speech или openai/whisper-1/speech-to-text. Типы TypeScript подсказывают несколько ID; работает любой ID, который может вызывать ваш ключ. На странице Модели перечислены все модели с параметрами и ценами. Чтобы получить их списком из кода, со схемами входа:

curl "https://api.popnow.ai/api/v1/models?modality=image&includeSchema=1" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

modality — это image, video или audio. Чат-модели перечислены по адресу GET https://api.popnow.ai/v1/models.

Цены

Цены указаны в USD за изображение, за секунду или за 1 000 символов, в зависимости от модели; они показаны на странице Модели и на странице каждой модели. Индекс цен AI тоже их содержит. Каждая задача удерживает максимальную цену с вашего баланса API при принятии и окончательно списывает фактическую сумму по завершении. Задачи с ошибкой или истёкшие не оплачиваются. Подробности: Оплата API и расчёт стоимости.

Каждый элемент изображения в providerMetadata.popnow.images содержит taskId, costUsd (десятичную строку в USD) и признак settled — списана ли окончательная сумма. Результаты синтеза и распознавания несут те же поля в providerMetadata.popnow.

Задачи, опрос и повторы

Генерация PopNow асинхронна. Каждый вызов создаёт задачу, ждёт до 60 секунд на запрос создания, затем опрашивает задачу (сначала каждые 2 секунды, потом реже, до каждых 15 секунд), пока она не завершится окончательно, и скачивает файлы результата по подписанным ссылкам. Ключ API на эти ссылки никогда не отправляется.

Эти опции передаются в providerOptions.popnow и не отправляются модели:

Каждый запрос создания несёт заголовок Idempotency-Key. Ошибки соединения, ответы 429 и повторяемые 5xx повторяются дважды с тем же ключом, поэтому повтор никогда не запускает вторую задачу. Если вы передаёте свой idempotencyKey, собственные повторы AI SDK (maxRetries) тоже его используют. См. Идемпотентность.

abortSignal немедленно прекращает ожидание. Задача, которая уже принята, продолжает выполняться в PopNow.

Ошибки

• APICallError (из @ai-sdk/provider) для ошибок API. В сообщении указан бизнес-код PopNow, например 40201 (недостаточно баланса API) или 40301 (ключу нельзя вызывать эту модель). См. Коды ошибок.
• PopNowTaskError, когда задача завершается со статусом failed или expired. У неё есть taskId, state, errorCode (например, content_rejected), errorMessage и costUsd. Такие задачи не оплачиваются.
• PopNowTaskTimeoutError, когда заканчивается pollTimeoutMs. У неё есть taskId; задача продолжает выполняться.

import { popnow, PopNowTaskError } from '@popnow/ai-sdk-provider';
import { generateImage } from 'ai';

try {
  await generateImage({
    model: popnow.image('google/nano-banana-2.1/text-to-image'),
    prompt: 'A lighthouse at dawn, watercolor',
  });
} catch (error) {
  if (PopNowTaskError.isInstance(error)) console.log(error.taskId, error.errorCode);
}

Что не входит

• Видео. Интерфейс видеомоделей AI SDK ещё экспериментальный (experimental_generateVideo), поэтому этот пакет пока его не реализует. Видеомодели PopNow доступны через API задач, официальные SDK и совместимые с OpenAI эндпоинты видео.
• Эмбеддинги. embeddingModel выбрасывает NoSuchModelError.

Какая версия AI SDK нужна?

AI SDK 7 (ai@^7) на Node.js 22 или новее. Установите оба пакета командой npm install @popnow/ai-sdk-provider ai.

Можно ли вызывать из браузера?

Нет, если ключ API находится в странице: любой, кто может его прочитать, может потратить ваш баланс API. Вызывайте AI SDK из серверного маршрута, например обработчика маршрута Next.js или серверного действия, и передавайте результат в браузер.

Поддерживает ли он видеомодели?

Пока нет, потому что интерфейс видео в AI SDK ещё экспериментальный. Для видео используйте API задач или SDK для JavaScript.

Как посмотреть, сколько стоил вызов?

Читайте providerMetadata.popnow: каждая задача сообщает свой taskId, costUsd и признак settled. В консоли API видно расход по каждому ключу.

Связанное