> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getalai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Examples & Use Cases
> Complete Python examples and real-world use cases for the Alai API.
This guide provides complete, working examples for common Alai API workflows. All examples use Python with the `requests` library.
## Installation
```bash theme={null}
pip install requests
```
***
## AlaiClient Helper Class
Copy this helper class to simplify your Alai API integrations. It handles polling, error handling, and provides a clean interface for all operations.
```python theme={null}
"""
Alai API Python Client
A simple wrapper for common Alai API operations
"""
import requests
import time
from typing import List, Optional
class AlaiClient:
"""Simple Python client for the Alai API."""
def __init__(self, api_key: str):
self.api_key = api_key
self.base_url = "https://slides-api.getalai.com/api/v1"
self.headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
def generate_presentation(
self,
content: str,
title: str = "Presentation",
slide_range: str = "auto",
theme_id: Optional[str] = None,
export_formats: List[str] = None,
image_ids: List[str] = None,
wait: bool = True,
timeout: int = 300
) -> dict:
"""
Generate a presentation from text content.
Args:
content: The text content to transform into slides
title: Presentation title
slide_range: Number of slides ("auto", "1", "2-5", "6-10", etc.)
theme_id: Theme ID from get_themes(). Legacy theme display names still work but are deprecated.
export_formats: List of formats ["link", "pdf", "ppt"]
image_ids: List of image IDs from upload_images()
wait: If True, polls until completion
timeout: Max seconds to wait
Returns:
Generation result with presentation URLs
"""
if export_formats is None:
export_formats = ["link"]
payload = {
"input_text": content,
"presentation_options": {
"title": title,
"slide_range": slide_range
},
"export_formats": export_formats
}
if theme_id:
payload["presentation_options"]["theme_id"] = theme_id
if image_ids:
payload["image_ids"] = image_ids
response = requests.post(
f"{self.base_url}/generations",
headers=self.headers,
json=payload
)
response.raise_for_status()
result = response.json()
if wait:
return self.wait_for_completion(result["generation_id"], timeout)
return result
def get_themes(self) -> List[dict]:
"""
List available themes for the authenticated user.
Returns:
List of theme objects with `id` and `name`
"""
response = requests.get(
f"{self.base_url}/themes",
headers=self.headers
)
response.raise_for_status()
return response.json()["themes"]
def wait_for_completion(self, generation_id: str, timeout: int = 300) -> dict:
"""
Poll until a generation completes or fails.
Args:
generation_id: The ID returned from an async operation
timeout: Max seconds to wait
Returns:
Final generation status with results
Raises:
Exception: If generation fails
TimeoutError: If timeout exceeded
"""
start = time.time()
while time.time() - start < timeout:
response = requests.get(
f"{self.base_url}/generations/{generation_id}",
headers=self.headers
)
response.raise_for_status()
result = response.json()
if result["status"] == "completed":
return result
elif result["status"] == "failed":
raise Exception(f"Generation failed: {result.get('error')}")
time.sleep(3)
raise TimeoutError(f"Generation {generation_id} timed out after {timeout}s")
def add_slide(
self,
presentation_id: str,
content: str,
instructions: str = None,
position: int = None,
wait: bool = True
) -> dict:
"""
Add a slide to an existing presentation.
Args:
presentation_id: ID of the presentation
content: Content for the new slide
instructions: Additional styling instructions
position: Slide position (None = append at end)
wait: If True, polls until completion
Returns:
Generation result with slide_id
"""
payload = {
"slide_context": content,
"options": {}
}
if instructions:
payload["options"]["additional_instructions"] = instructions
if position is not None:
payload["options"]["slide_order"] = position
response = requests.post(
f"{self.base_url}/presentations/{presentation_id}/slides",
headers=self.headers,
json=payload
)
response.raise_for_status()
result = response.json()
if wait:
return self.wait_for_completion(result["generation_id"])
return result
def export(
self,
presentation_id: str,
formats: List[str] = None,
wait: bool = True
) -> dict:
"""
Export a presentation to specified formats.
Args:
presentation_id: ID of the presentation
formats: List of formats ["link", "pdf", "ppt"]
wait: If True, polls until completion
Returns:
Export result with download URLs
"""
if formats is None:
formats = ["link", "pdf"]
response = requests.post(
f"{self.base_url}/presentations/{presentation_id}/exports",
headers=self.headers,
json={"formats": formats}
)
response.raise_for_status()
result = response.json()
if wait:
return self.wait_for_completion(result["generation_id"])
return result
def upload_images(self, file_paths: List[str]) -> List[str]:
"""
Upload images for use in presentations.
Args:
file_paths: List of local file paths
Returns:
List of image IDs to use in generation requests
"""
files = [("files", open(path, "rb")) for path in file_paths]
response = requests.post(
f"{self.base_url}/upload-images",
headers={"Authorization": f"Bearer {self.api_key}"},
files=files
)
response.raise_for_status()
return response.json()["image_ids"]
def delete_presentation(self, presentation_id: str) -> bool:
"""Delete a presentation."""
response = requests.delete(
f"{self.base_url}/presentations/{presentation_id}",
headers=self.headers
)
response.raise_for_status()
return response.json().get("success", False)
def delete_slide(self, presentation_id: str, slide_id: str) -> bool:
"""Delete a slide from a presentation."""
response = requests.delete(
f"{self.base_url}/presentations/{presentation_id}/slides/{slide_id}",
headers=self.headers
)
response.raise_for_status()
return response.json().get("success", False)
```
Save this as `alai_client.py` and import it in your projects: `from alai_client import AlaiClient`
***
## Example 1: Generate a Simple Presentation
The most basic use case - turn text into a presentation.
```python theme={null}
from alai_client import AlaiClient
client = AlaiClient("your_api_key")
theme_id = client.get_themes()[0]["id"]
# Generate a presentation from text
result = client.generate_presentation(
content="""
Introduction to Machine Learning
Machine learning is a subset of artificial intelligence that enables
systems to learn and improve from experience without being explicitly
programmed.
Key concepts:
- Supervised Learning: Learning from labeled data
- Unsupervised Learning: Finding patterns in unlabeled data
- Reinforcement Learning: Learning through trial and error
Applications include image recognition, natural language processing,
recommendation systems, and autonomous vehicles.
""",
title="Introduction to Machine Learning",
slide_range="6-10",
theme_id=theme_id,
export_formats=["link", "pdf"]
)
print(f"View online: {result['formats']['link']['url']}")
print(f"Download PDF: {result['formats']['pdf']['url']}")
```
***
## Example 2: Weekly Report Generator
Automate recurring presentations like weekly reports.
```python theme={null}
from alai_client import AlaiClient
from datetime import datetime
client = AlaiClient("your_api_key")
default_theme_id = client.get_themes()[0]["id"]
def generate_weekly_report(metrics: dict) -> dict:
"""Generate a weekly report presentation from metrics."""
week_num = datetime.now().isocalendar()[1]
year = datetime.now().year
content = f"""
Weekly Business Report - Week {week_num}, {year}
Revenue Performance:
- Total Revenue: ${metrics['revenue']:,.0f}
- Week-over-Week Change: {metrics['revenue_change']:+.1f}%
- Year-to-Date: ${metrics['ytd_revenue']:,.0f}
Customer Metrics:
- New Customers: {metrics['new_customers']}
- Churn Rate: {metrics['churn_rate']:.1f}%
- Net Promoter Score: {metrics['nps']}
Top Products:
1. {metrics['top_products'][0]['name']} - ${metrics['top_products'][0]['revenue']:,.0f}
2. {metrics['top_products'][1]['name']} - ${metrics['top_products'][1]['revenue']:,.0f}
3. {metrics['top_products'][2]['name']} - ${metrics['top_products'][2]['revenue']:,.0f}
Key Highlights:
{chr(10).join(f"- {h}" for h in metrics['highlights'])}
Challenges & Action Items:
{chr(10).join(f"- {c}" for c in metrics['challenges'])}
"""
return client.generate_presentation(
content=content,
title=f"Weekly Report - W{week_num}",
slide_range="6-10",
theme_id=default_theme_id,
export_formats=["link", "pdf", "ppt"]
)
# Example usage
metrics = {
"revenue": 1_250_000,
"revenue_change": 15.3,
"ytd_revenue": 45_000_000,
"new_customers": 47,
"churn_rate": 2.1,
"nps": 72,
"top_products": [
{"name": "Enterprise Plan", "revenue": 450_000},
{"name": "Team Plan", "revenue": 380_000},
{"name": "Starter Plan", "revenue": 370_000}
],
"highlights": [
"Closed 3 enterprise deals worth $500K+",
"Product launch exceeded expectations by 40%",
"Customer satisfaction at all-time high"
],
"challenges": [
"APAC region underperforming targets",
"Support ticket volume up 20%"
]
}
result = generate_weekly_report(metrics)
print(f"Report ready: {result['formats']['link']['url']}")
```
***
## Example 3: Document to Slides
Convert meeting notes, documents, or any text file into a presentation.
```python theme={null}
from alai_client import AlaiClient
client = AlaiClient("your_api_key")
# Read content from a file
with open("meeting_notes.txt", "r") as f:
notes = f.read()
# Generate presentation
result = client.generate_presentation(
content=notes,
title="Product Roadmap Review - Q1 Planning",
slide_range="11-15",
export_formats=["link", "ppt"]
)
print(f"Presentation: {result['formats']['link']['url']}")
print(f"PowerPoint: {result['formats']['ppt']['url']}")
```
The API automatically structures your content into logical slides. For best results, use clear headings and bullet points in your source text.
***
## Example 4: Add Slides to Existing Presentation
Build presentations incrementally by adding slides one at a time.
```python theme={null}
from alai_client import AlaiClient
client = AlaiClient("your_api_key")
# First, create a base presentation
result = client.generate_presentation(
content="Company Overview: Founded in 2020, we build AI-powered tools.",
title="Company Overview",
slide_range="2-5"
)
presentation_id = result["presentation_id"]
print(f"Created presentation: {presentation_id}")
# Add a new slide with team information
team_result = client.add_slide(
presentation_id=presentation_id,
content="""
Our Team:
- 50+ engineers across 3 continents
- Leadership from Google, Meta, and Amazon
- 60% of team has advanced degrees
""",
instructions="Use a team-focused layout with icons"
)
print(f"Added team slide: {team_result['slide_id']}")
# Add another slide with metrics
metrics_result = client.add_slide(
presentation_id=presentation_id,
content="""
Key Metrics:
- $10M ARR
- 500+ enterprise customers
- 99.9% uptime
- 4.8/5 customer rating
""",
instructions="Make it visually impactful with large numbers"
)
print(f"Added metrics slide: {metrics_result['slide_id']}")
# Export the final presentation
export = client.export(presentation_id, formats=["link", "pdf", "ppt"])
print(f"Final presentation: {export['formats']['link']['url']}")
```
***
## Example 5: Batch Processing
Generate multiple presentations efficiently.
```python theme={null}
from alai_client import AlaiClient
from concurrent.futures import ThreadPoolExecutor
client = AlaiClient("your_api_key")
# Define multiple presentations to generate
presentations = [
{
"title": "Q1 Financial Results",
"content": "Q1 revenue: $5M, growth: 25%, new customers: 150..."
},
{
"title": "Q2 Financial Results",
"content": "Q2 revenue: $6.2M, growth: 24%, new customers: 180..."
},
{
"title": "Q3 Financial Results",
"content": "Q3 revenue: $7.5M, growth: 21%, new customers: 200..."
},
{
"title": "Q4 Financial Results",
"content": "Q4 revenue: $9M, growth: 20%, new customers: 250..."
}
]
def generate_one(spec):
"""Generate a single presentation."""
result = client.generate_presentation(
content=spec["content"],
title=spec["title"],
slide_range="6-10",
export_formats=["link", "pdf"]
)
return {
"title": spec["title"],
"url": result["formats"]["link"]["url"],
"pdf": result["formats"]["pdf"]["url"]
}
# Process sequentially (recommended to stay within rate limits)
results = []
for spec in presentations:
print(f"Generating: {spec['title']}...")
result = generate_one(spec)
results.append(result)
print(f" Done: {result['url']}")
# Print summary
print("\n=== All Presentations ===")
for r in results:
print(f"{r['title']}: {r['url']}")
```
Respect the rate limit of 5 concurrent generations. For large batches, process sequentially or add delays between requests.
***
## Example 6: Presentations with Custom Images
Upload your own images to include in presentations.
```python theme={null}
from alai_client import AlaiClient
client = AlaiClient("your_api_key")
# Upload images first
image_ids = client.upload_images([
"product_screenshot.png",
"team_photo.jpg",
"office_building.png"
])
print(f"Uploaded {len(image_ids)} images: {image_ids}")
# Generate presentation referencing uploaded images via their IDs
result = client.generate_presentation(
content="""
About Our Company
Our Product:
A revolutionary AI-powered analytics platform that helps businesses
make data-driven decisions in real-time.
Our Team:
A diverse group of engineers, designers, and business experts
united by a passion for innovation.
Our Office:
Located in the heart of San Francisco, our modern workspace
fosters creativity and collaboration.
""",
title="About Our Company",
slide_range="6-10",
image_ids=image_ids
)
print(f"Presentation: {result['formats']['link']['url']}")
```
Supported image formats: PNG, JPEG, WebP, GIF, AVIF, SVG. Max 10MB per file, 10 images per upload.
***
## Error Handling Best Practices
Robust error handling for production use.
```python theme={null}
from alai_client import AlaiClient
import requests
import time
client = AlaiClient("your_api_key")
def generate_with_retry(content: str, title: str, max_retries: int = 3) -> dict:
"""Generate a presentation with automatic retry on failure."""
for attempt in range(max_retries):
try:
result = client.generate_presentation(
content=content,
title=title,
export_formats=["link"]
)
return result
except requests.exceptions.HTTPError as e:
status_code = e.response.status_code
if status_code == 401:
raise Exception("Invalid API key. Check your credentials.")
elif status_code == 402:
raise Exception("Insufficient credits. Please top up your account.")
elif status_code == 429:
# Rate limited - wait and retry
wait_time = 2 ** attempt * 5 # Exponential backoff
print(f"Rate limited. Waiting {wait_time}s before retry...")
time.sleep(wait_time)
continue
elif status_code >= 500:
# Server error - retry
wait_time = 2 ** attempt * 2
print(f"Server error. Waiting {wait_time}s before retry...")
time.sleep(wait_time)
continue
else:
raise
except TimeoutError:
if attempt < max_retries - 1:
print(f"Timeout. Retrying... ({attempt + 1}/{max_retries})")
continue
raise
except Exception as e:
print(f"Unexpected error: {e}")
raise
raise Exception(f"Failed after {max_retries} attempts")
# Usage
try:
result = generate_with_retry(
content="Your presentation content...",
title="My Presentation"
)
print(f"Success: {result['formats']['link']['url']}")
except Exception as e:
print(f"Failed: {e}")
```
***
## Next Steps
Detailed documentation for all endpoints and parameters
Discover theme IDs and names available to your account