polli

# 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 | Intent | Command | |---|---| | Log in once | `polli auth login` | | Agent-assisted login | `polli --json auth login --no-browser` | | Store an existing key | `printf '%s' "$POLLINATIONS_API_KEY" \| polli auth login --with-token` | | Generate image | `polli gen image "<prompt>" --output out.png` | | Generate text | `polli gen text "<prompt>"` | | Text with stdin as context | `echo "<ctx>" \| polli gen text "<question>"` | | Describe an image (vision) | `polli gen text "what is this?" --image <url>` | | One-shot TTS | `polli gen audio "<text>" --output speech.mp3` | | Speak out loud | `polli gen audio "<text>" --play` (uses `afplay` on macOS; `ffplay`/`mpv`/`mpg123` on Linux) | | Generate video | `polli gen video "<prompt>" --output out.mp4` | | Generate a 3D model | `polli gen 3d "<prompt>" --output out.glb` (or `--image <url>` for image-only models) | | Embed text | `polli gen embeddings "<text>" ["<text2>" ...]` (one vector per line; also reads stdin) | | Change a voice | `polli gen voice-change talk.mp3 --voice nova` | | Isolate speech | `polli gen isolate interview.mp4` (strips music/noise) | | Speech + character timings | `polli gen audio "<text>" --timestamps` (also writes `speech.mp3.json`) | | Transcribe audio | `polli gen transcribe path/to.mp3` | | Upload a local file | `polli upload path/to.png` (prints public URL) | | List all models | `polli models` | | Search models | `polli models <query>` (`--source official\|community`, `--reliability all`) | | Discover voices | `polli models --type audio --voices` (one line per model) | | Filter models by type | `polli models --type image` (text, decision, image, audio, video, 3d, embedding, realtime) | | Model health + latency | `polli models --stats` (default 60m, `--window <min>`) | | Check balance | `polli usage` | | Developer earnings | `polli earnings` (`--days <n>`) | | List your quests + claim state | `polli quests` (filters: `--open --claimable --claimed --coming-soon`) | | Manage prompt agents | `polli agents list` | | Manage invite-only community models | `polli my-models list` | | Update the CLI | `polli update` (global installs only; npx/local get instructions) | | Connect a coding harness to Pollinations | `polli harness <bloom\|dsh\|hermes\|opencode\|openclaw\|pi\|prime\|tgpt> on` (available adapters: `polli harness --help`) | | Start a Linux sandbox (alpha) | `polli sandbox create` (`--timeout <seconds>` to keep it running without ssh, `0` until you pause or kill it; `pollinations-large` as the template for 4 vCPU and 8 GB; then `list`, `logs <id>`, `timeout <id> <seconds>`, `pause <id>`, `kill <id>`); the default template comes logged in, with the coding harnesses | | ssh / scp / rsync into a sandbox | `ssh <sandbox-id>.polli`. Port forwarding (`ssh -L 3000:localhost:3000 <sandbox-id>.polli`) and VS Code Remote-SSH work. An open connection keeps the sandbox running and paid; it pauses 15–20 minutes after the last one closes (5–10 on Windows) | | Publish a static site | `polli sites deploy ./dist --name my-app` (prints `https://my-app.pollinations.app`; then `list`, `delete <name>`) | | Machine-readable output | append `--json` to any command | ## 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>`, or set `POLLINATIONS_API_KEY` in the environment. Prefix any command with `POLLINATIONS_ENV=staging` to use staging; it keeps its own login, so run `POLLINATIONS_ENV=staging polli auth login` once. An exported `POLLINATIONS_API_KEY` wins over both logins. ## Recipes ### Generate an image to a file ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash cat README.md | polli gen text "what does this project do?" ``` stdin becomes context; the positional argument is the question. ### Interactive chat session ```bash 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 ```bash 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. Voices differ per model: `polli models --type audio --voices` lists each model's voices, so pass the matching `--model` with `--voice`. 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) ```bash 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) ```bash 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) ```bash 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 ```bash 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, plus fixed per-generation fees, 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 ```bash 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`. ### Generate a 3D model ```bash polli gen 3d "a red fox" --output fox.glb polli gen 3d --image https://media.pollinations.ai/abc --resolution high ``` `--model` defaults to `hyper3d/rodin-2.5` for a text-only prompt and `microsoft/trellis-2` once `--image <url>` is given (public http(s), upload local files first with `polli upload`) — `trellis-2` is **image-to-3D only** and rejects a bare prompt. `--resolution low|medium|high` only affects `trellis-2`. The output extension is inferred from the response's `Content-Type`, not the model name: `nvidia/asset-harvester` returns a Gaussian Splat `.ply`, everything else returns `.glb`. `hyper3d/rodin-2.5` and `nvidia/asset-harvester` require Paid Pollen. ### Generate embeddings ```bash polli gen embeddings "first text" "second text" --model google/gemini-embedding-2 printf 'first\nsecond\n' | polli gen embeddings # one input per stdin line ``` Prints one JSON array per input, in input order, one per line (pipe/`jq`-friendly). `--dimensions <n>` (128-4096), `--task-type` (Gemini retrieval hint), and `--input-type query|document` (Cohere) are optional. `--json` prints the full response including `usage`. ### Change or isolate a voice ```bash polli gen voice-change talk.mp3 --voice nova --format wav polli gen isolate interview.mp4 ```