pollinations/pollinations/polli-cli

polli — Pollinations CLI

Thin wrapper around gen.pollinations.ai. Generates images, text, audio, video; transcribes speech; manages API keys, usage, quests, agents, and invite-only my-models.

If polli is not installed, run npm i -g @pollinations/cli@latest (provides the polli binary).

When to use this skill

• User asks to generate an image / text / audio / video via pollinations
• User mentions polli, pollinations, pollen, pollinations.ai
• User wants to transcribe speech or run TTS
• User asks about their pollen balance, usage, or API keys
• User wants to browse or filter available models
• User wants to inspect quests or manage invite-only my-models
• User wants to create or update a hosted prompt agent
• User wants to publish a website or web app they built

For agent-assisted login, use polli --json auth login --no-browser. Read stderr while the command runs and show the user the verification URL and user code so they can review access. On approval, stdout contains one JSON result: {"authenticated":true}. Tokens are stored locally and never included in that result.

Quick reference

Setup

One-time: polli auth login (device-flow; creates a key with profile, usage, and keys). To store an existing key, run printf '%s' "$POLLINATIONS_API_KEY" | polli auth login --with-token. Verify with polli auth status (or polli whoami). Override the stored key for a single command with --key <key>. Prefix any command with POLLINATIONS_ENV=staging to use staging; it keeps its own login, so run POLLINATIONS_ENV=staging polli auth login once.

Recipes

Generate an image to a file

polli gen image "a fox reading a book, studio ghibli style" --output fox.png

Defaults: tongyi-mai/z-image-turbo, 1024x1024. Without --output the file is image.<ext>, with the extension inferred from the response's Content-Type (tongyi-mai/z-image-turbo and black-forest-labs/flux.1-schnell return JPEG, so image.jpg); an explicit --output is used as given. Pick a different model with --model black-forest-labs/flux.1-schnell (see polli models --type image). For edits / img2img, pass one or more --image <url> flags — must be public http(s) URLs, local paths are rejected client-side. Only models that list `"image"` in `input_modalities` actually consume the flag — black-forest-labs/flux.1-schnell and tongyi-mai/z-image-turbo are text-only and will silently ignore --image. Find i2i-capable models with polli models --type image --json | jq -r '.[] | select(.input_modalities | contains(["image"])) | .name' (common choices: google/gemini-2.5-flash-image, black-forest-labs/flux.1-kontext-pro, prunaai/p-image-edit). To use a local file, upload it first with polli upload (see next recipe). Img2img models may treat `--width`/`--height` as a hint and keep the source aspect — check the output with file/ffprobe; if the aspect matters, pre-crop the source or crop afterwards.

Upload a local file to get a public URL

URL=$(polli upload cat.png)
polli gen image "make the cat purple" --image "$URL" --output purple.png

polli upload <file> streams one raw-file request to media.pollinations.ai (400 MiB max; 30-day lifecycle, refreshed by GETs once the object is at least 15 days old). Each upload receives a unique id. Human mode: URL on stdout and id/size/contentType on stderr. --json: full upload response on stdout. The returned URL is public (no auth to fetch) and works anywhere --image is accepted — gen image, gen video, etc.

Generate text

polli gen text "summarize the three laws of robotics"

Save to file: --output summary.txt. Use --system "<msg>" to set system prompt. For reasoning models, pass --reasoning low|medium|high to control reasoning effort. Only send `--reasoning` to models where `reasoning: true` in polli models --type text --json — the flag is not validated client-side, and non-reasoning models may silently accept it (openai), ignore it, or return a 400 (mistral).

Describe an image with a vision model

URL=$(polli upload selfie.jpg)
polli gen text "turn this person into a cartoon pet in one playful sentence" --image "$URL"

gen text --image <url...> attaches one or more public https URLs as an OpenAI-style multimodal message — repeatable for multi-image prompts. Local paths aren't supported; run them through polli upload first (see the upload recipe above). Only text models with `"image"` in `input_modalities` actually read the image — filter with polli models --type text --json | jq -r '.[] | select(.input_modalities | index("image")) | .name'. Non-vision models silently ignore the attachment. Good defaults: openai, gemini, claude.

Pipe stdin as context into text generation

cat README.md | polli gen text "what does this project do?"

stdin becomes context; the positional argument is the question.

Interactive chat session

polli gen chat --model openai/gpt-5.4-nano --system "you are a terse assistant"

Slash commands inside the session: /exit, /clear, /save <path>.

Text-to-speech

polli gen audio "hello world" --voice nova --output hello.mp3
echo "long script" | polli gen audio --voice nova --output out.mp3

Without --voice, the API uses the model's default voice. To discover the full live voice list, use the model registry: polli models --type audio --json | jq -r '.[].voices[]?' — each audio model entry includes its voices[] array. Format defaults to mp3; --format opus|aac|flac|wav to change. Accepts stdin (same as gen text). Add --play to save and then play the audio back (handy for narration/demos). Playback starts after the file is fully written, and the command blocks until playback finishes — if you want fire-and-forget, wrap in a subshell: ( polli gen audio "..." --play & ). Player on macOS: afplay; on Linux it tries ffplay, then mpv, then mpg123 in that order.

Generate music (elevenlabs/music-v2)

polli gen audio "lofi hip-hop beat" --model elevenlabs/music-v2 --duration 30 --instrumental --output track.mp3

Generate sound effects (elevenlabs/eleven-text-to-sound-v2)

polli gen audio "thunderclap with heavy rain" --model elevenlabs/eleven-text-to-sound-v2 --duration 5 --output thunder.mp3

Text-to-sound-effect via ElevenLabs (aliases: sfx, sound-effects). --duration 0.5–30s (omit to let the model pick). Billed per second of output (~$0.004/s, capped at $0.12 for a full 30s).

Multilingual TTS (elevenlabs/eleven-multilingual-v2)

polli gen audio "Bonjour, ceci est un test" --model elevenlabs/eleven-multilingual-v2 --voice rachel --output fr.mp3

Stable, lifelike TTS across 29 languages (aliases: multilingual-v2, eleven-v2) — a non-alpha alternative to the default v3.

Estimate the cost before generating

polli gen image "a fox" --model flux --estimate
polli gen video "a spacecraft landing on mars" --model veo --duration 8 --audio --estimate

--estimate reads the public model list (/image/models), prints the estimated Pollen for that request and exits without generating. Per-image, per-megapixel and per-second rates give a number; token-billed models (e.g. gpt-image-2, nanobanana) print estimate: unknown with their rates, because the charge depends on usage the provider reports afterwards. --json adds pollen (null when unknown) and the per-rate lines.

Generate video

polli gen video "a spacecraft landing on mars" --model alibaba/wan-2.2-fast --duration 5 --output mars.mp4

Cheapest path: --model alibaba/wan-2.2-fast at ~$0.01/sec, fixed 5-second output (any --duration value is ignored — you always pay for and receive 5 sec). For image-to-video, pass --image <url> with a public HTTPS URL (local file paths and 404/rate-limited hosts will fail with a server error).

Flag support varies per model and is not enforced client-side. --duration, --aspect-ratio, and --audio are forwarded to the server but may be silently ignored — verified on wan-fast where duration is locked to 5s, --aspect-ratio 9:16 still returns 16:9, and --audio produces no audio track. Always inspect the output (file, ffprobe) before trusting a flag worked. Check polli models --type video --json for per-model capabilities.

Video is not tracked by `--stats`. polli models --type video --stats returns empty — the stats pipe only records text/image/audio events. To compare video models, fall back to polli models --type video --json and look at price/description fields. The same applies to --type 3d.