Provedor do Vercel AI SDK

@popnow/ai-sdk-provider conecta os modelos do PopNow ao Vercel AI SDK. Com uma única chave de API, você chama modelos de geração e edição de imagem com generateImage, texto para fala com generateSpeech, fala para texto com transcribe, e modelos de chat com generateText e streamText. Tudo é cobrado em USD do seu saldo da API, que é separado.

O pacote é de código aberto sob licença MIT (GitHub). Ele requer o AI SDK 7 (ai@^7) e Node.js 22 ou mais recente.

Resumo

Configuração

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

Configurações do provedor

Para outras configurações, crie a sua própria instância com 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 também aceita uma função fetch personalizada.

Edite uma imagem

Os modelos de edição têm IDs que terminam em /edit. Passe as imagens de origem e, quando o modelo aceitar, uma máscara no 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'],
  },
});

URLs são passadas como estão. Imagens enviadas como bytes ou base64 vão em linha quando são JPEG, PNG, WebP ou GIF de no máximo 1 MiB; caso contrário, são enviadas ao PopNow.

Como as configurações viram campos do PopNow

Cada modelo do PopNow valida o seu input contra o próprio JSON Schema e rejeita campos desconhecidos. O provedor lê o schema do modelo (GET /api/v1/models/{model}, em cache por dez minutos) e só envia uma configuração quando o modelo tem o campo correspondente:

Uma configuração que o modelo não tem é deixada de fora e informada em warnings como unsupported. Qualquer outro campo do modelo vai em providerOptions.popnow, escrito exatamente como no schema do modelo (snake_case), por exemplo resolution, output_format ou quality. Esses valores substituem os mapeados.

Texto para fala

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 vira voice_id, outputFormat vira output_format, e instructions, speed e language viram campos de mesmo nome, quando o modelo os tem. O schema de cada modelo lista as vozes que ele aceita.

Transcrição

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

Os bytes de áudio são enviados ao PopNow primeiro (MP3 e WAV, até 90 MiB). Uma URL pública https:// (audio: new URL('https://...')) é passada diretamente ao PopNow, sem download.

Modelos de chat

O PopNow serve os modelos de chat por uma API compatível com OpenAI em https://api.popnow.ai/v1. O provedor usa @ai-sdk/openai-compatible para eles, com a mesma chave de API e o mesmo 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 com o mesmo 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);

Os modelos de chat são cobrados por token, sem mínimo por requisição. A página Modelos de chat lista todos os modelos e os parâmetros que aceitam.

IDs de modelo

Os IDs de modelo têm a forma <maker>/<model>/<task>, por exemplo google/nano-banana-2.1/text-to-image, openai/tts-1/text-to-speech ou openai/whisper-1/speech-to-text. Os tipos do TypeScript sugerem alguns; qualquer ID que a sua chave possa chamar funciona. Modelos lista todos os modelos com seus parâmetros e preços. Para listá-los no código, com os schemas de entrada:

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

modality é image, video ou audio. Os modelos de chat são listados em GET https://api.popnow.ai/v1/models.

Preços

Os preços são em USD por imagem, por segundo ou por 1.000 caracteres, dependendo do modelo, e aparecem em Modelos e na página de cada modelo. O índice de preços de IA também os lista. Cada tarefa reserva o preço máximo do seu saldo da API quando é aceita e liquida a cobrança real ao terminar. Tarefas com falha ou expiradas não são cobradas. Detalhes: Cobrança e cotações.

Cada entrada de imagem em providerMetadata.popnow.images traz o taskId, o costUsd (uma string decimal em USD) e se a cobrança está settled. Resultados de fala e transcrição trazem os mesmos campos em providerMetadata.popnow.

Tarefas, consultas e novas tentativas

A geração no PopNow é assíncrona. Cada chamada cria uma tarefa, espera até 60 segundos na requisição de criação e depois consulta a tarefa (a cada 2 segundos no início, aumentando até a cada 15 segundos) até que ela seja definitiva; então baixa os arquivos de saída pelos links assinados. A chave de API nunca é enviada a esses links.

Estas opções vão em providerOptions.popnow e não são enviadas ao modelo:

Cada requisição de criação leva um Idempotency-Key. Erros de conexão, 429 e 5xx que podem ser repetidos são tentados de novo duas vezes com a mesma chave, então uma nova tentativa nunca inicia uma segunda tarefa. Quando você passa a sua própria idempotencyKey, as novas tentativas do AI SDK (maxRetries) também a reutilizam. Veja Idempotência.

abortSignal para de esperar imediatamente. Uma tarefa já aceita continua rodando no PopNow.

Erros

• APICallError (de @ai-sdk/provider) para erros da API. A mensagem traz o código de negócio do PopNow, como 40201 (saldo da API insuficiente) ou 40301 (a chave pode não chamar este modelo). Veja Erros.
• PopNowTaskError quando uma tarefa termina como failed ou expired. Tem taskId, state, errorCode (por exemplo content_rejected), errorMessage e costUsd. Essas tarefas não são cobradas.
• PopNowTaskTimeoutError quando pollTimeoutMs se esgota. Tem taskId; a tarefa continua rodando.

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

Não incluído

• Vídeo. A interface de modelos de vídeo do AI SDK ainda é experimental (experimental_generateVideo), então este pacote ainda não a implementa. Os modelos de vídeo do PopNow estão disponíveis pela API de tarefas, pelos SDKs oficiais e pelos endpoints compatíveis com OpenAI Videos.
• Embeddings. embeddingModel lança NoSuchModelError.

Qual versão do AI SDK é necessária?

AI SDK 7 (ai@^7) com Node.js 22 ou mais recente. Instale os dois com npm install @popnow/ai-sdk-provider ai.

Posso chamar no navegador?

Não com a sua chave de API na página: quem puder ler a chave pode gastar o seu saldo da API. Chame o AI SDK a partir de uma rota do servidor, como um route handler do Next.js ou uma server action, e envie o resultado ao navegador.

Oferece suporte a modelos de vídeo?

Ainda não, porque a interface de vídeo do AI SDK é experimental. Para vídeo, use a API de tarefas ou o SDK de JavaScript.

Como vejo quanto uma chamada custou?

Leia providerMetadata.popnow: cada tarefa informa seu taskId, seu costUsd e se a cobrança está settled. O console de API mostra o uso por chave.

Relacionados