# 🌸 Blossom AI
A beautiful Python SDK for [Pollinations.AI](https://pollinations.ai) - Generate images, text, and audio with AI.
---
>Warning!!
>
>To generate audio, you need an authentication!!!
---
## ✨ Features
- 🖼️ **Image Generation** - Create stunning images from text descriptions
- 📝 **Text Generation** - Generate text with various models
- 🎙️ **Audio Generation** - Text-to-speech with multiple voices
- 🚀 **Simple API** - Easy to use, beautifully designed
- 🎨 **Beautiful Errors** - Helpful error messages with suggestions
- 🔄 **Reproducible** - Use seeds for consistent results
## 📦 Installation
```bash
pip install eclips-blossom-ai
```
## 🚀 Quick Start
```python
from blossom_ai import Blossom
# Initialize
ai = Blossom()
# Generate an image
ai.image.save("a beautiful sunset over mountains", "sunset.jpg")
# Generate text
response = ai.text.generate("Explain quantum computing in simple terms")
print(response)
# Generate audio
ai.audio.save("Hello, welcome to Blossom AI!", "welcome.mp3")
```
## 📖 Examples
### Image Generation
```python
from blossom_ai import Blossom
ai = Blossom()
# Generate and save an image
ai.image.save(
prompt="a majestic dragon in a mystical forest",
filename="dragon.jpg",
width=1024,
height=1024,
model="flux"
)
# Get image data as bytes
image_data = ai.image.generate("a cute robot")
```
### Text Generation
```python
from blossom_ai import Blossom
ai = Blossom()
# Simple text generation
response = ai.text.generate("What is Python?")
# With system message
response = ai.text.generate(
prompt="Write a haiku about coding",
system="You are a creative poet"
)
# Reproducible results with seed
response = ai.text.generate(
prompt="Generate a random idea",
seed=42 # Same seed = same result
)
# Chat with message history
response = ai.text.chat([
{"role": "system", "content": "You are a helpful assistant"},
{"role": "user", "content": "What's the weather like?"}
])
```
### Audio Generation
```python
from blossom_ai import Blossom
ai = Blossom()
# Generate and save audio
ai.audio.save(
text="Welcome to the future of AI",
filename="welcome.mp3",
voice="nova"
)
# Available voices
voices = ai.audio.voices()
print(voices) # ['alloy', 'echo', 'fable', 'onyx', 'nova', 'shimmer']
```
## 🎯 Supported Parameters
### Text Generation
| Parameter | Type | Description | Supported |
|-----------|------|-------------|-----------|
| `prompt` | str | Your text prompt | ✅ |
| `model` | str | Model to use (default: "openai") | ✅ |
| `system` | str | System message to guide behavior | ✅ |
| `seed` | int | For reproducible results | ✅ |
| `json_mode` | bool | Return JSON response | ✅ |
| `private` | bool | Keep response private | ✅ |
| `temperature` | float | Randomness control | ❌ Not supported in GET API |
**Note:** The current Pollinations.AI GET endpoint doesn't support the `temperature` parameter. For temperature control, you would need to use their POST endpoint, which is currently experiencing issues.
### Image Generation
| Parameter | Type | Description |
|-----------|------|-------------|
| `prompt` | str | Image description |
| `model` | str | Model (default: "flux") |
| `width` | int | Width in pixels |
| `height` | int | Height in pixels |
| `seed` | int | Reproducibility |
| `nologo` | bool | Remove watermark (requires auth) |
| `enhance` | bool | Enhance prompt with AI |
| `safe` | bool | NSFW filtering |
## 🛠️ API Methods
### Blossom Class
```python
ai = Blossom(timeout=30) # Main client
ai.image # ImageGenerator instance
ai.text # TextGenerator instance
ai.audio # AudioGenerator instance
```
### ImageGenerator
```python
# Generate image (returns bytes)
image_data = ai.image.generate(prompt, **options)
# Save image to file
filepath = ai.image.save(prompt, filename, **options)
# List available models
models = ai.image.models()
```
### TextGenerator
```python
# Generate text (simple)
text = ai.text.generate(prompt, **options)
# Chat with message history
text = ai.text.chat(messages, **options)
# List available models
models = ai.text.models()
```
### AudioGenerator
```python
# Generate audio (returns bytes)
audio_data = ai.audio.generate(text, voice="alloy")
# Save audio to file
filepath = ai.audio.save(text, filename, voice="nova")
# List available voices
voices = ai.audio.voices()
```
## 🎨 Error Handling
Blossom AI provides beautiful, helpful error messages:
```python
from blossom_ai import Blossom, BlossomError
ai = Blossom()
try:
response = ai.text.generate("Hello")
except BlossomError as e:
print(f"Error: {e.message}")
print(f"Suggestion: {e.suggestion}")
```
## 📚 More Examples
Check out the `tests/` directory for more detailed examples:
- `01_audio_generation.py` - audio generation examples
- `02_image_generation.py` - Image generation examples
- `03_text_generation.py` - Text generation examples
## 🔑 Authentication (Optional)
For higher rate limits, access to advanced features (like `nologo` for image generation), and to avoid `Payment Required` errors, you can provide an API token.
1. Visit [auth.pollinations.ai](https://auth.pollinations.ai) to register your application and obtain an API token.
2. Pass your API token when initializing the `Blossom` client:
```python
from blossom_ai import Blossom
# Initialize with your API token
ai = Blossom(api_token="YOUR_API_TOKEN_HERE")
# Now you can use features that require authentication, e.g., nologo
ai.image.save("a beautiful sunset", "sunset_no_logo.jpg", nologo=True)
```
If no `api_token` is provided, the library will operate in anonymous mode with default rate limits and feature restrictions.
## 📝 License
MIT License - see LICENSE file for details
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 🐛 Known Issues
- **Temperature parameter**: The GET text endpoint doesn't support `temperature`. This is a limitation of the Pollinations.AI API
- **POST endpoint**: Currently experiencing connectivity issues
## 🔗 Links
- [Pollinations.AI](https://pollinations.ai)
- [API Documentation](https://github.com/pollinations/pollinations)
- [Auth Portal](https://auth.pollinations.ai)
## ❤️ Credits
Built with love using the [Pollinations.AI](https://pollinations.ai) platform.
---
Made with 🌸 by the eclips team
Raw data
{
"_id": null,
"home_page": null,
"name": "eclips-blossom-ai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Eclips Team <develop@eclips-team.ru>",
"keywords": "ai, artificial-intelligence, audio-generation, deep-learning, generative-ai, gpt, image-generation, llm, machine-learning, pollinations, stable-diffusion, text-generation, text-to-speech, tts",
"author": null,
"author_email": "Eclips Team <develop@eclips-team.ru>",
"download_url": "https://files.pythonhosted.org/packages/84/0f/870e4a25ebe29bf7c1a2d9dbbfed55b1ce229baf35e90fb493da0be1c1f0/eclips_blossom_ai-0.1.2.tar.gz",
"platform": null,
"description": "# \ud83c\udf38 Blossom AI\n\nA beautiful Python SDK for [Pollinations.AI](https://pollinations.ai) - Generate images, text, and audio with AI.\n\n\n\n---\n>Warning!!\n> \n>To generate audio, you need an authentication!!!\n---\n## \u2728 Features\n\n- \ud83d\uddbc\ufe0f **Image Generation** - Create stunning images from text descriptions\n- \ud83d\udcdd **Text Generation** - Generate text with various models\n- \ud83c\udf99\ufe0f **Audio Generation** - Text-to-speech with multiple voices\n- \ud83d\ude80 **Simple API** - Easy to use, beautifully designed\n- \ud83c\udfa8 **Beautiful Errors** - Helpful error messages with suggestions\n- \ud83d\udd04 **Reproducible** - Use seeds for consistent results\n\n## \ud83d\udce6 Installation\n\n```bash\npip install eclips-blossom-ai\n```\n\n## \ud83d\ude80 Quick Start\n\n```python\nfrom blossom_ai import Blossom\n\n# Initialize\nai = Blossom()\n\n# Generate an image\nai.image.save(\"a beautiful sunset over mountains\", \"sunset.jpg\")\n\n# Generate text\nresponse = ai.text.generate(\"Explain quantum computing in simple terms\")\nprint(response)\n\n# Generate audio\nai.audio.save(\"Hello, welcome to Blossom AI!\", \"welcome.mp3\")\n```\n\n## \ud83d\udcd6 Examples\n\n### Image Generation\n\n```python\nfrom blossom_ai import Blossom\n\nai = Blossom()\n\n# Generate and save an image\nai.image.save(\n prompt=\"a majestic dragon in a mystical forest\",\n filename=\"dragon.jpg\",\n width=1024,\n height=1024,\n model=\"flux\"\n)\n\n# Get image data as bytes\nimage_data = ai.image.generate(\"a cute robot\")\n```\n\n### Text Generation\n\n```python\nfrom blossom_ai import Blossom\n\nai = Blossom()\n\n# Simple text generation\nresponse = ai.text.generate(\"What is Python?\")\n\n# With system message\nresponse = ai.text.generate(\n prompt=\"Write a haiku about coding\",\n system=\"You are a creative poet\"\n)\n\n# Reproducible results with seed\nresponse = ai.text.generate(\n prompt=\"Generate a random idea\",\n seed=42 # Same seed = same result\n)\n\n# Chat with message history\nresponse = ai.text.chat([\n {\"role\": \"system\", \"content\": \"You are a helpful assistant\"},\n {\"role\": \"user\", \"content\": \"What's the weather like?\"}\n])\n```\n\n### Audio Generation\n\n```python\nfrom blossom_ai import Blossom\n\nai = Blossom()\n\n# Generate and save audio\nai.audio.save(\n text=\"Welcome to the future of AI\",\n filename=\"welcome.mp3\",\n voice=\"nova\"\n)\n\n# Available voices\nvoices = ai.audio.voices()\nprint(voices) # ['alloy', 'echo', 'fable', 'onyx', 'nova', 'shimmer']\n```\n\n## \ud83c\udfaf Supported Parameters\n\n### Text Generation\n\n| Parameter | Type | Description | Supported |\n|-----------|------|-------------|-----------|\n| `prompt` | str | Your text prompt | \u2705 |\n| `model` | str | Model to use (default: \"openai\") | \u2705 |\n| `system` | str | System message to guide behavior | \u2705 |\n| `seed` | int | For reproducible results | \u2705 |\n| `json_mode` | bool | Return JSON response | \u2705 |\n| `private` | bool | Keep response private | \u2705 |\n| `temperature` | float | Randomness control | \u274c Not supported in GET API |\n\n**Note:** The current Pollinations.AI GET endpoint doesn't support the `temperature` parameter. For temperature control, you would need to use their POST endpoint, which is currently experiencing issues.\n\n### Image Generation\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `prompt` | str | Image description |\n| `model` | str | Model (default: \"flux\") |\n| `width` | int | Width in pixels |\n| `height` | int | Height in pixels |\n| `seed` | int | Reproducibility |\n| `nologo` | bool | Remove watermark (requires auth) |\n| `enhance` | bool | Enhance prompt with AI |\n| `safe` | bool | NSFW filtering |\n\n## \ud83d\udee0\ufe0f API Methods\n\n### Blossom Class\n\n```python\nai = Blossom(timeout=30) # Main client\n\nai.image # ImageGenerator instance\nai.text # TextGenerator instance \nai.audio # AudioGenerator instance\n```\n\n### ImageGenerator\n\n```python\n# Generate image (returns bytes)\nimage_data = ai.image.generate(prompt, **options)\n\n# Save image to file\nfilepath = ai.image.save(prompt, filename, **options)\n\n# List available models\nmodels = ai.image.models()\n```\n\n### TextGenerator\n\n```python\n# Generate text (simple)\ntext = ai.text.generate(prompt, **options)\n\n# Chat with message history\ntext = ai.text.chat(messages, **options)\n\n# List available models\nmodels = ai.text.models()\n```\n\n### AudioGenerator\n\n```python\n# Generate audio (returns bytes)\naudio_data = ai.audio.generate(text, voice=\"alloy\")\n\n# Save audio to file\nfilepath = ai.audio.save(text, filename, voice=\"nova\")\n\n# List available voices\nvoices = ai.audio.voices()\n```\n\n## \ud83c\udfa8 Error Handling\n\nBlossom AI provides beautiful, helpful error messages:\n\n```python\nfrom blossom_ai import Blossom, BlossomError\n\nai = Blossom()\n\ntry:\n response = ai.text.generate(\"Hello\")\nexcept BlossomError as e:\n print(f\"Error: {e.message}\")\n print(f\"Suggestion: {e.suggestion}\")\n```\n\n## \ud83d\udcda More Examples\n\nCheck out the `tests/` directory for more detailed examples:\n\n- `01_audio_generation.py` - audio generation examples\n- `02_image_generation.py` - Image generation examples\n- `03_text_generation.py` - Text generation examples\n\n## \ud83d\udd11 Authentication (Optional)\n\nFor higher rate limits, access to advanced features (like `nologo` for image generation), and to avoid `Payment Required` errors, you can provide an API token.\n\n1. Visit [auth.pollinations.ai](https://auth.pollinations.ai) to register your application and obtain an API token.\n2. Pass your API token when initializing the `Blossom` client:\n\n ```python\n from blossom_ai import Blossom\n\n # Initialize with your API token\n ai = Blossom(api_token=\"YOUR_API_TOKEN_HERE\")\n\n # Now you can use features that require authentication, e.g., nologo\n ai.image.save(\"a beautiful sunset\", \"sunset_no_logo.jpg\", nologo=True)\n ```\n\n If no `api_token` is provided, the library will operate in anonymous mode with default rate limits and feature restrictions.\n\n## \ud83d\udcdd License\n\nMIT License - see LICENSE file for details\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## \ud83d\udc1b Known Issues\n\n- **Temperature parameter**: The GET text endpoint doesn't support `temperature`. This is a limitation of the Pollinations.AI API\n- **POST endpoint**: Currently experiencing connectivity issues\n\n## \ud83d\udd17 Links\n\n- [Pollinations.AI](https://pollinations.ai)\n- [API Documentation](https://github.com/pollinations/pollinations)\n- [Auth Portal](https://auth.pollinations.ai)\n\n## \u2764\ufe0f Credits\n\nBuilt with love using the [Pollinations.AI](https://pollinations.ai) platform.\n\n---\n\nMade with \ud83c\udf38 by the eclips team",
"bugtrack_url": null,
"license": "MIT",
"summary": "\ud83c\udf38 Beautiful and simple AI generation library for images, text, and audio",
"version": "0.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/PrimeevolutionZ/blossom-ai/issues",
"Changelog": "https://github.com/PrimeevolutionZ/blossom-ai/releases",
"Discussions": "https://github.com/PrimeevolutionZ/blossom-ai/discussions",
"Documentation": "https://github.com/PrimeevolutionZ/blossom-ai#readme",
"Homepage": "https://github.com/PrimeevolutionZ/blossom-ai",
"Issue Tracker": "https://github.com/PrimeevolutionZ/blossom-ai/issues",
"Repository": "https://github.com/PrimeevolutionZ/blossom-ai",
"Source Code": "https://github.com/PrimeevolutionZ/blossom-ai"
},
"split_keywords": [
"ai",
" artificial-intelligence",
" audio-generation",
" deep-learning",
" generative-ai",
" gpt",
" image-generation",
" llm",
" machine-learning",
" pollinations",
" stable-diffusion",
" text-generation",
" text-to-speech",
" tts"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "73b0f72789be08fba85a7c041f38d3ea51cdda063eff7e6e831c7de223c5c6d6",
"md5": "5562d2ca07db87b16621ae6b16663383",
"sha256": "9de1e10194ed7417b7d4e5e096967a0b2c4773df020bdb1f07b890a1c7a4599e"
},
"downloads": -1,
"filename": "eclips_blossom_ai-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5562d2ca07db87b16621ae6b16663383",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10819,
"upload_time": "2025-10-10T11:40:51",
"upload_time_iso_8601": "2025-10-10T11:40:51.930492Z",
"url": "https://files.pythonhosted.org/packages/73/b0/f72789be08fba85a7c041f38d3ea51cdda063eff7e6e831c7de223c5c6d6/eclips_blossom_ai-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "840f870e4a25ebe29bf7c1a2d9dbbfed55b1ce229baf35e90fb493da0be1c1f0",
"md5": "738bec3fe33bfca65bdc2fa73035ec9e",
"sha256": "54cf37dd95dfe7632c85876411b51e08e3450e0c6581ce70dfbf95b296d4d758"
},
"downloads": -1,
"filename": "eclips_blossom_ai-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "738bec3fe33bfca65bdc2fa73035ec9e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19575,
"upload_time": "2025-10-10T11:40:53",
"upload_time_iso_8601": "2025-10-10T11:40:53.139537Z",
"url": "https://files.pythonhosted.org/packages/84/0f/870e4a25ebe29bf7c1a2d9dbbfed55b1ce229baf35e90fb493da0be1c1f0/eclips_blossom_ai-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-10 11:40:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PrimeevolutionZ",
"github_project": "blossom-ai",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "eclips-blossom-ai"
}
JSON
