Provider Vercel AI SDK

@popnow/ai-sdk-provider łączy modele PopNow z Vercel AI SDK. Jednym kluczem API wywołujesz modele generowania i edycji obrazów przez generateImage, zamianę tekstu na mowę przez generateSpeech, zamianę mowy na tekst przez transcribe, a modele czatu przez generateText i streamText. Wszystko jest rozliczane w USD z twojego osobnego salda API.

Pakiet ma otwarty kod na licencji MIT (GitHub). Wymaga AI SDK 7 (ai@^7) i Node.js 22 lub nowszego.

Przegląd

Konfiguracja

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);

Ustawienia providera

Do pozostałych ustawień utwórz własną instancję przez 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 przyjmuje też własną funkcję fetch.

Edycja obrazu

Modele edycji mają ID kończące się na /edit. Przekaż obrazy źródłowe, a tam, gdzie model przyjmuje maskę, także maskę, w prompcie:

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'],
  },
});

Adresy URL są przekazywane bez zmian. Obrazy podane jako bajty lub base64 są wysyłane w treści żądania, gdy są to JPEG, PNG, WebP lub GIF o rozmiarze do 1 MiB; w pozostałych przypadkach są wgrywane do PopNow.

Jak ustawienia mapują się na PopNow

Każdy model PopNow sprawdza swoje input według własnego JSON Schema i odrzuca nieznane pola. Provider czyta schemat modelu (GET /api/v1/models/{model}, w pamięci podręcznej przez dziesięć minut) i wysyła ustawienie tylko wtedy, gdy model ma odpowiadające mu pole:

Ustawienie, którego model nie ma, jest pomijane i zgłaszane w warnings jako unsupported. Każde inne pole modelu idzie do providerOptions.popnow, zapisane dokładnie tak jak w schemacie modelu (snake_case), na przykład resolution, output_format albo quality. Te wartości nadpisują zmapowane.

Zamiana tekstu na mowę

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 odpowiada voice_id, outputFormat odpowiada output_format, a instructions, speed i language trafiają do pól o tej samej nazwie, jeśli model je ma. Schemat każdego modelu wymienia głosy, które przyjmuje.

Transkrypcja

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);

Bajty audio są najpierw wgrywane do PopNow (MP3 i WAV, do 90 MiB). Publiczny adres https:// (audio: new URL('https://...')) jest przekazywany do PopNow bezpośrednio, bez pobierania.

Modele czatu

PopNow udostępnia modele czatu przez API zgodne z OpenAI pod adresem https://api.popnow.ai/v1. Provider używa do nich @ai-sdk/openai-compatible, z tym samym kluczem API i tym samym saldem:

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 działa z tym samym modelem:

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);

Modele czatu są wyceniane za token, bez minimum za żądanie. Modele czatu wymieniają wszystkie modele i parametry, które przyjmują.

ID modeli

ID modeli mają postać <maker>/<model>/<task>, na przykład google/nano-banana-2.1/text-to-image, openai/tts-1/text-to-speech albo openai/whisper-1/speech-to-text. Typy TypeScript podpowiadają kilka z nich; działa każde ID, które twój klucz może wywołać. Modele wymieniają wszystkie modele z parametrami i cenami. Aby pobrać je z kodu razem ze schematami wejścia:

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

modality to image, video lub audio. Modele czatu są listowane pod GET https://api.popnow.ai/v1/models.

Ceny

Ceny są podane w USD za obraz, za sekundę albo za 1000 znaków, zależnie od modelu, i widać je na Modelach oraz na stronie każdego modelu. Indeks cen AI też je zawiera. Każde zadanie blokuje maksymalną cenę z twojego salda API w chwili przyjęcia i rozlicza rzeczywistą kwotę po zakończeniu. Zadania nieudane lub wygasłe nie są naliczane. Szczegóły: Rozliczenia API i wyceny.

Każdy wpis obrazu w providerMetadata.popnow.images zawiera taskId, costUsd (dziesiętny ciąg znaków w USD) i to, czy opłata jest settled, czyli rozliczona. Wyniki syntezy mowy i transkrypcji niosą te same pola w providerMetadata.popnow.

Zadania, odpytywanie i ponowienia

Generowanie PopNow jest asynchroniczne. Każde wywołanie tworzy zadanie, czeka do 60 sekund na żądanie utworzenia, potem odpytuje zadanie (najpierw co 2 sekundy, z czasem co 15 sekund), aż będzie ostateczne, i pobiera pliki wynikowe z podpisanych linków. Klucz API nigdy nie jest wysyłany na te linki.

Te opcje idą w providerOptions.popnow i nie są wysyłane do modelu:

Każde żądanie utworzenia niesie nagłówek Idempotency-Key. Błędy połączenia, odpowiedzi 429 i powtarzalne 5xx są ponawiane dwukrotnie z tym samym kluczem, więc ponowienie nigdy nie uruchamia drugiego zadania. Gdy podajesz własny idempotencyKey, własne ponowienia AI SDK (maxRetries) też go używają. Zobacz Idempotencja.

abortSignal natychmiast przerywa czekanie. Zadanie, które zostało już przyjęte, dalej działa w PopNow.

Błędy

• APICallError (z @ai-sdk/provider) dla błędów API. Komunikat zawiera kod biznesowy PopNow, na przykład 40201 (za mało salda API) lub 40301 (klucz nie może wywołać tego modelu). Zobacz Kody błędów.
• PopNowTaskError, gdy zadanie kończy się statusem failed lub expired. Ma pola taskId, state, errorCode (na przykład content_rejected), errorMessage i costUsd. Takie zadania nie są naliczane.
• PopNowTaskTimeoutError, gdy skończy się pollTimeoutMs. Ma pole taskId; zadanie działa dalej.

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);
}

Czego nie obejmuje

• Wideo. Interfejs modeli wideo AI SDK jest wciąż eksperymentalny (experimental_generateVideo), dlatego ten pakiet jeszcze go nie implementuje. Modele wideo PopNow są dostępne przez API zadań, oficjalne SDK i endpointy wideo zgodne z OpenAI.
• Embeddingi. embeddingModel zgłasza NoSuchModelError.

Jakiej wersji AI SDK wymaga?

AI SDK 7 (ai@^7) na Node.js 22 lub nowszym. Zainstaluj oba pakiety poleceniem npm install @popnow/ai-sdk-provider ai.

Czy mogę wywoływać to z przeglądarki?

Nie z kluczem API na stronie: każdy, kto może go odczytać, może wydać twoje saldo API. Wywołuj AI SDK z trasy serwerowej, na przykład handlera trasy Next.js albo server action, i przekaż wynik do przeglądarki.

Czy obsługuje modele wideo?

Jeszcze nie, bo interfejs wideo AI SDK jest wciąż eksperymentalny. Do wideo użyj API zadań albo SDK dla JavaScriptu.

Jak sprawdzić, ile kosztowało wywołanie?

Odczytaj providerMetadata.popnow: każde zadanie podaje swój taskId, costUsd i to, czy opłata jest settled. Konsola API pokazuje zużycie według klucza.

Powiązane