ImageAPI AI Python SDK

Official Python SDK for ImageAPI AI. Generate high-resolution AI images with low latency, refine prompts for 0 credits with up to 5 free retries, and seamlessly integrate image generation into your Python scripts, FastAPI backends, or AI agents.

Built with zero external dependencies using standard Python standard libraries (urllib.request, json).

⚡ Quick Start

1. Installation

pip install imageapiai

2. Set Your API Key

Get your secret API key (sk_live_...) from the [ImageAPI.ai Dashboard](https://imageapiai.com/dashboard).

Set it in your environment:

export IMAGEAPIAI_API_KEY="sk_live_your_secret_api_key_here"

3. Generate an Image in 3 Lines

from imageapiai import ImageAPI

client = ImageAPI()  # Automatically loads os.environ["IMAGEAPIAI_API_KEY"]

# Shorthand string generation call\
res = client.generate("A futuristic cyberpunk street with neon reflections, 8k render")

# Attribute or dictionary access both work!\
print("Image URL:", res.data.image_url)\
print("Credits Remaining:", res.data.credits_remaining)

🚀 Usage & Examples

1. Generate a Fresh Image

You can pass a simple string prompt, or configure explicit dimensions and inference quality:

from imageapiai import ImageAPI

client = ImageAPI()

# Detailed configuration call\
result = client.generate(\
    prompt="A photorealistic arctic fox standing on icy terrain during sunset",\
    width=1024,\
    height=768,\
    quality="high"  # 'low' | 'medium' (default) | 'high'\
)

print("Prompt ID:", result.data.prompt_id)\
print("Image URL:", result.data.image_url)\
print("Credits Deducted:", result.data.credits_deducted)

2. Refine / Retry an Existing Image (5 Free Retries)

Each generation includes up to 5 free refinement retries that modify the output for 0 credits:

Refine an existing generation using parent prompt ID\

refined = client.refine(\
    parent_prompt_id="gen_1234567890",\
    prompt_update="Make it daytime, add bright golden sunlight reflections",\
    quality="high"\
)

print("Updated Image URL:", refined.data.image_url)\
print("Retries Left:", refined.data.retries_remaining)\
print("Credits Deducted:", refined.data.credits_deducted)  # 0

3. Check Account Credit Balance & Profile

Check remaining credit balance and subscription status\

profile = client.get_profile()\
print("Email:", profile.data.email)\
print("Remaining Credits:", profile.data.credit_balance)\
print("Subscription Status:", profile.data.subscription_status)

# Retrieve historical generations\
history = client.get_history()\
print("Total Historical Generations:", len(history.data))

🌐 Web Framework Integrations

FastAPI Backend Endpoint

from fastapi import FastAPI, HTTPException\
from pydantic import BaseModel\
from imageapiai import ImageAPI, ImageAPIError

app = FastAPI()\
client = ImageAPI()  # Reads IMAGEAPIAI_API_KEY from environment

class GenerateRequest(BaseModel):\
    prompt: str\
    quality: str = "medium"

@app.post("/api/generate")\
def generate_image(req: GenerateRequest):\
    try:\
        res = client.generate(\
            prompt=req.prompt,\
            quality=req.quality\
        )\
        return {\
            "success": True,\
            "image_url": res.data.image_url,\
            "prompt_id": res.data.prompt_id\
        }\
    except ImageAPIError as e:\
        raise HTTPException(status_code=500, detail=str(e))

🛠️ Key SDK Features

1. Zero-Config Environment Loading

If api_key is omitted, the client automatically checks:

1.  os.environ["IMAGEAPIAI_API_KEY"]

2.  os.environ["IMAGEAPI_API_KEY"]

Zero-config (recommended for clean scripts and AI agents)\

client = ImageAPI()

Or explicit initialization\

client = ImageAPI(api_key="sk_live_...")

2. Flexible Response Access (Attribute + Dictionary + Casing)

Response objects support both dot attribute access and dictionary indexing, as well as automatic snake_case and camelCase property aliases:

res = client.generate("Cyberpunk city")

All of these work seamlessly:\

url = res.data.image_url\
url = res["data"]["image_url"]\
url = res.data.imageUrl

📚 API & SDK Reference

🔗 Links & Resources

• Homepage: https://imageapiai.com

• Dashboard & API Keys: https://imageapiai.com/dashboard

• Showcase Gallery: https://imageapiai.com/showcase

• API Documentation: https://imageapiai.com/docs

• PyPI Package: https://pypi.org/project/imageapiai

📄 License

MIT © ImageAPI AI