AjaxAI Quickstart Guide

AjaxAI removes everything that isn't directly related to your business logic—no JSONL files, no polling, no parsing. The goal is to make batch AI processing even easier than synchronous.

Get Started

Getting Started

Everything you need to begin using AjaxAI for batch AI processing.

Before You Begin

  1. Sign up for an AjaxAI account
  2. Complete billing setup and Google Cloud integration
  3. Get your API key from the Settings page

Installation

Install the SDK

Install the AjaxAI Python SDK using pip:

pip install ajaxai-sdk

API Key Configuration

Set up your API key to authenticate with the AjaxAI service.

Environment Variable (Recommended)

Set your API key as an environment variable for secure access:

# Set as environment variable
export AJAXAI_API_KEY="your_api_key_here"

# Or pass directly in code (not recommended for production)
import os
os.environ["AJAXAI_API_KEY"] = "your_api_key_here"

Core Workflow

The AjaxAI workflow is straightforward: create a job, add requests, submit, and get results. No file management or complex state tracking needed.

Basic Usage

Here's how to create and submit your first batch job:

from ajaxai import create_batch_job, AjaxAiRequestItem

# Create a job (job_type is required for result routing)
job = create_batch_job(job_type="content_generation")

# Add requests
request = AjaxAiRequestItem(request_id="req_1").add_text("Write a short poem about AI")
job.add_request(request)

# Submit and process
job.submit()

Two Approaches to Handle Results

Choose between manual checking for immediate control or automated callbacks for seamless background processing.

Manual Checking

For scripts, testing, or when you want immediate control over when to check results:

from ajaxai import create_batch_job, AjaxAiRequestItem

job = create_batch_job(job_type="simple_test")
request = AjaxAiRequestItem(request_id="test_1").add_text("Explain quantum computing in one sentence")
job.add_request(request)
job.submit()

# Check when ready
print(f"Job status: {job.get_state()}")

# Get results when completed
if job.get_state() == "succeeded":
    for result in job.get_results():
        print(f"Response: {result.response['text']}")

Background Callbacks (Recommended)

Polling for job completion gets messy fast when processing multiple batches. Callbacks handle results automatically as they complete:

from ajaxai import create_batch_job, AjaxAiRequestItem, AjaxAiClient
from ajaxai.registry import ajaxai_callback

# Register a callback for this job type
@ajaxai_callback('content_generation')
def handle_content_results(job):
    print(f"Job {job.job_id} completed!")
    for result in job.get_results():
        print(f"Generated content: {result.response['text']}")

# Start background processing
client = AjaxAiClient()
client.start_polling()

# Submit jobs - callbacks will trigger automatically when complete
job = create_batch_job(job_type="content_generation")
request = AjaxAiRequestItem(request_id="content_1").add_text("Write a product description for wireless headphones")
job.add_request(request)
job.submit()

Structured Outputs with Pydantic

One of the most tedious parts of AI processing is parsing free-form text responses. Structured outputs let you define exactly what you want back:

Define Your Schema

Use Pydantic models to get structured, type-safe responses:

from pydantic import BaseModel
from typing import List

class ProductAnalysis(BaseModel):
    product_name: str
    rating: float
    pros: List[str]
    cons: List[str]
    recommendation: str

# Request structured output
request = AjaxAiRequestItem(
    request_id="product_review",
    output_model=ProductAnalysis
).add_text("Analyze this product review: 'Great headphones, amazing sound quality but battery life could be better. Worth the price!'")

job.add_request(request)
job.submit()

# Get typed results
for result in job.get_results():
    try:
        analysis = ProductAnalysis.model_validate_json(result.response['text'])
        print(f"Product: {analysis.product_name}")
        print(f"Rating: {analysis.rating}")
        print(f"Pros: {', '.join(analysis.pros)}")
    except ValidationError:
        # Handle the rare case where AI output doesn't match your model
        print(f"Fallback to raw text: {result.response['text']}")

Complete Working Examples

Real-world examples showing different use cases and patterns.

Simple Text Processing

from ajaxai import create_batch_job, AjaxAiRequestItem

def simple_text_example():
    # Create job
    job = create_batch_job(job_type="content_creation")
    
    # Add multiple requests
    prompts = [
        "Write a tagline for a productivity app",
        "Create a brief product description for smart glasses",
        "Generate 3 social media hashtags for sustainable fashion"
    ]
    
    for i, prompt in enumerate(prompts):
        request = AjaxAiRequestItem(request_id=f"content_{i}").add_text(prompt)
        job.add_request(request)
    
    # Submit and get results
    job.submit()
    
    # Wait for completion and process results
    if job.get_state() == "succeeded":
        for result in job.get_results():
            print(f"Request {result.summary.request_id}: {result.response['text']}")

simple_text_example()

Multimodal Processing (Text + Images)

from ajaxai import create_batch_job, AjaxAiRequestItem

def multimodal_example():
    job = create_batch_job(
        job_type="product_catalog",
        system_instruction="You are an expert e-commerce copywriter."
    )
    
    products = [
        {
            "id": "prod_1",
            "image": "https://example-store.com/images/wireless-earbuds.jpg",
            "context": "Premium wireless earbuds with noise cancellation"
        },
        {
            "id": "prod_2", 
            "image": "https://example-store.com/images/smart-watch.png",
            "context": "Fitness-focused smartwatch with health monitoring"
        }
    ]
    
    for product in products:
        request = AjaxAiRequestItem(request_id=product["id"])\
            .add_text(f"Create a product description for: {product['context']}")\
            .add_image(product["image"])\
            .add_text("Based on the image, generate compelling marketing copy.")
        
        job.add_request(request)
    
    job.submit()

multimodal_example()

Key Do's and Don'ts

✅ Do This

  • Always specify job_type - Required for callback routing and result organization
  • Use structured outputs - Get reliable, typed responses instead of parsing free text
  • Handle parsing errors gracefully - LLMs are highly reliable but not perfect
  • Use robust image URLs - Cloud storage, CDNs, and established platforms work best

❌Avoid This

  • ×Protected or throttled image URLs - Use publicly accessible, robust hosting
  • ×Assuming perfect structured output - Always include try/catch around parsing
  • ×Ignoring job states - Check completion status before processing results
  • ×Hardcoding API keys - Use environment variables for security

Ready to get started?

Sign up for an account and start processing AI requests at scale.

Create Your Account