nexusai-py 5.0.3

A comprehensive Python wrapper for the Nexus AI API

Nexus AI - Python Client Library

A comprehensive Python wrapper for the Nexus AI API - providing access to 14 image generation models, 20+ text generation models, and interactive Akinator game API.

🚀 Features

• 🎨 Image Generation: 14 AI models including Flux, Stable Diffusion, and specialized models
• 💬 Text Generation: 20+ models (Gemini, GPT-4, Llama, Qwen, DeepSeek, and more)
• ⚡ Real-time Streaming: ChatGPT-like streaming responses for text generation
• 👁️ Image Vision: Analyze images with Gemini models
• 💾 Conversation History: Automatic conversation context management
• 🎮 Akinator Game: Interactive guessing game API
• 🔒 Type Safe: Full type hints for better IDE support
• 📦 Easy to Use: Simple and intuitive API

📋 Table of Contents

• Installation
• Getting Your API Key
• Quick Start
• Image Generation
• Text Generation
• Streaming Responses
• Image Vision
• Akinator Game
• Error Handling
• Rate Limits
• Examples
• Support

💻 Installation

Install using pip:

pip install nexusai-py

Or install from source:

git clone https://github.com/yourusername/nexusai-py.git
cd nexusai-py
pip install -e .

🔑 Getting Your API Key (100% Free!)

1. Go to Nexus

2. Click "Try Now For Free" and sign in (Discord or Google recommended)

3. Click "Try Now For Free" again to access the dashboard

4. Scroll down to find the "Your API Key" box - that's your key!

Free Plan Includes:

• ✅ 500 requests per day
• ✅ Access to all 14 image generation models
• ✅ Access to all 20+ text generation models
• ✅ Up to 2048x2048 image resolution
• ✅ Real-time streaming support
• ✅ Image vision capabilities
• ✅ Conversation history
• ✅ Akinator game API

🚀 Quick Start

from nexusai import NexusAI

# Initialize the client
client = NexusAI(api_key="your-api-key-here")

# Generate an image
result = client.generate_image(
    prompt="A futuristic city at sunset",
    model="flux",
    width=1024,
    height=768
)

# Get the full image URL
image_url = client.get_full_image_url(result['imageUrl'])
print(f"Image URL: {image_url}")

# Generate text
response = client.generate_text(
    model="gemini-2.5-flash",
    prompt="Explain quantum computing in simple terms"
)
print(response['completion'])

🎨 Image Generation

Basic Usage

# Generate an image
result = client.generate_image(
    prompt="A beautiful mountain landscape",
    model="flux",
    width=1024,
    height=768
)

# The API returns a relative path
print(result['imageUrl'])  # /data/generated-images/abc123.png

# Convert to full URL
full_url = client.get_full_image_url(result['imageUrl'])
print(full_url)  # https://nexus.drexus.xyz/data/generated-images/abc123.png

Available Models

Model	Description	Best For
flux	High-quality general purpose	Realistic images
flux-realism	Photo-realistic generation	Photography style
flux-anime	Anime-style images	Anime characters & art
flux-3d	3D rendered style	3D model visualization
flux-pro	Professional quality	High-end production
any-dark	Dark mode optimized	Dark themes & moods
turbo	Fast generation	Quick prototyping
stable-diffusion	Classic SD model	General purpose
stable-diffusion-animation	Animation frames	Animation sequences
photo3d	3D photo-like	3D-like photos

Advanced Example

# High-resolution anime artwork
result = client.generate_image(
    prompt="A cyberpunk warrior in neon city, highly detailed anime style",
    model="flux-anime",
    width=2048,
    height=2048
)

# Save the image
import requests
from PIL import Image
from io import BytesIO

image_url = client.get_full_image_url(result['imageUrl'])
response = requests.get(image_url)
img = Image.open(BytesIO(response.content))
img.save("output.png")
print("Image saved as output.png")

💬 Text Generation

Basic Usage

# Simple text generation
response = client.generate_text(
    model="gemini-2.5-flash",
    prompt="Write a short poem about the ocean"
)
print(response['completion'])

With System Instructions

# Control the AI's behavior
response = client.generate_text(
    model="gemini-2.5-pro",
    prompt="How do I center a div?",
    system_instruction="You are a senior web developer. Always provide modern CSS solutions with code examples.",
    temperature=0.7
)
print(response['completion'])

Available Models

Google Gemini:

• gemini-2.5-flash - Latest fast model
• gemini-2.5-pro - Most capable model
• gemini-2.0-flash - Fast and efficient
• And more Gemini variants...

OpenAI:

• gpt-4 - Advanced reasoning

Meta AI:

• llama-3.3-70b-instruct - Meta Llama 3.3

Alibaba Cloud:

• qwen2.5-coder-32b - Specialized for code

DeepSeek:

• deepseek-r1 - Advanced reasoning
• deepseek-v3.1 - Latest version

And many more!

Conversation History

# First message
response1 = client.generate_text(
    model="gemini-2.5-flash",
    prompt="My name is Alice",
    userid="user123"
)

# Follow-up - the AI remembers!
response2 = client.generate_text(
    model="gemini-2.5-flash",
    prompt="What's my name?",
    userid="user123"
)
print(response2['completion'])  # Should mention "Alice"

# Clear history when done
client.clear_conversation_history("user123")

⚡ Streaming Responses

Get real-time streaming responses like ChatGPT:

# Stream text as it's generated
print("AI: ", end='', flush=True)
for chunk in client.generate_text(
    model="gemini-2.5-flash",
    prompt="Write a short story about a robot",
    stream=True
):
    print(chunk, end='', flush=True)
print()  # New line at the end

Streaming is supported by:

• All Google Gemini models
• All Meta Llama models
• All Qwen models
• DeepSeek models
• GPT-4
• And more!

👁️ Image Vision

Analyze images with Gemini models:

Single Image

# Analyze an image from URL
response = client.generate_text(
    model="gemini-2.5-flash",
    prompt="What objects are in this image?",
    images="https://example.com/photo.jpg"
)
print(response['completion'])

Multiple Images

# Compare multiple images
response = client.generate_text(
    model="gemini-2.5-pro",
    prompt="Compare these two images and describe the differences",
    images=[
        "https://example.com/image1.jpg",
        "https://example.com/image2.jpg"
    ]
)
print(response['completion'])

Base64 Images

# Use base64 encoded image data
response = client.generate_text(
    model="gemini-2.5-flash",
    prompt="Describe this image in detail",
    images={
        "data": "iVBORw0KGgoAAAANSUhEUgAA...",
        "mimeType": "image/png"
    }
)

Note: Image vision is only available with Gemini models!

🎮 Akinator Game

Play the interactive guessing game:

# Start a new game
game = client.start_akinator_game(region="en")
game_id = game['gameId']
print(game['question'])
print("Answers:", game['answers'])

# Answer questions
while True:
    answer = input("Your answer (yes/no/dont-know/probably/probably-not): ")
    
    result = client.answer_akinator(game_id, answer)
    
    # Check if character was guessed
    if result.get('solved'):
        print(f"\nFound it! {result['name']}")
        print(f"Description: {result['description']}")
        break
    
    # Next question
    print(f"\nProgress: {result['progress']}%")
    print(result['question'])

# Clean up
client.delete_akinator_game(game_id)

Additional Akinator Features

# Go back to previous question
previous = client.akinator_go_back(game_id)

# Check current progress
progress = client.get_akinator_progress(game_id)
print(f"Progress: {progress['progress']}%")

# Available regions: en, es, fr, de, it, pt, ru, jp, zh
game = client.start_akinator_game(region="es", child_mode=True)

⚠️ Error Handling

The library provides specific exceptions for different error types:

from nexusai import NexusAI
from nexusai.exceptions import (
    AuthenticationError,
    RateLimitError,
    BadRequestError,
    ServerError
)

client = NexusAI(api_key="your-api-key")

try:
    result = client.generate_image(prompt="A sunset")
except AuthenticationError as e:
    print(f"Invalid API key: {e}")
except RateLimitError as e:
    print(f"Rate limit exceeded: {e}")
except BadRequestError as e:
    print(f"Invalid parameters: {e}")
except ServerError as e:
    print(f"Server error: {e}")

Error Codes

Code	Exception	Description
400	BadRequestError	Missing or invalid parameters
401	AuthenticationError	Invalid or missing API key
404	NotFoundError	Resource not found
429	RateLimitError	Rate limit exceeded (500/day)
500	ServerError	Internal server error

📊 Rate Limits

Free Plan:

• 500 requests per day
• Resets every 24 hours
• Applies to all endpoints combined

Tips:

• Use streaming for long text generation (counts as 1 request)
• Cache image URLs (they're valid for 2 hours)
• Reuse conversation history instead of re-sending context

📚 Examples

Check out the examples/ directory for complete working examples:

• examples/image_generation.py - All image generation features
• examples/text_generation.py - Text generation with streaming
• examples/akinator_game.py - Interactive Akinator game

Run an example:

python examples/image_generation.py

🆘 Support

• Discord: https://discord.gg/qdgkMkQbnt
• Email: [e-mail]
• Website: https://nexus.drexus.xyz
• Documentation: https://nexus.drexus.xyz/docs

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

⚡ Built With

• requests - HTTP library for Python
• typing - Type hints support

---

Nexus AI - All AI, One API.

© 2025 Nexus API. All rights reserved.