Skip to content

Latest commit

 

History

History
433 lines (321 loc) · 13.9 KB

API_COVERAGE.md

File metadata and controls

433 lines (321 loc) · 13.9 KB

Pollinations.AI API Coverage - Complete Feature Parity

This document verifies that PolliLibPy (Python) and PolliLibJS (JavaScript) have 100% coverage of all Pollinations.AI API features as documented in the official API documentation.

Last updated: 2025-11-17

✅ API Endpoints Coverage

Image Generation Endpoints

Endpoint Python JavaScript Status
GET /prompt/{prompt} ✅ text_to_image.py ✅ text-to-image.js Complete
GET /models ✅ model_retrieval.py::list_image_models() ✅ model-retrieval.js::listImageModels() Complete
GET /feed ✅ streaming_mode.py::monitor_feed() ✅ streaming-mode.js::monitorFeed() Complete

Text Generation Endpoints

Endpoint Python JavaScript Status
GET /{prompt} ✅ text_to_text.py::generate_text() ✅ text-to-text.js::generateText() Complete
POST /openai ✅ text_to_text.py::chat() ✅ text-to-text.js::chat() Complete
GET /models ✅ model_retrieval.py::list_text_models() ✅ model-retrieval.js::listTextModels() Complete
GET /feed ✅ streaming_mode.py::monitor_feed() ✅ streaming-mode.js::monitorFeed() Complete

Audio Endpoints

Endpoint Python JavaScript Status
GET /{prompt}?model=openai-audio&voice={voice} (TTS) ✅ text_to_speech.py::generate_speech() ✅ text-to-speech.js::generateSpeech() Complete
POST /openai (STT via multimodal) ✅ speech_to_text.py::transcribe() ✅ speech-to-text.js::transcribe() Complete

✅ Image Generation Parameters

All parameters from the official API documentation are fully supported:

Parameter Type Default Python JavaScript
prompt string Required ✅ ✅
model string flux ✅ ✅
width integer 1024 ✅ ✅
height integer 1024 ✅ ✅
seed integer random ✅ ✅
nologo boolean false ✅ ✅
enhance boolean false ✅ ✅
private boolean false ✅ ✅
safe boolean false ✅ (added) ✅ (added)

Supported Models: flux, turbo, stable-diffusion, kontext

Special Feature: Image-to-image transformation with kontext model

  • ✅ Python: image_to_image.py::transform_image()
  • ✅ JavaScript: image-to-image.js::transformImage()

✅ Text Generation Parameters

Simple Endpoint (GET)

Parameter Type Default Python JavaScript
prompt string Required ✅ ✅
model string openai ✅ ✅
temperature float varies ✅ ✅
seed integer random ✅ ✅
system string — ✅ ✅
json boolean false ✅ ✅
stream boolean false ✅ ✅

OpenAI-Compatible Endpoint (POST)

Parameter Type Python JavaScript
messages array ✅ ✅
model string ✅ ✅
temperature float ✅ ✅
max_tokens integer ✅ ✅
stream boolean ✅ ✅
tools array ✅ function_calling.py ✅ function-calling.js
reasoning_effort string ✅ ✅
top_p float ✅ ✅
stop array ✅ (as stop_sequences) ✅ (as stopSequences)
safe boolean ✅ (added) ✅ (added)

Supported Models: openai, openai-fast, openai-reasoning, mistral, gemini-search

Reasoning Effort Levels: minimal, low, medium, high

  • ✅ Python: Fully implemented
  • ✅ JavaScript: Fully implemented

✅ Audio Features

Text-to-Speech (TTS)

All 6 Official Voices Supported:

Voice Description Python JavaScript
alloy Neutral, professional voice ✅ ✅
echo Deep, resonant voice ✅ ✅
fable Storyteller vibe voice ✅ ✅
onyx Warm, rich voice ✅ ✅
nova Bright, friendly voice ✅ ✅
shimmer Soft, melodic voice ✅ ✅

TTS Features:

  • ✅ Voice selection
  • ✅ MP3 and WAV export formats
  • ✅ Sample rate configuration
  • ✅ Streaming playback option
  • ✅ Loudness normalization
  • ✅ Multi-voice generation

Speech-to-Text (STT)

STT Features:

  • ✅ Base64-encoded audio input via multimodal endpoint
  • ✅ Multiple audio format support (wav, mp3, etc.)
  • ✅ Word-level timestamps
  • ✅ Punctuation restoration
  • ✅ Speaker diarization support
  • ✅ JSON and SRT export formats
  • ✅ Noise reduction preprocessing

✅ Vision & Multimodal Support

Vision Models

Supported Vision Models:

  • ✅ openai
  • ✅ openai-large
  • ✅ claude-hybridspace

Image Input Methods

Input Method Python JavaScript
Image URL ✅ image_to_text.py::analyze_image_url() ✅ image-to-text.js::analyzeImageUrl()
Base64-encoded images ✅ image_to_text.py::analyze_image_file() ✅ image-to-text.js::analyzeImageFile()
Data URL format ✅ data:image/{format};base64,{data} ✅ data:image/{format};base64,{data}

Audio Input (Multimodal)

Input Method Python JavaScript
Base64-encoded audio ✅ speech_to_text.py::transcribe() ✅ speech-to-text.js::transcribe()
Format specification ✅ input_audio with data and format ✅ input_audio with data and format

✅ Advanced Features

1. Reasoning Controls

Reasoning Effort Presets:

  • ✅ minimal: Quick responses
  • ✅ low: Light reasoning
  • ✅ medium: Balanced approach
  • ✅ high: Deep thinking

Compatible Models: openai, openai-fast, openai-reasoning

Implementation:

  • ✅ Python: text_to_text.py::chat(reasoning_effort="...")
  • ✅ JavaScript: text-to-text.js::chat({reasoningEffort: "..."})

2. Safety Filtering

Safety Features:

  • ✅ safe=true parameter for NSFW filtering
  • ✅ Prompt safety checks
  • ✅ Clear blocked content reporting
  • ✅ Applies to both text and image generation

Implementation:

  • ✅ Python: safe=True parameter in text_to_text.py and text_to_image.py
  • ✅ JavaScript: safe: true parameter in both modules

3. Function Calling / Tool Use

Tool Definition Schema:

  • ✅ JSON schema validation
  • ✅ Function parameter typing
  • ✅ Required/optional parameter handling
  • ✅ Multiple tool support

Example Functions Implemented:

  • ✅ Math operations (add, subtract, multiply, divide)
  • ✅ Random number generation
  • ✅ Equation evaluation
  • ✅ Web value extraction
  • ✅ Normalization utilities

Implementation:

  • ✅ Python: function_calling.py with complete schema support
  • ✅ JavaScript: function-calling.js with complete schema support

4. Streaming Mode (SSE)

Streaming Features:

  • ✅ Token-by-token text streaming
  • ✅ Progress events for image/audio
  • ✅ Heartbeat messages during idle
  • ✅ Retry guidance in headers
  • ✅ Client cancellation support
  • ✅ Real-time feed monitoring

Implementation:

  • ✅ Python: streaming_mode.py::stream_text(), monitor_feed()
  • ✅ JavaScript: streaming-mode.js::streamText(), monitorFeed()

5. Exponential Backoff for Retries

Retry Strategy:

  • ✅ Jittered exponential backoff
  • ✅ Respect for Retry-After headers
  • ✅ Configurable max attempts
  • ✅ Idempotency key support
  • ✅ Retry logging and tagging

Implementation:

  • ✅ Python: pollylib.py::retry_request() and retry_backoff.py
  • ✅ JavaScript: pollylib.js::retryRequest()

6. Seed-Based Deterministic Generation

Seed Features:

  • ✅ Fixed seed for reproducible outputs
  • ✅ Cross-platform seed handling
  • ✅ Randomness source selection
  • ✅ Variance comparison across seeds
  • ✅ Seed logging with outputs

Implementation:

  • ✅ Python: seed parameter in all generation functions
  • ✅ JavaScript: seed parameter in all generation functions

✅ Authentication Methods

API key authentication is supported (per official docs):

Key Type Use Case Python JavaScript
Publishable (pk_) Client-side apps ✅ api_key parameter ✅ apiKey option
Secret (sk_) Backend services ✅ api_key parameter ✅ apiKey option

Get API Key: https://enter.pollinations.ai

Implementation:

  • ✅ Python: PollinationsAPI(api_key="pk_...")
  • ✅ JavaScript: new PollinationsAPI({apiKey: "pk_..."})

Auth Methods:

  • Header: Authorization: Bearer YOUR_API_KEY
  • Query param: ?key=YOUR_API_KEY

✅ Model Information Schema

Text Models - Normalized Schema

All fields from the TODO requirements are implemented:

  • ✅ name and description
  • ✅ max input tokens
  • ✅ reasoning capability flag
  • ✅ tier (anonymous, seed, flower, nectar)
  • ✅ community supported flag
  • ✅ input types array
  • ✅ output types array
  • ✅ tool use / function calling flag
  • ✅ aliases array
  • ✅ vision flag
  • ✅ audio flag
  • ✅ voices array
  • ✅ system messages supported flag
  • ✅ uncensored flag

Image Models - Normalized Schema

All fields from the TODO requirements are implemented:

  • ✅ name and description
  • ✅ style tags
  • ✅ input/output limits (width, height)
  • ✅ supported formats (PNG, JPEG)
  • ✅ image-to-image support flag

Implementation:

  • ✅ Python: model_retrieval.py::_normalize_text_models() and _normalize_image_models()
  • ✅ JavaScript: model-retrieval.js::_normalizeTextModels() and _normalizeImageModels()

✅ Image-to-Image Transformation

Kontext Model Features:

  • ✅ Source image input
  • ✅ Text prompt-guided transformation
  • ✅ Inpainting with mask input
  • ✅ Outpainting with canvas expansion
  • ✅ Text overlay with styling
  • ✅ Meme template mode
  • ✅ EXIF preservation option

Implementation:

  • ✅ Python: image_to_image.py (full module)
  • ✅ JavaScript: image-to-image.js (full module)

✅ Additional Library Features

Testing Utilities (Bonus - Not in API)

Both libraries include comprehensive testing frameworks:

Feature Python JavaScript
Sample Corpus Management ✅ test_utils.py::SampleCorpus ✅ test-utils.js::SampleCorpus
Prompt Fuzzing ✅ test_utils.py::PromptFuzzer ✅ test-utils.js::PromptFuzzer
Chaos Testing ✅ test_utils.py::ChaosTestRunner ✅ test-utils.js::ChaosTestRunner
Memory Profiling ✅ test_utils.py::MemoryProfiler ✅ test-utils.js::MemoryProfiler
Binary Data Handling ✅ test_utils.py::BinaryDataHandler ✅ test-utils.js::BinaryDataHandler
Cold Start Simulation ✅ test_utils.py::ColdStartSimulator ✅ test-utils.js::ColdStartSimulator

📊 Coverage Summary

API Endpoint Coverage: 100% ✅

  • ✅ 3/3 Image endpoints
  • ✅ 4/4 Text endpoints
  • ✅ 2/2 Audio endpoints

Parameter Coverage: 100% ✅

  • ✅ 9/9 Image parameters (including safe)
  • ✅ 7/7 Simple text parameters
  • ✅ 9/9 OpenAI endpoint parameters

Feature Coverage: 100% ✅

  • ✅ All 6 TTS voices
  • ✅ All STT features
  • ✅ All vision/multimodal features
  • ✅ All authentication methods
  • ✅ All advanced features (streaming, reasoning, safety, tools, etc.)

Model Coverage: 100% ✅

  • ✅ All image models (flux, turbo, stable-diffusion, kontext)
  • ✅ All text models (openai, openai-fast, openai-reasoning, mistral, gemini-search)
  • ✅ All audio models (openai-audio)
  • ✅ All vision models (openai, openai-large, claude-hybridspace)

Language Parity: 100% ✅

  • ✅ Python implementation complete
  • ✅ JavaScript implementation complete
  • ✅ Feature-for-feature parity between both languages

🎯 Conclusion

PolliLibPy and PolliLibJS provide complete, production-ready implementations of the entire Pollinations.AI API surface area.

What This Means:

  1. Every documented API endpoint is accessible
  2. Every documented parameter is supported
  3. Every advanced feature is implemented
  4. Both languages have identical capabilities
  5. Additional testing utilities enhance development workflow

Files Summary:

Python (PolliLibPy/):

  • pollylib.py - Base API client with auth and retry logic
  • model_retrieval.py - Model listing and metadata
  • text_to_image.py - Image generation
  • text_to_text.py - Text generation (GET and POST)
  • text_to_speech.py - TTS with all 6 voices
  • speech_to_text.py - STT via multimodal
  • image_to_text.py - Vision/image analysis
  • image_to_image.py - Image transformation
  • function_calling.py - Tool use and function calling
  • streaming_mode.py - SSE streaming and feeds
  • retry_backoff.py - Advanced retry strategies
  • test_utils.py - Comprehensive testing framework
  • __init__.py - Package initialization

JavaScript (PolliLibJS/):

  • pollylib.js - Base API client with auth and retry logic
  • model-retrieval.js - Model listing and metadata
  • text-to-image.js - Image generation
  • text-to-text.js - Text generation (GET and POST)
  • text-to-speech.js - TTS with all 6 voices
  • speech-to-text.js - STT via multimodal
  • image-to-text.js - Vision/image analysis
  • image-to-image.js - Image transformation
  • function-calling.js - Tool use and function calling
  • streaming-mode.js - SSE streaming and feeds
  • test-utils.js - Comprehensive testing framework
  • index.js - Package entry point

📝 References

Last Verified: 2025-11-17 API Version: Latest (as of documentation date) Coverage Status: ✅ COMPLETE - 100%