nellie-api 0.1.0

Python client for the Nellie AI Book Generation API

Nellie Python SDK

The official Python client for the Nellie AI Book Generation API.

SDK Version: 0.1.0
API Version: v1

Installation

pip install nellie-api

Usage

Basic Book Generation

from nellie_api import Nellie

client = Nellie(api_key="nel_...")

# Start a book generation job
book = client.books.create(
    prompt="A sci-fi mystery about a lost colony on Mars",
    style="sci_fi",
    type="novel"
)

print(f"Book started! ID: {book.request_id}")

# Check status
status = client.books.retrieve(book.request_id)
print(f"Status: {status.status} ({status.progress}%)")

if status.status == "completed":
    print(f"Download URL: {status.result_url}")

Waiting for Completion

Use the built-in polling helper to wait for a job to finish:

from nellie_api import Nellie

client = Nellie(api_key="nel_...")

book = client.books.create(prompt="A fantasy adventure")

# Block until complete (with progress callback)
result = client.books.wait_for_completion(
    book.request_id,
    poll_interval=120,  # Check every 2 minutes (minimum: 60s)
    timeout=7200,       # Max wait time: 2 hours
    on_progress=lambda s: print(f"Progress: {s.progress}%")
)

if result.is_successful():
    print(f"Done! Download: {result.result_url}")
else:
    print(f"Failed: {result.error}")

Getting Configuration Options

Fetch available styles, types, and output formats:

config = client.get_configuration()
print(f"Available styles: {config.styles}")
print(f"Available types: {config.types}")
print(f"Available formats: {config.formats}")

Getting Available Models

Retrieve available generation models and their costs:

models = client.get_models()
for model in models:
    print(f"{model.name}: {model.cost_per_book} credits")

Checking Usage Statistics

Get your credit consumption and request history:

usage = client.get_usage()
print(f"Total requests: {usage.total_requests}")
print(f"Total credits used: {usage.total_credits_used}")

for req in usage.recent_requests:
    print(f"  {req.request_id}: {req.status} ({req.credits_used} credits)")

Type Hints

The SDK exports type literals for better IDE support:

from nellie_api import BookStyle, BookType, ModelVersion, OutputFormat

style: BookStyle = "sci_fi"
type: BookType = "novel"

Configuration

You can configure the client using environment variables or constructor arguments.

Environment Variables:

• NELLIE_API_KEY: Your API key.
• NELLIE_API_BASE_URL: (Optional) Override the API base URL.

Constructor:

client = Nellie(
    api_key="nel_...", 
    base_url="https://api.nelliewriter.com",  # SDK automatically uses /v1 paths
    max_retries=3,  # Configures automatic retries for rate limits
    timeout=30      # Request timeout in seconds (default: 30)
)

Webhooks

Verify incoming webhooks securely using the built-in utility:

from nellie_api import Webhook, WebhookSignatureError
import os

# Your webhook secret from the dashboard
webhook_secret = os.environ.get("NELLIE_WEBHOOK_SECRET")

# In your Flask/Django/FastAPI route:
def webhook_handler(request):
    payload = request.data
    sig_header = request.headers.get("X-Nellie-Signature")

    try:
        event = Webhook.construct_event(
            payload, sig_header, webhook_secret
        )
    except WebhookSignatureError as e:
        return "Invalid signature", 400

    # Handle the event
    if event.status == "completed":
        print(f"Book ready: {event.result_url}")
    
    return "Success", 200

Error Handling

The SDK raises exceptions for various error conditions:

• AuthenticationError: Invalid API key (HTTP 401).
• RateLimitError: Too many requests (HTTP 429).
• APIError: General API errors (e.g. invalid parameters, server errors).
• NellieError: Base class for all SDK errors.

from nellie_api import Nellie, APIError, AuthenticationError, RateLimitError

try:
    client.books.create(...)
except AuthenticationError:
    print("Check your API key")
except RateLimitError:
    print("Rate limit exceeded - wait before retrying")
except APIError as e:
    print(f"API Error: {e}")