# Pollinations API

> Generate text, images, video, and audio with a single API. OpenAI-compatible — use any OpenAI SDK by changing the base URL.

Base URL: https://gen.pollinations.ai
API Keys: https://enter.pollinations.ai
Docs: https://gen.pollinations.ai/api/docs
CLI: `npx @pollinations_ai/cli` (binary: `polli`) — agent-friendly, `--json` everywhere

## Quick Start

### Text (Python, OpenAI SDK)

```python
from openai import OpenAI
client = OpenAI(base_url="https://gen.pollinations.ai", api_key="YOUR_API_KEY")
response = client.chat.completions.create(model="openai", messages=[{"role": "user", "content": "Hello!"}])
print(response.choices[0].message.content)
```

### Image (URL — no code needed)

```
https://gen.pollinations.ai/image/a%20cat%20in%20space?model=flux
```

### Image (Python, OpenAI SDK)

```python
from openai import OpenAI
client = OpenAI(base_url="https://gen.pollinations.ai/v1", api_key="YOUR_API_KEY")
response = client.images.generate(model="flux", prompt="a cat in space", size="1024x1024")
print(response.data[0].url)
```

### Audio (cURL)

```bash
curl "https://gen.pollinations.ai/audio/Hello%20world?voice=nova" \
  -H "Authorization: Bearer YOUR_API_KEY" -o speech.mp3
```

## CLI

`@pollinations_ai/cli` wraps this API for terminals and agents. Structured `--json` output, deterministic exit codes, friendly 402 balance hints, stdin piping.

```bash
npm install -g @pollinations_ai/cli
polli auth login
polli gen image "a cat in space" --model flux --output cat.png
polli gen text "summarize this" < notes.md
polli models --type image
polli usage
```

Source: https://github.com/pollinations/pollinations/tree/main/packages/polli-cli

## Authentication

All generation requests require an API key. Model listing endpoints work without auth.

- Header: `Authorization: Bearer YOUR_API_KEY`
- Query param: `?key=YOUR_API_KEY`

Key types: `sk_` (secret, server-side) | `pk_` (publishable, client-side, rate limited)

## Endpoints

### POST /v1/chat/completions
OpenAI-compatible chat completions. Use any OpenAI SDK with base_url="https://gen.pollinations.ai".

Request body (JSON):
- model (string, default: "openai"): Model ID
- messages (array, required): [{role: "user"|"assistant"|"system", content: "..."}]
- stream (boolean, default: false): SSE streaming
- temperature (number, 0.0-2.0): Randomness
- seed (integer, default: 0): Reproducibility. -1 for random
- response_format ({type: "json_object"}): Force JSON output

### GET /text/{prompt}
Simple text generation. Returns plain text.
Query params: model, seed, system, json, temperature, stream

### GET /image/{prompt}
Generate image or video. Returns binary (image/jpeg or video/mp4).

Query params:
- model (string, default: "zimage"): Image or video model
- width (int, default: 1024), height (int, default: 1024)
- seed (int, default: 0): Works with flux, zimage, seedream, klein, seedance. -1 for random
- enhance (boolean, default: false): AI prompt enhancement
- negative_prompt (string): Only flux, zimage
- safe (boolean, default: false): Safety filter
- quality (low|medium|high|hd, default: "medium"): gptimage, gptimage-large
- image (string): Reference image URL(s), | or , separated
- transparent (boolean, default: false): gptimage, gptimage-large
- reasoning (boolean, default: false): Enable thinking for improved text/layout. nanobanana, nanobanana-2, nanobanana-pro
- duration (int, 1-10): Video duration in seconds
- aspectRatio ("16:9"|"9:16"): Video only
- audio (boolean, default: false): Video audio. wan always has audio

### POST /v1/images/generations
OpenAI-compatible image generation. Use any OpenAI SDK with `base_url="https://gen.pollinations.ai/v1"`.

Request body (JSON):
- prompt (string, required): Text description of the image
- model (string, default: "flux"): Image model
- size (string, default: "1024x1024"): WIDTHxHEIGHT
- response_format ("url"|"b64_json", default: "b64_json"): Return format
- quality, seed, nologo, enhance, safe: Same as GET /image/{prompt}

### POST /v1/images/edits
OpenAI-compatible image editing. Accepts JSON with image URLs or multipart/form-data file uploads.

Request body (JSON or multipart):
- prompt (string, required): Description of the edit
- image (string or array): Source image URL(s)
- model (string, default: "flux"): Image model

### GET /audio/{text}
Text-to-speech or music generation. Returns audio/mpeg.
Query params: voice, model (elevenlabs|elevenmusic|acestep), duration

### POST /v1/audio/speech
OpenAI-compatible TTS. Body: {input, voice, model}

### POST /v1/audio/transcriptions
Speech-to-text. Multipart: file (audio), model (whisper-large-v3|scribe)

### GET /v1/models
List text models (OpenAI format). No auth required.

### GET /image/models
List image/video models with metadata. No auth required.

## Text Models

- openai: OpenAI GPT-5.4 Nano - Fast & Balanced [tools]
- openai-fast: OpenAI GPT-5 Nano - Ultra Fast & Affordable [tools]
- openai-large: OpenAI GPT-5.4 - Most Powerful & Intelligent [tools, reasoning]
- qwen-coder: Qwen3 Coder 30B - Specialized for Code Generation [tools]
- mistral: Mistral Small 3.2 - Efficient & Cost-Effective [tools]
- openai-audio: OpenAI GPT Audio Mini - Voice Input & Output [tools]
- openai-audio-large: OpenAI GPT Audio 1.5 - Premium Voice Input & Output [tools]
- gemini: Google Gemini 3 Flash - Pro-Grade Reasoning at Flash Speed [tools, search, code-exec] (paid)
- gemini-flash-lite-3.1: Google Gemini 3.1 Flash Lite - Fast & Cost-Effective [tools, search, code-exec] (paid)
- gemini-fast: Google Gemini 2.5 Flash Lite - Ultra Fast & Cost-Effective [tools, search, code-exec]
- deepseek: DeepSeek V3.2 - Efficient Reasoning & Agentic AI [tools, reasoning]
- grok: xAI Grok 4.1 Fast - High Speed & Real-Time [tools]
- grok-large: xAI Grok 4.20 Reasoning - Most Powerful Grok [tools, reasoning]
- gemini-search: Google Gemini 2.5 Flash Lite - With Google Search [search, code-exec]
- midijourney: MIDIjourney - AI Music Composition Assistant [tools]
- midijourney-large: MIDIjourney Large - Premium AI Music Composition [tools] (paid)
- claude-fast: Anthropic Claude Haiku 4.5 - Fast & Intelligent [tools]
- claude: Anthropic Claude Sonnet 4.6 - Most Capable & Balanced [tools] (paid)
- claude-large: Anthropic Claude Opus 4.6 - Most Intelligent Model [tools] (paid)
- perplexity-fast: Perplexity Sonar - Fast & Affordable with Web Search [search]
- perplexity-reasoning: Perplexity Sonar Reasoning - Advanced Reasoning with Web Search [reasoning, search]
- kimi: Moonshot Kimi K2.5 - Flagship Agentic Model with CoT Reasoning [tools, reasoning]
- gemini-large: Google Gemini 3.1 Pro - Most Intelligent Model with 1M Context (Preview) [tools, reasoning, search] (paid)
- nova-fast: Amazon Nova Micro - Ultra Fast & Ultra Cheap [tools]
- nova: Amazon Nova 2 Lite - 1M Context with Reasoning [tools, reasoning]
- glm: Z.ai GLM-5.1 - 744B MoE, Long Context Reasoning & Agentic Workflows [tools, reasoning]
- minimax: MiniMax M2.5 - Coding, Agentic & Multi-Language [tools, reasoning]
- mistral-large: Mistral Large 3 - Premium Multilingual & Reasoning [tools, reasoning]
- polly: Polly by @Itachi-1824 - Pollinations AI Assistant with GitHub, Code Search & Web Tools (Alpha) [tools, reasoning, search, code-exec] (alpha)
- qwen-coder-large: Qwen3 Coder Next - Advanced Code Generation via DashScope [tools]
- qwen-large: Qwen3.6 Plus - 396B MoE Flagship with Reasoning (Fireworks) [tools, reasoning]
- qwen-vision: Qwen3 VL Plus - Vision-Language Understanding with Reasoning via DashScope [tools, reasoning]
- qwen-safety: Qwen3Guard 8B - Content Safety & Moderation (OVH)

## Image Models

- kontext: FLUX.1 Kontext - In-context editing & generation (image input)
- nanobanana: NanoBanana - Gemini 2.5 Flash Image (paid, image input)
- nanobanana-2: NanoBanana 2 - Gemini 3.1 Flash Image (paid, image input)
- nanobanana-pro: NanoBanana Pro - Gemini 3 Pro Image (4K, Thinking) (paid, image input)
- seedream5: Seedream 5.0 Lite - ByteDance ARK (web search, reasoning) (paid, image input)
- gptimage: GPT Image 1 Mini - OpenAI's image generation model (image input)
- gptimage-large: GPT Image 1.5 - OpenAI's advanced image generation model (image input)
- flux: Flux Schnell - Fast high-quality image generation
- zimage: Z-Image Turbo - Fast 6B Flux with 2x upscaling
- wan-image: Wan 2.7 Image - Alibaba text-to-image and image editing (up to 2K) (image input)
- wan-image-pro: Wan 2.7 Image Pro - Alibaba text-to-image and editing (4K, thinking mode) (paid, image input)
- qwen-image: Qwen Image Plus - Alibaba text-to-image and image editing via DashScope (image input)
- grok-imagine: Grok Imagine - xAI official image generation (paid)
- grok-imagine-pro: Grok Imagine Pro - xAI official pro image generation (Aurora) (paid)
- klein: FLUX.2 Klein 4B - Fast image generation and editing (image input)
- p-image: Pruna p-image - Fast text-to-image generation (paid)
- p-image-edit: Pruna p-image-edit - Image-to-image editing (paid, image input)
- nova-canvas: Amazon Nova Canvas - Bedrock Image Generation & Editing (paid, image input)

## Video Models

- veo: Veo 3.1 Fast - Google's video generation model (preview) (paid)
- seedance: Seedance Lite - BytePlus video generation (better quality) (paid)
- seedance-pro: Seedance Pro-Fast - BytePlus video generation (better prompt adherence) (paid)
- wan: Wan 2.6 - Alibaba text/image-to-video with audio (2-15s, up to 1080P) via DashScope (paid)
- wan-fast: Wan 2.2 - Fast & cheap text/image-to-video (5s, 480P) via DashScope (paid)
- grok-video-pro: Grok Video Pro - xAI official video generation (720p, 1-15s) (paid)
- ltx-2: LTX-2.3 - Fast text-to-video generation with upscaler
- p-video: Pruna p-video - Text/image-to-video generation (up to 1080p) (paid)
- nova-reel: Amazon Nova Reel - Bedrock Video Generation (6-60s, 720p)

## Audio Models

- elevenlabs: ElevenLabs v3 TTS - Expressive voices with emotions & audio tags
- elevenmusic: ElevenLabs Music - Generate studio-grade music from text prompts
- whisper: Whisper Large V3 - Speech to Text Transcription (OVHcloud) (alpha)
- scribe: ElevenLabs Scribe v2 - Speech to Text (90+ languages, diarization)
- acestep: ACE-Step 1.5 Turbo - Fast open-source music generation with lyrics support (alpha)

## Available Voices (TTS)

alloy, echo, fable, onyx, nova, shimmer, ash, ballad, coral, sage, verse, rachel, domi, bella, elli, charlotte, dorothy, sarah, emily, lily, matilda, adam, antoni, arnold, josh, sam, daniel, charlie, james, fin, callum, liam, george, brian, bill

## Account

All account endpoints require authentication (API key or session). API keys need the relevant `account:<scope>` permission.
Base path: /api/account

### GET /api/account/profile
Returns user profile: name, email, githubUsername, image, tier, createdAt, nextResetAt.
Requires `account:profile` permission.

### GET /api/account/balance
Returns { balance } — remaining pollen (sum of tier + pack + crypto). If API key has a budget, returns key budget instead.
Requires `account:balance` permission.

### GET /api/account/usage
Per-request usage history: model, token counts, cost, response time.
Query params: format (json|csv, default json), days (1-90, default 30), limit (1-50000, default 100), before (ISO timestamp cursor). Each response is capped by limit; dashboard detailed CSV uses the latest 50,000 rows within the selected period.
Requires `account:usage` permission.

### GET /api/account/usage/daily
Daily aggregated usage for the requested time window (max 90 days) grouped by date and model: { date, model, meter_source, requests, cost_usd }.
Query params: format (json|csv, default json), days (1-90, default 90)
Requires `account:usage` permission. Cached 1 hour.

### GET /api/account/keys
List all API keys for the current user. Requires secret key (sk_) with `account:keys` permission.

### POST /api/account/keys
Create an API key. Requires secret key (sk_) with `account:keys` permission.
Body (JSON):
- name (string, required): Display name
- type ("secret"|"publishable", default "secret"): Key type (sk_ or pk_)
- expiresIn (int, optional): Seconds until expiry (max 365d)
- allowedModels (string[], optional): Restrict to specific models. null = all
- pollenBudget (number, optional): Pollen budget cap. null = unlimited
- accountPermissions (string[], optional): e.g. ["balance","usage"]. "keys" is auto-stripped
Returns full key value once: { id, key, name, type, prefix, start, expiresAt, permissions, pollenBudget }

### DELETE /api/account/keys/:id
Revoke an API key by ID. Cannot revoke the key authenticating the request.
Requires secret key (sk_) with `account:keys` permission.

### GET /api/account/key
Info about the current API key: { valid, type, name, expiresAt, expiresIn, permissions, pollenBudget, rateLimitEnabled }.
Requires API key authentication (any key type).

## Media Storage

Base URL: https://media.pollinations.ai
Content-addressed file storage. Upload requires API key; retrieval is public.
Max file size: 10 MB. Files expire after 14 days; re-uploading resets the TTL.

### POST /upload
Upload a file. Accepts multipart/form-data (field: `file`), raw binary, or JSON { data (base64), contentType?, name? }.
Auth: `Authorization: Bearer <key>` or `?key=<key>`
Returns { id (16-char hex hash), url, contentType, size, duplicate }.

### GET /{hash}
Retrieve a file by its 16-char hex content hash. No auth required. Cached immutably.

### HEAD /{hash}
Check if a file exists. Returns Content-Type, Content-Length, X-Content-Hash headers. No auth.

## Errors

JSON: {status, success: false, error: {code, message}}
- 400: Invalid parameters
- 401: Missing/invalid API key
- 402: Insufficient balance
- 403: Permission denied
- 500: Server error

# 🌼 Bring Your Own Pollen (BYOP)

Your users pay for their own AI usage. You pay $0.

## 🔄 How It Works

1. User connects — via your web app or CLI
2. Signs in, creates a scoped API key
3. Their pollen, your app

Why this is good:

- 💸 **$0 costs** — scales to any number of users without costing you a cent
- 🔑 **No key management** — the auth flow handles it
- ⚖️ **Self-regulating** — everyone pays for what they use
- 🌐 **Works everywhere** — web apps, CLIs, MCP servers, anything

Both flows land on the same authorize screen where users set model restrictions, budget, and expiry. Same key, same pollen, different entry point.

## 🗝️ App Key

An **App Key** is a publishable key (`pk_...`) you create on [enter.pollinations.ai](https://enter.pollinations.ai) specifically for BYOP. It's optional but strongly recommended:

| Without App Key | With App Key |
|----------------|-------------|
| Consent screen shows generic hostname | Consent screen shows **your app name + your GitHub** |
| No traffic attribution | Traffic your app drives is **tracked to your account** |
| No tier benefit | Real usage → **automatic tier upgrades** → higher pollen grants |

To create one, go to [enter.pollinations.ai](https://enter.pollinations.ai) → **Create New App Key**:

![Create New App Key](https://media.pollinations.ai/aa8ca9fe3110aff7)

Set the **Name** (shows on the consent screen) and **App URL** (your app's domain). The key you get back is your `app_key`.

When users authorize, this is what they see:

![Authorize Screen](https://media.pollinations.ai/b030a47e32df2b2b)

## ⚙️ Web Apps (Redirect Flow)

### 1. Build the Auth Link

With `app_key` (consent screen shows your app name + your GitHub):
```
https://enter.pollinations.ai/authorize?redirect_url=https://myapp.com&app_key=pk_yourkey
```

Without (still works, just shows the hostname):
```
https://enter.pollinations.ai/authorize?redirect_url=https://myapp.com
```

With restrictions:
```
https://enter.pollinations.ai/authorize?redirect_url=https://myapp.com&app_key=pk_yourkey&models=flux,openai&expiry=7&budget=10
```

| Param | What it does | Example |
|-------|-------------|---------|
| `app_key` | Your publishable key — shows app name + author on consent screen, tracks traffic for tier upgrades | `pk_abc123` |
| `redirect_url` | Where users return after authorizing — receives the temp API key in the URL fragment | `https://myapp.com` |
| `models` | Restrict to specific models | `flux,openai,gptimage` |
| `budget` | Pollen cap | `10` |
| `expiry` | Key lifetime in days (default: 30) | `7` |
| `permissions` | Account access | `profile,balance,usage` |

### 2. Handle the Redirect

User comes back with a key in the URL fragment:
```
https://myapp.com#api_key=sk_abc123xyz
```

Fragment, not query param — never hits server logs. 🔒

### 💻 Code

```javascript
// Send user to auth
const params = new URLSearchParams({
  redirect_url: location.href,
  app_key: 'pk_yourkey', // optional — shows app name + author
});
window.location.href = `https://enter.pollinations.ai/authorize?${params}`;

// Grab key from URL after redirect
const apiKey = new URLSearchParams(location.hash.slice(1)).get('api_key');

// Use their pollen
fetch('https://gen.pollinations.ai/v1/chat/completions', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ model: 'openai', messages: [{ role: 'user', content: 'yo' }] })
});
```

## 🖥️ CLIs & Headless Apps (Device Flow)

Same authorize screen, but the user opens a browser separately. Your CLI polls for the key.

**Where this fits:**
- **Discord / Telegram / WhatsApp bots** — bot DMs the code, user approves in browser, bot gets their key
- **CLI tools** — `pollinations login` opens a browser, CLI waits for approval
- **MCP servers** — AI agent requests access, user approves from their browser
- **Raspberry Pi / IoT** — headless device displays a code, user approves on their phone
- **VS Code extensions** — extension shows the code, user approves in browser

```bash
# 1. request a device code (pass your app_key as client_id for attribution)
curl -X POST https://enter.pollinations.ai/api/device/code \
  -H 'Content-Type: application/json' \
  -d '{"client_id": "pk_yourkey", "scope": "generate"}'
# → { "device_code": "...", "user_code": "ABCD-1234", "verification_uri": "/device" }

# 2. tell user: "go to enter.pollinations.ai/device and enter ABCD-1234"

# 3. poll for the key (every 5s)
curl -X POST https://enter.pollinations.ai/api/device/token \
  -H 'Content-Type: application/json' \
  -d '{"device_code": "..."}'
# pending → { "error": "authorization_pending" }
# done    → { "access_token": "sk_...", "token_type": "bearer", "scope": "generate" }
```

## 👤 Who's Using This Key?

Once you have a key, you can check who it belongs to:

```bash
curl https://enter.pollinations.ai/api/device/userinfo \
  -H 'Authorization: Bearer sk_...'
# → { "sub": "user-id", "name": "Thomas", "preferred_username": "voodoohop", "email": "...", "picture": "..." }
```

Standard OIDC userinfo shape — works with any `sk_` or `pk_` key.

---

🕐 Keys expire in 30 days. Users can revoke anytime from the dashboard.

[edit this doc](https://github.com/pollinations/pollinations/edit/main/BRING_YOUR_OWN_POLLEN.md) · *h/t [Puter.js](https://docs.puter.com/user-pays-model/) for the idea*