Provider Vercel AI SDK

@popnow/ai-sdk-provider collega i modelli PopNow al Vercel AI SDK. Con una sola chiave API richiami i modelli di generazione e modifica immagini con generateImage, la sintesi vocale con generateSpeech, il riconoscimento vocale con transcribe e i modelli di chat con generateText e streamText. Tutto viene fatturato in USD dal tuo saldo API separato.

Il pacchetto è open source con licenza MIT (GitHub). Richiede AI SDK 7 (ai@^7) e Node.js 22 o successivo.

In sintesi

Configurazione

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

Impostazioni del provider

Per altre impostazioni, crea la tua istanza con 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 accetta anche una funzione fetch personalizzata.

Modifica un'immagine

I modelli di modifica hanno ID che terminano con /edit. Passa le immagini di partenza e, quando il modello lo prevede, una maschera nel prompt:

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

Gli URL vengono passati così come sono. Le immagini fornite come byte o base64 vengono inviate in linea se sono JPEG, PNG, WebP o GIF di massimo 1 MiB; altrimenti vengono caricate su PopNow.

Come le impostazioni diventano campi PopNow

Ogni modello PopNow convalida il proprio input con il proprio JSON Schema e rifiuta i campi sconosciuti. Il provider legge lo schema del modello (GET /api/v1/models/{model}, in cache per dieci minuti) e invia un'impostazione solo quando il modello ha il campo corrispondente:

Un'impostazione che il modello non ha viene omessa e segnalata in warnings come unsupported. Qualsiasi altro campo del modello va in providerOptions.popnow, scritto esattamente come nello schema del modello (snake_case), per esempio resolution, output_format o quality. Questi valori sostituiscono quelli mappati.

Sintesi vocale

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 diventa voice_id, outputFormat diventa output_format, e instructions, speed e language diventano campi con lo stesso nome, quando il modello li ha. Lo schema di ogni modello elenca le voci che accetta.

Trascrizione

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

I byte audio vengono prima caricati su PopNow (MP3 e WAV, fino a 90 MiB). Un URL pubblico https:// (audio: new URL('https://...')) viene passato direttamente a PopNow senza scaricarlo.

Modelli di chat

PopNow serve i modelli di chat tramite un'API compatibile con OpenAI su https://api.popnow.ai/v1. Il provider usa @ai-sdk/openai-compatible per questi, con la stessa chiave API e lo stesso saldo:

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 funziona con lo stesso modello:

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

I modelli di chat sono tariffati per token, senza un minimo per richiesta. Modelli di chat elenca tutti i modelli e i parametri che accettano.

ID dei modelli

Gli ID dei modelli hanno la forma <maker>/<model>/<task>, per esempio google/nano-banana-2.1/text-to-image, openai/tts-1/text-to-speech o openai/whisper-1/speech-to-text. I tipi TypeScript ne suggeriscono alcuni; funziona qualsiasi ID che la tua chiave può chiamare. Modelli elenca tutti i modelli con i loro parametri e prezzi. Per elencarli da codice, con gli schemi di input:

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

modality è image, video o audio. I modelli di chat si elencano su GET https://api.popnow.ai/v1/models.

Prezzi

I prezzi sono in USD per immagine, per secondo o per 1.000 caratteri, a seconda del modello, e sono mostrati su Modelli e nella pagina di ogni modello. Anche l'indice dei prezzi IA li elenca. Ogni attività trattiene il prezzo massimo dal tuo saldo API quando viene accettata e salda l'addebito effettivo al termine. Le attività fallite o scadute non vengono addebitate. Dettagli: Fatturazione e preventivi.

Ogni voce immagine in providerMetadata.popnow.images riporta il taskId, il suo costUsd (una stringa decimale in USD) e se l'addebito è settled. I risultati di sintesi vocale e trascrizione riportano gli stessi campi in providerMetadata.popnow.

Attività, polling e ripetizioni

La generazione PopNow è asincrona. Ogni chiamata crea un'attività, attende fino a 60 secondi nella richiesta di creazione, poi interroga l'attività (ogni 2 secondi all'inizio, fino a ogni 15 secondi) finché non è definitiva, e scarica i file di output dai link firmati. La chiave API non viene mai inviata a quei link.

Queste opzioni vanno in providerOptions.popnow e non vengono inviate al modello:

Ogni richiesta di creazione porta un Idempotency-Key. Errori di connessione, 429 e 5xx ritentabili vengono ritentati due volte con la stessa chiave, quindi un nuovo tentativo non avvia mai una seconda attività. Quando passi una tua idempotencyKey, anche i tentativi del AI SDK (maxRetries) la riutilizzano. Vedi Idempotenza.

abortSignal smette subito di attendere. Un'attività già accettata continua a girare su PopNow.

Errori

• APICallError (da @ai-sdk/provider) per gli errori API. Il messaggio riporta il codice di business PopNow, come 40201 (saldo API insufficiente) o 40301 (la chiave potrebbe non poter chiamare questo modello). Vedi Errori.
• PopNowTaskError quando un'attività termina come failed o expired. Ha taskId, state, errorCode (per esempio content_rejected), errorMessage e costUsd. Queste attività non vengono addebitate.
• PopNowTaskTimeoutError quando scade pollTimeoutMs. Ha taskId; l'attività continua a girare.

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

Non incluso

• Video. L'interfaccia dei modelli video del AI SDK è ancora sperimentale (experimental_generateVideo), quindi questo pacchetto non la implementa ancora. I modelli video PopNow sono disponibili tramite la API delle attività, gli SDK ufficiali e gli endpoint compatibili con OpenAI Videos.
• Embedding. embeddingModel lancia NoSuchModelError.

Quale versione di AI SDK serve?

AI SDK 7 (ai@^7) su Node.js 22 o successivo. Installa entrambi con npm install @popnow/ai-sdk-provider ai.

Posso chiamarlo dal browser?

Non con la tua chiave API nella pagina: chiunque possa leggere la chiave può spendere il tuo saldo API. Chiama il AI SDK da una route del server, come un route handler di Next.js o una server action, e invia il risultato al browser.

Supporta i modelli video?

Non ancora, perché l'interfaccia video del AI SDK è sperimentale. Per i video usa la API delle attività o l'SDK JavaScript.

Come vedo quanto è costata una chiamata?

Leggi providerMetadata.popnow: ogni attività riporta il suo taskId, il suo costUsd e se l'addebito è settled. La console API mostra l'uso per chiave.

Correlati