Free.ai Python SDK

Access hundreds of AI tools from your Python code. Chat, image generation, text to speech, translation, video, music, and more.

Website | API Docs | PyPI | CLI Tool

Install

pip install free-dot-ai

Quick Start

from freeai import FreeAI

ai = FreeAI(api_key="sk-free-xxx")  # or FreeAI() for anonymous

# Chat on a self-hosted model — free, no key needed, within the daily pool
response = ai.chat("What is Python?")
print(response.text)

# A premium model (anything with a provider prefix) needs purchased tokens.
# Free and anonymous callers get InsufficientCreditsError here, and the
# message tells you the cost, your balance and the shortfall.
response = ai.chat("Explain quantum computing", model="openai/gpt-4o")
print(response.text)

# Image generation
image = ai.image("A sunset over mountains")
image.save("sunset.png")

# Text to speech
audio = ai.tts("Hello world", voice="af_heart")
audio.save("hello.mp3")

# Translation
result = ai.translate("Hello", to="es")
print(result.text)  # "Hola"

# Speech to text
transcript = ai.stt(url="https://example.com/audio.mp3")
print(transcript.text)

# Music generation
music = ai.music("Upbeat jazz piano")
music.save("jazz.mp3")

# Video generation
video = ai.video("A cat walking through a garden")
video.save("cat.mp4")

BYOK (Bring Your Own Key)

Use your own API keys from any provider. Zero markup.

# OpenAI
ai = FreeAI(provider="openai", api_key="sk-proj-xxx")
response = ai.chat("Hello", model="gpt-4o")

# Anthropic
ai = FreeAI(provider="anthropic", api_key="sk-ant-xxx")
response = ai.chat("Hello", model="claude-sonnet-4")

# Google
ai = FreeAI(provider="google", api_key="AIzaSyxxx")
response = ai.chat("Hello", model="gemini-2.5-pro")

# OpenRouter (346+ models)
ai = FreeAI(provider="openrouter", api_key="sk-or-xxx")
response = ai.chat("Hello", model="meta-llama/llama-3.3-70b")

Or via environment variables:

export FREEAI_API_KEY=sk-proj-xxx
export FREEAI_PROVIDER=openai

ai = FreeAI()  # picks up env vars automatically

All Methods

Response Objects

Every response has:

• Typed attributes (.text, .url, etc.)
• .usage — token usage info (.tokens_used, .tokens_charged, .source, .model)
• .raw — the full JSON response dict

Media responses (image, tts, music, video) have a .save(path) method to download the file.

Models

Self-Hosted (cheapest)

OpenRouter (346+ models)

Use the provider/model format:

ai.chat("Hello", model="openai/gpt-4o")
ai.chat("Hello", model="anthropic/claude-sonnet-4")
ai.chat("Hello", model="google/gemini-2.5-pro")
ai.chat("Hello", model="meta-llama/llama-3.3-70b")
ai.chat("Hello", model="deepseek/deepseek-chat-v3")

Full list: free.ai/models/ or ai.models()

Pricing

• Anonymous: Daily free limits (no API key needed)
• Free account: 50K tokens/day (sign up)
• Paid plans: From $5/month (pricing)
• BYOK: $0 — your key, your bill, zero markup

Error Handling

from freeai import FreeAI, AuthenticationError, RateLimitError, InsufficientCreditsError

ai = FreeAI(api_key="sk-free-xxx")

try:
    response = ai.chat("Hello")
except AuthenticationError:
    print("Bad API key")
except InsufficientCreditsError:
    print("Out of tokens — buy more at free.ai/pricing/")
except RateLimitError:
    print("Too many requests — slow down")

Free.ai Ecosystem

• Free.ai — hundreds of free AI tools on the web
• Python SDK — pip install free-dot-ai (you are here)
• CLI Coder — pip install freeai-code — AI coding in your terminal
• iOS App — Native iPhone/iPad app
• Android App — Native Android app
• API Docs — Full API reference
• Web IDE — Code in your browser

License

MIT