Proveedor del Vercel AI SDK

@popnow/ai-sdk-provider conecta los modelos de PopNow con el Vercel AI SDK. Con una sola clave de API llamas a los modelos de generación y edición de imágenes con generateImage, a texto a voz con generateSpeech, a voz a texto con transcribe, y a los modelos de chat con generateText y streamText. Todo se factura en USD desde tu saldo de la API, que es independiente.

El paquete es de código abierto bajo licencia MIT (GitHub). Requiere AI SDK 7 (ai@^7) y Node.js 22 o más reciente.

De un vistazo

Configuración

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

Ajustes del proveedor

Para otros ajustes, crea tu propia instancia 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 también acepta una función fetch personalizada.

Edita una imagen

Los modelos de edición tienen IDs que terminan en /edit. Pasa las imágenes de origen y, cuando el modelo lo admite, una máscara dentro del 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'],
  },
});

Las URL se pasan tal cual. Las imágenes dadas como bytes o base64 se envían en línea si son JPEG, PNG, WebP o GIF de como máximo 1 MiB; si no, se suben a PopNow.

Cómo se asignan los ajustes a PopNow

Cada modelo de PopNow valida su input con su propio JSON Schema y rechaza los campos desconocidos. El proveedor lee el esquema del modelo (GET /api/v1/models/{model}, en caché durante diez minutos) y solo envía un ajuste cuando el modelo tiene el campo correspondiente:

Un ajuste que el modelo no tiene se omite y se informa en warnings como unsupported. Cualquier otro campo del modelo va en providerOptions.popnow, escrito exactamente como en el esquema del modelo (snake_case), por ejemplo resolution, output_format o quality. Estos valores sustituyen a los asignados.

Texto a voz

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 se asigna a voice_id, outputFormat a output_format, y instructions, speed y language a campos con el mismo nombre, cuando el modelo los tiene. El esquema de cada modelo lista las voces que acepta.

Transcripción

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

Los bytes de audio se suben primero a PopNow (MP3 y WAV, hasta 90 MiB). Una URL pública https:// (audio: new URL('https://...')) se pasa directamente a PopNow sin descargarla.

Modelos de chat

PopNow sirve los modelos de chat a través de una API compatible con OpenAI en https://api.popnow.ai/v1. El proveedor usa @ai-sdk/openai-compatible para ellos, con la misma clave de API y el mismo 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 funciona con el mismo modelo:

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

Los modelos de chat se cobran por token, sin mínimo por solicitud. Modelos de chat lista todos los modelos y los parámetros que aceptan.

IDs de modelo

Los IDs de modelo tienen la forma <maker>/<model>/<task>, por ejemplo google/nano-banana-2.1/text-to-image, openai/tts-1/text-to-speech u openai/whisper-1/speech-to-text. Los tipos de TypeScript sugieren algunos; cualquier ID que tu clave pueda llamar funciona. Modelos lista todos los modelos con sus parámetros y precios. Para listarlos desde código, con sus esquemas de entrada:

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

modality es image, video o audio. Los modelos de chat se listan en GET https://api.popnow.ai/v1/models.

Precios

Los precios se expresan en USD por imagen, por segundo o por 1.000 caracteres, según el modelo, y se muestran en Modelos y en la página de cada modelo. El índice de precios de IA también los lista. Cada tarea retiene su precio máximo del saldo de la API al ser aceptada y liquida el cargo real al terminar. Las tareas fallidas o caducadas no se cobran. Detalles: Facturación y cotizaciones.

Cada entrada de imagen en providerMetadata.popnow.images incluye el taskId, su costUsd (una cadena decimal en USD) y si el cargo está settled. Los resultados de voz y transcripción llevan los mismos campos en providerMetadata.popnow.

Tareas, consultas y reintentos

La generación de PopNow es asíncrona. Cada llamada crea una tarea, espera hasta 60 segundos en la solicitud de creación y luego consulta la tarea (cada 2 segundos al principio, aumentando hasta cada 15 segundos) hasta que sea definitiva; después descarga los archivos de salida desde sus enlaces firmados. La clave de API nunca se envía a esos enlaces.

Estas opciones van en providerOptions.popnow y no se envían al modelo:

Cada solicitud de creación lleva un Idempotency-Key. Los errores de conexión, 429 y los 5xx reintentables se reintentan dos veces con la misma clave, así que un reintento nunca inicia una segunda tarea. Cuando pasas tu propio idempotencyKey, los reintentos del AI SDK (maxRetries) también lo reutilizan. Consulta Idempotencia.

abortSignal deja de esperar de inmediato. Una tarea ya aceptada sigue ejecutándose en PopNow.

Errores

• APICallError (de @ai-sdk/provider) para errores de la API. El mensaje incluye el código de negocio de PopNow, como 40201 (saldo de la API insuficiente) o 40301 (la clave puede no llamar a este modelo). Consulta Errores.
• PopNowTaskError cuando una tarea termina como failed o expired. Tiene taskId, state, errorCode (por ejemplo content_rejected), errorMessage y costUsd. Estas tareas no se cobran.
• PopNowTaskTimeoutError cuando se agota pollTimeoutMs. Tiene taskId; la tarea sigue ejecutándose.

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

No incluido

• Video. La interfaz de modelos de video del AI SDK sigue siendo experimental (experimental_generateVideo), así que este paquete todavía no la implementa. Los modelos de video de PopNow están disponibles a través de la API de tareas, los SDK oficiales y los endpoints compatibles con OpenAI Videos.
• Embeddings. embeddingModel lanza NoSuchModelError.

¿Qué versión de AI SDK necesita?

AI SDK 7 (ai@^7) con Node.js 22 o más reciente. Instala ambos con npm install @popnow/ai-sdk-provider ai.

¿Puedo llamarlo desde el navegador?

No con tu clave de API en la página: cualquiera que pueda leer la clave puede gastar tu saldo de la API. Llama al AI SDK desde una ruta del servidor, como un route handler de Next.js o una server action, y envía el resultado al navegador.

¿Admite modelos de video?

Todavía no, porque la interfaz de video del AI SDK sigue siendo experimental. Para video, usa la API de tareas o el SDK de JavaScript.

¿Cómo veo cuánto costó una llamada?

Lee providerMetadata.popnow: cada tarea informa su taskId, su costUsd y si el cargo está settled. La consola de API muestra el uso por clave.

Relacionados