Pollinations Python Skill

Environment Setup

Required .env Keys

POLLINATIONS_API_KEY=sk_your_key_here

# Optional tuning
TARGET_VIDEO_DURATION=180
AUDIO_PROVIDER=edge-tts
EDGE_TTS_NAME=id-ID-ArdiNeural

Install Dependencies

pip install openai python-dotenv requests pillow

Or add to requirements.txt:

openai>=1.0.0
python-dotenv>=1.0.0
requests>=2.31.0
pillow>=10.0.0

Load .env in Every Script

from dotenv import load_dotenv
import os

load_dotenv()  # reads .env in CWD or any parent

API_KEY = os.getenv("POLLINATIONS_API_KEY")
if not API_KEY:
    raise EnvironmentError("POLLINATIONS_API_KEY is not set in .env")

Run the environment checker any time setup is uncertain:

python .agents/skills/pollinations-python/scripts/check_env.py

API Reference Docs

Quick Patterns

Text Generation (OpenAI SDK)

from openai import OpenAI
from dotenv import load_dotenv
import os

load_dotenv()
client = OpenAI(
    base_url="https://gen.pollinations.ai",
    api_key=os.environ["POLLINATIONS_API_KEY"],
)

response = client.chat.completions.create(
    model="openai",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

Image Generation (OpenAI SDK)

from openai import OpenAI
from dotenv import load_dotenv
import os

load_dotenv()
client = OpenAI(
    base_url="https://gen.pollinations.ai/v1",
    api_key=os.environ["POLLINATIONS_API_KEY"],
)

response = client.images.generate(
    model="flux",
    prompt="a cat in space",
    size="1024x1024",
)
print(response.data[0].url)

Save Image to Disk (Cross-Platform)

import requests
from pathlib import Path
from dotenv import load_dotenv
import os

load_dotenv()

def save_image(url: str, filename: str) -> Path:
    """Download image URL and save to output/ folder."""
    output_dir = Path("output")
    output_dir.mkdir(parents=True, exist_ok=True)  # works on all OS
    dest = output_dir / filename
    resp = requests.get(url, timeout=60)
    resp.raise_for_status()
    dest.write_bytes(resp.content)
    return dest

Audio / TTS

import requests
from pathlib import Path
from dotenv import load_dotenv
import os
from urllib.parse import quote

load_dotenv()
API_KEY = os.environ["POLLINATIONS_API_KEY"]

def tts(text: str, voice: str = "nova", out: str = "speech.mp3") -> Path:
    url = f"https://gen.pollinations.ai/audio/{quote(text)}?voice={voice}"
    resp = requests.get(url, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=120)
    resp.raise_for_status()
    dest = Path(out)
    dest.write_bytes(resp.content)
    return dest

Check API Balance

import requests
from dotenv import load_dotenv
import os

load_dotenv()
resp = requests.get(
    "https://gen.pollinations.ai/api/account/balance",
    headers={"Authorization": f"Bearer {os.environ['POLLINATIONS_API_KEY']}"},
)
print(resp.json())

Cross-Platform Checklist

When writing or reviewing scripts, verify:

• All file paths use pathlib.Path, not string concatenation
• .env loaded with python-dotenv at the top of main / entry point
• No hardcoded API keys — all read from os.getenv or os.environ
• requirements.txt exists and lists all imports
• mkdir calls use parents=True, exist_ok=True
• Binary file writes use .write_bytes() not open(..., 'w') (important on Windows)
• Timeouts set on all requests calls
• load_dotenv() called before any os.getenv that reads API keys

Error Codes Quick Reference

Bundled Scripts

generate_images.py — Batch scene image generation

Reads prompt_N.txt from each scene folder and calls the Pollinations image API to generate a JPEG. Defaults are tuned for the 9:16 short-form video pipeline (1080×1920 portrait).

Install deps:

pip install requests python-dotenv

Configure .env:

POLLINATIONS_API_KEY=your_key_here

Run directly (no editing needed):

# Portrait (default 1080×1920) — auto-detects scenes
python .agents/skills/pollinations-python/scripts/generate_images.py output/20260411_funfact-planet-mars

# Landscape (1920×1080)
python .agents/skills/pollinations-python/scripts/generate_images.py output/20260411_funfact-planet-mars --orientation landscape

# Custom model and dimensions
python .agents/skills/pollinations-python/scripts/generate_images.py output/20260411_funfact-planet-mars \
  --model nanobanana --width 1080 --height 1920

CLI arguments:

Output per scene: scene_N/image_N.jpeg

Resumable: Skips scenes where image_N.jpeg already exists.

Important: Output must be .jpeg — Remotion's renderer requires JPEG format. Other formats will break rendering.