@pollinations_ai/sdk

Official SDK for pollinations.ai - Generate images, text, audio, and video with one simple package.

Installation

npm install @pollinations_ai/sdk

Quick Start

First, get your API key at https://enter.pollinations.ai and set it:

export POLLINATIONS_API_KEY=your_api_key

Then:

import { generateImage, generateText } from '@pollinations_ai/sdk';

// Generate an image
const image = await generateImage('a futuristic cityscape');
await image.saveToFile('cityscape.png');

// Generate text
const text = await generateText('explain quantum computing in simple terms');
console.log(text);

Complete Beginner Example

New to coding? Here's a complete file you can copy-paste and run:

// save this as: my-first-ai.mjs
// First run: export POLLINATIONS_API_KEY=your_api_key

import { generateText, generateImage } from '@pollinations_ai/sdk';

async function main() {
  // Generate text
  const poem = await generateText('write a short poem about robots');
  console.log('Generated poem:');
  console.log(poem);

  // Generate an image
  const image = await generateImage('a friendly robot waving hello');
  await image.saveToFile('robot.png');
  console.log('Image saved to robot.png!');
}

main();

Run it with:

export POLLINATIONS_API_KEY=your_api_key
node my-first-ai.mjs

Browser Example

<script type="module">
  import { configure, generateText, generateImage } from 'https://esm.sh/@pollinations_ai/sdk';

  // Set your API key
  configure({ apiKey: 'your_api_key' });

  // Generate text
  const text = await generateText('write a haiku');

  // Generate image
  const image = await generateImage('a cute robot');

  // Display both
  document.body.innerHTML = `
    <p>${text}</p>
    <img src="${image.toDataURL()}">
  `;
</script>

API Key

An API key is required. Get one for free at https://enter.pollinations.ai

import { configure } from '@pollinations_ai/sdk';

configure({ apiKey: 'your_api_key' });

Or set the environment variable:

export POLLINATIONS_API_KEY=your_api_key

Image Generation

import { generateImage, imageUrl } from '@pollinations_ai/sdk';

// Generate and save
const image = await generateImage('a robot painting', {
  model: 'flux',
  width: 1920,
  height: 1080,
});
await image.saveToFile('robot.png');

// Get as base64 or data URL
const base64 = image.toBase64();
const dataUrl = image.toDataURL();

// Generate multiple images
const images = await generateImage('abstract art', { n: 4 });
images.forEach((img, i) => img.saveToFile(`art-${i}.png`));

// Just get the URL (no download)
const url = await imageUrl('a sunset');

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | model | string | 'flux' | Model to use | | width | number | 1024 | Width in pixels | | height | number | 1024 | Height in pixels | | seed | number | random | Reproducible results | | enhance | boolean | false | AI prompt enhancement | | negativePrompt | string | - | What to avoid in the image | | nologo | boolean | false | Remove watermark | | private | boolean | false | Keep generation private | | safe | boolean | false | Safety filter | | quality | string | 'medium' | 'low', 'medium', 'high', 'hd' | | referenceImage | string | - | URL for image-to-image | | transparent | boolean | false | Transparent background (PNG) | | guidanceScale | number | - | Prompt strictness (1-20) | | n | number | 1 | Number of images |

Text Generation

import { generateText, generateTextStream } from '@pollinations_ai/sdk';

// Simple
const text = await generateText('write a poem about coding');

// With options
const story = await generateText('explain gravity', {
  model: 'openai',
  systemPrompt: 'You are a physics teacher',
});

// Multiple responses
const facts = await generateText('give me a random fact', { n: 3 });

// Streaming
for await (const chunk of generateTextStream('tell me a story')) {
  process.stdout.write(chunk);
}

// Full response with metadata
const result = await generateText('hello', { raw: true });
console.log(result.text);
console.log(result.tokens);      // { input, output, total }
console.log(result.actualModel); // actual model used

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | model | string | 'openai' | Model to use | | systemPrompt | string | - | System prompt | | temperature | number | 1 | Creativity (0-2) | | maxTokens | number | - | Max output tokens | | frequencyPenalty | number | - | Reduce repetition (-2 to 2) | | presencePenalty | number | - | Encourage new topics (-2 to 2) | | seed | number | random | Reproducible results | | json | boolean | false | JSON output mode | | private | boolean | false | Keep generation private | | n | number | 1 | Number of responses | | raw | boolean | false | Return full response |

Chat

import { chat, chatStream, conversation } from '@pollinations_ai/sdk';

// Single message
const response = await chat([
  { role: 'system', content: 'You are a helpful assistant' },
  { role: 'user', content: 'What is 2+2?' }
]);
console.log(response.text);

// Streaming
for await (const chunk of chatStream([{ role: 'user', content: 'Write a poem' }])) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

// Conversation (auto-manages history)
const convo = conversation({ model: 'openai' });
convo.system('You are a pirate');

const r1 = await convo.say('Hello!');        // "Ahoy, matey!"
const r2 = await convo.say('Where are we?'); // Remembers context

console.log(convo.getHistory()); // Full message history
convo.clear(); // Reset conversation

Video Generation

import { generateVideo } from '@pollinations_ai/sdk';

const video = await generateVideo('a timelapse of clouds', {
  model: 'veo',
  duration: 6,
});
await video.saveToFile('clouds.mp4');

// Multiple videos
const videos = await generateVideo('ocean waves', { n: 2, duration: 4 });

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | model | string | 'veo' | 'veo' or 'seedance' | | duration | number | - | veo: 4, 6, or 8 sec / seedance: 2-10 sec | | aspectRatio | string | - | e.g. '16:9', '9:16', '1:1' | | seed | number | random | Reproducible results | | audio | boolean | false | Include audio (veo only) | | referenceImage | string | - | URL for image-to-video | | private | boolean | false | Keep generation private | | nologo | boolean | false | Remove watermark | | safe | boolean | false | Safety filter | | n | number | 1 | Number of videos |

Audio (Text-to-Speech)

import { generateAudio } from '@pollinations_ai/sdk';
import { writeFileSync } from 'fs';

const audio = await generateAudio('Hello, welcome!', {
  voice: 'nova',
});

// Save to file (Node.js)
writeFileSync('welcome.mp3', Buffer.from(audio.data, 'base64'));

// Play in browser
const audioEl = new Audio(`data:audio/mp3;base64,${audio.data}`);
audioEl.play();

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | voice | string | 'alloy' | Voice to use | | model | string | 'openai-audio' | Model to use | | format | string | 'mp3' | 'mp3', 'wav', 'flac', 'opus', 'pcm16' | | seed | number | random | Reproducible results | | n | number | 1 | Number of outputs |

Vision (Image Input)

import { chat } from '@pollinations_ai/sdk';

const response = await chat([
  {
    role: 'user',
    content: [
      { type: 'text', text: 'What is in this image?' },
      { type: 'image_url', image_url: { url: 'https://example.com/photo.jpg' } }
    ]
  }
]);

List Available Models

import { getTextModels, getImageModels } from '@pollinations_ai/sdk';

const textModels = await getTextModels();
const imageModels = await getImageModels();

console.log(textModels.map(m => m.name));

Error Handling

import { generateImage, PollinationsError } from '@pollinations_ai/sdk';

try {
  const image = await generateImage('test');
} catch (err) {
  if (err instanceof PollinationsError) {
    console.error(err.message);  // Error message
    console.error(err.code);     // Error code
    console.error(err.status);   // HTTP status
  }
}

Advanced: Client Class

import { Pollinations } from '@pollinations_ai/sdk';

const client = new Pollinations({ apiKey: 'your_key' });

const imageResponse = await client.image('a sunset');
const text = await client.text('hello');
const chatResponse = await client.chat([{ role: 'user', content: 'hi' }]);

TypeScript

Full TypeScript support with exported types:

import type {
  ImageGenerateOptions,
  TextGenerateOptions,
  ChatOptions,
  Message,
  ImageResponseExt,
  ChatResponseExt,
} from '@pollinations_ai/sdk';

API Reference

| Function | Description | |----------|-------------| | generateImage(prompt, options?) | Generate image(s) | | imageUrl(prompt, options?) | Get image URL | | generateText(prompt, options?) | Generate text | | generateTextStream(prompt, options?) | Stream text | | chat(messages, options?) | Chat completion | | chatStream(messages, options?) | Stream chat | | conversation(options?) | Create conversation | | generateVideo(prompt, options?) | Generate video(s) | | videoUrl(prompt, options?) | Get video URL | | generateAudio(text, options?) | Text to speech | | getTextModels() | List text models | | getImageModels() | List image models | | getModels() | List all models | | configure({ apiKey }) | Set global config |

Troubleshooting

"saveToFile is only available in Node.js"

If you're in a browser, use toDataURL() or toBase64() instead:

const image = await generateImage('a cat');
const dataUrl = image.toDataURL();  // Use this for <img src="">
const base64 = image.toBase64();    // Raw base64 string

Request Timeout

Default timeouts: text/chat 5min, images 10min, videos 10min. For custom timeouts:

import { Pollinations } from '@pollinations_ai/sdk';

const client = new Pollinations({
  timeout: 600000,       // 10 minutes for all requests
  textTimeout: 300000,   // 5 minutes for text
  imageTimeout: 600000,  // 10 minutes for images
  videoTimeout: 900000,  // 15 minutes for videos
});

Rate Limiting

Publishable keys (pk_) have rate limits. Use a secret key (sk_) for unlimited requests.

Network Errors

The SDK automatically retries failed requests up to 3 times. To customize:

import { Pollinations } from '@pollinations_ai/sdk';

const client = new Pollinations({
  maxRetries: 5,  // Retry up to 5 times
});

Links

• Pollinations.AI
• API Documentation - Full API reference
• Get API Key
• Discord
• GitHub

License

MIT