Metadata-Version: 2.4
Name: imageapiai
Version: 1.1.0
Summary: Official Python SDK for ImageAPI AI - Generate and refine AI images with simple API calls.
Author-email: ImageAPI AI <support@imageapiai.com>
License: MIT
Project-URL: Homepage, https://imageapiai.com
Project-URL: Documentation, https://imageapiai.com/docs
Project-URL: Showcase, https://imageapiai.com/showcase
Project-URL: Dashboard, https://imageapiai.com/dashboard
Project-URL: PyPI, https://pypi.org/project/imageapiai/
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

ImageAPI AI Python SDK
======================

Official Python SDK for [ImageAPI AI](https://imageapiai.com/). 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
----------------------
| Method                                              | Parameters                                                                                          | Description                                                                      |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| ImageAPI(api_key=None, base_url=...)                | api_key (str, optional), base_url (str, optional)                                                   | Initializes the client. Defaults to reading IMAGEAPIAI_API_KEY from environment. |
| client.generate(prompt=None, ...)                   | prompt (str), width (int), height (int), quality (str), parent_prompt_id (str), prompt_update (str) | Generates a new AI image or refines an existing one.                             |
| client.refine(parent_prompt_id, prompt_update, ...) | parent_prompt_id (str), prompt_update (str), width (int), height (int), quality (str)               | Refines an image for 0 credits (up to 5 free retries).                           |
| client.get_profile()                                | None                                                                                                | Fetches user profile, credit balance, and subscription status.                   |
| client.get_history()                                | None                                                                                                | Returns account generation history.                                              |

🔗 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](https://imageapiai.com)
