llamagen-python 0.1.6__tar.gz → 0.1.8__tar.gz

{llamagen_python-0.1.6 → llamagen_python-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: llamagen-python
-Version: 0.1.6
+Version: 0.1.8
 Summary: Official Python SDK for LlamaGen Comic API and Animation API
 Project-URL: Homepage, https://llamagen.ai/comic-api
 Project-URL: Documentation, https://llamagen.ai/comic-api/docs
@@ -23,7 +23,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 
-# llamagen-python
+# LlamaGen Python SDK
 
 Official Python SDK for LlamaGen's Comic API and Animation API.
 
@@ -35,11 +35,29 @@ Homepage: <https://llamagen.ai/comic-api>
 pip install llamagen-python
 ```
 
+## Get Your API Key
+
+1. Open the [LlamaGen Comic API Dashboard](https://llamagen.ai/comic-api).
+2. Sign in and create an API key.
+3. Use the key with the SDK or an HTTP `Authorization` header:
+
+```http
+Authorization: Bearer YOUR_API_KEY
+```
+
+For local SDK examples, set the key in your shell or in a local `.env` file:
+
+```bash
+LLAMAGEN_API_KEY=YOUR_API_KEY
+```
+
 ## Quick Start
 
+This example creates one comic generation and waits for the final result. API
+generation calls consume credits.
+
 ```python
 import os
-from pathlib import Path
 
 from llamagen import LlamaGenClient
 
@@ -63,14 +81,32 @@ done = client.comic.wait_for_completion(created["id"], timeout_ms=WAIT_TIMEOUT_M
 print("comic.wait_for_completion:", done["id"], done.get("status"), done.get("comics"))
 ```
 
-The full runnable demo is in [`examples/quickstart.py`](examples/quickstart.py).
-It loads `LLAMAGEN_API_KEY` from the environment or a local `.env` file.
-Set `LLAMAGEN_UPLOAD_FILE=/path/to/reference.png` to run the upload demo, and
-set `LLAMAGEN_RUN_OPTIONAL_DEMOS=1` to run extra paid generation examples.
+The full runnable demo is in [`examples/quickstart.py`](examples/quickstart.py):
+
+```bash
+python examples/quickstart.py
+```
+
+Pass a local image path to run the upload example:
+
+```bash
+python examples/quickstart.py upload /path/to/reference.png
+```
+
+Other README examples are available as subcommands, such as `comic-create`,
+`comic-create-advanced`, `comic-get`, `comic-wait`, `comic-create-and-wait`,
+`comic-continue`, `comic-update-panel`, `usage`, `animation-create`,
+`animation-create-wait`, `animation-wait`, and `animation-create-and-wait`.
 
-## Client
+All Python examples below are self-contained for copy/paste usage. Replace
+`YOUR_COMIC_ID` or `YOUR_ANIMATION_ID` with an existing generation ID when an
+example fetches, waits for, continues, or updates an existing job.
+
+## Configure The Client
 
 ```python
+from llamagen import LlamaGenClient
+
 client = LlamaGenClient(
     api_key="YOUR_API_KEY",
     base_url="https://api.llamagen.ai/v1",
@@ -88,7 +124,15 @@ dependencies.
 Use `llamagen.comic` to create comics, manga, webtoons, storyboards,
 consistent-character pages, and panel edits.
 
+Create with advanced options:
+
 ```python
+import os
+
+from llamagen import LlamaGenClient
+
+client = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])
+
 generation = client.comic.create({
     "prompt": "The Little Prince meets the Fox in a luminous desert.",
     "style": "storybook manga",
@@ -117,116 +161,157 @@ Comic methods:
 - `llamagen.comic.upload(file, filename=None)` calls `POST /v1/comics/upload`.
 - `llamagen.comic.wait_for_completion(id, **options)` polls until a terminal status.
 - `llamagen.comic.create_and_wait(params, **options)` creates and polls.
-- `llamagen.comic.create_batch(params_list, concurrency=3)` submits many jobs.
-- `llamagen.comic.wait_for_many(ids, concurrency=3)` polls many jobs.
 
 Comic examples:
 
+Create a comic generation:
+
 ```python
-# Create a comic generation.
+import os
+
+from llamagen import LlamaGenClient
+
+client = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])
+
 created = client.comic.create({
     "prompt": "A 4-panel comic about Leo finding a glowing key in a quiet library.",
     "style": "manga",
     "fixPanelNum": 4,
 })
 print("comic.create:", created["id"], created.get("status"))
+```
 
-# Fetch the whole generation, or one page/panel.
-fetched = client.comic.get(created["id"])
+Fetch a comic generation, page, or panel:
+
+```python
+import os
+
+from llamagen import LlamaGenClient
+
+client = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])
+comic_id = "YOUR_COMIC_ID"
+
+fetched = client.comic.get(comic_id)
 print("comic.get:", fetched["id"], fetched.get("status"))
 
-panel = client.comic.get(created["id"], page=0, panel=0)
-print("comic.get panel:", panel.get("id", created["id"]), panel.get("status"))
+panel = client.comic.get(comic_id, page=0, panel=0)
+print("comic.get panel:", panel.get("id", comic_id), panel.get("status"))
+```
 
-# Wait until the generation reaches a terminal status.
-# The default timeout is 30 minutes.
-done = client.comic.wait_for_completion(created["id"], timeout_ms=WAIT_TIMEOUT_MS)
+Wait for completion. The default timeout is 30 minutes:
+
+```python
+import os
+
+from llamagen import LlamaGenClient
+
+WAIT_TIMEOUT_MS = 30 * 60 * 1000
+
+client = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])
+comic_id = "YOUR_COMIC_ID"
+
+done = client.comic.wait_for_completion(comic_id, timeout_ms=WAIT_TIMEOUT_MS)
 print("comic.wait_for_completion:", done["id"], done.get("status"), done.get("comics"))
+```
+
+Create and wait in one call:
+
+```python
+import os
+
+from llamagen import LlamaGenClient
+
+WAIT_TIMEOUT_MS = 30 * 60 * 1000
+
+client = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])
 
-# Create and wait in one call.
 finished = client.comic.create_and_wait({
     "prompt": "A cozy 3-panel comic about a robot learning to bake bread.",
     "style": "storybook",
     "fixPanelNum": 3,
 }, timeout_ms=WAIT_TIMEOUT_MS)
 print("comic.create_and_wait:", finished["id"], finished.get("status"))
+```
+
+Continue an existing comic:
+
+```python
+import os
+
+from llamagen import LlamaGenClient
+
+client = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])
+comic_id = "YOUR_COMIC_ID"
 
-# Continue an existing comic.
 continued = client.comic.continue_write(
-    created["id"],
+    comic_id,
     {
         "prompt": "Continue the story with Leo opening a secret reading room.",
         "pagination": {"totalPages": 1, "panelsPerPage": 4},
     },
 )
 print("comic.continue_write:", continued["id"], continued.get("status"))
+```
+
+Regenerate one panel:
+
+```python
+import os
+
+from llamagen import LlamaGenClient
+
+client = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])
+comic_id = "YOUR_COMIC_ID"
 
-# Regenerate one panel.
 updated = client.comic.update_panel(
-    created["id"],
+    comic_id,
     {
         "panelIndex": 0,
         "prompt": "Make the glowing key brighter and add dramatic moonlight.",
     },
 )
 print("comic.update_panel:", updated["id"], updated.get("status"))
+```
 
-# Check usage.
-usage = client.comic.usage()
-print("comic.usage:", usage)
+Check usage:
 
-# Upload a local reference image.
-upload_file = os.environ.get("LLAMAGEN_UPLOAD_FILE")
-if upload_file:
-    uploaded = client.comic.upload(Path(upload_file))
-    print("comic.upload:", uploaded)
+```python
+import os
 
-# Submit many jobs and wait for many jobs.
-batch = client.comic.create_batch(
-    [
-        {
-            "prompt": "A 2-panel comic about a cloud trying on hats.",
-            "style": "cartoon",
-            "fixPanelNum": 2,
-        },
-        {
-            "prompt": "A 2-panel comic about a tiny train crossing a desk.",
-            "style": "manga",
-            "fixPanelNum": 2,
-        },
-    ],
-    concurrency=2,
-)
-ids = [item["result"]["id"] for item in batch if "result" in item]
-print("comic.create_batch:", ids)
+from llamagen import LlamaGenClient
 
-finished_many = client.comic.wait_for_many(ids, concurrency=2, timeout_ms=WAIT_TIMEOUT_MS)
-print("comic.wait_for_many:", [(item["id"], item.get("status")) for item in finished_many])
-```
+client = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])
 
-JavaScript-style aliases are also available: `createComic`, `getComic`,
-`continueComic`, `regeneratePanel`, `updateComicPanel`, `waitForCompletion`,
-`createAndWait`, and `waitForMany`.
+usage = client.comic.usage()
+print("comic.usage:", usage)
+```
 
-Alias examples:
+Upload a local reference image:
 
 ```python
-created = client.comic.createComic({
-    "prompt": "A 4-panel comic about a lighthouse keeper finding a map.",
-    "fixPanelNum": 4,
-})
-print("comic.createComic:", created["id"], created.get("status"))
+import os
+from pathlib import Path
+
+from llamagen import LlamaGenClient
 
-fetched = client.comic.getComic(created["id"])
-print("comic.getComic:", fetched["id"], fetched.get("status"))
+client = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])
 
-done = client.comic.waitForCompletion(created["id"], timeout_ms=WAIT_TIMEOUT_MS)
-print("comic.waitForCompletion:", done["id"], done.get("status"))
+image_path = Path("reference.png")
+uploaded = client.comic.upload(image_path)
+print("comic.upload:", uploaded)
 ```
 
 ## Animation API
 
+Create an animation job and wait for completion:
+
 ```python
+import os
+
+from llamagen import LlamaGenClient
+
+client = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])
+
 video = client.animation.create({
     "prompt": "A heroic fox detective walks through neon rain, cinematic camera move.",
     "videoOptions": {
@@ -235,12 +320,14 @@ video = client.animation.create({
         "aspect_ratio": "16:9",
     },
 })
+print("animation.create:", video["id"], video.get("status"))
 
 finished = client.animation.wait_for_completion(
     video["id"],
     interval_ms=5000,
     timeout_ms=30 * 60 * 1000,
 )
+print("animation.wait_for_completion:", finished["id"], finished.get("status"))
 ```
 
 Animation methods:
@@ -250,12 +337,17 @@ Animation methods:
 - `llamagen.animation.wait_for_completion(id, **options)` polls video status.
 - `llamagen.animation.create_and_wait(params, **options)` creates and polls.
 
-`llamagen.animations` is an alias for `llamagen.animation`.
-
 Animation examples:
 
+Create an animation job:
+
 ```python
-# Create an animation job.
+import os
+
+from llamagen import LlamaGenClient
+
+client = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])
+
 video = client.animation.create({
     "prompt": "A heroic fox detective walks through neon rain, cinematic camera move.",
     "videoOptions": {
@@ -265,15 +357,38 @@ video = client.animation.create({
     },
 })
 print("animation.create:", video["id"], video.get("status"))
+```
+
+Fetch and wait for an animation:
+
+```python
+import os
 
-# Fetch and wait.
-fetched = client.animation.get(video["id"])
+from llamagen import LlamaGenClient
+
+WAIT_TIMEOUT_MS = 30 * 60 * 1000
+
+client = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])
+animation_id = "YOUR_ANIMATION_ID"
+
+fetched = client.animation.get(animation_id)
 print("animation.get:", fetched["id"], fetched.get("status"))
 
-finished = client.animation.wait_for_completion(video["id"], timeout_ms=WAIT_TIMEOUT_MS)
+finished = client.animation.wait_for_completion(animation_id, timeout_ms=WAIT_TIMEOUT_MS)
 print("animation.wait_for_completion:", finished["id"], finished.get("status"))
+```
+
+Create and wait for an animation in one call:
+
+```python
+import os
+
+from llamagen import LlamaGenClient
+
+WAIT_TIMEOUT_MS = 30 * 60 * 1000
+
+client = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])
 
-# Create and wait in one call.
 finished = client.animation.create_and_wait({
     "prompt": "A paper boat sailing across a watercolor city at sunrise.",
     "videoOptions": {
@@ -283,61 +398,32 @@ finished = client.animation.create_and_wait({
     },
 }, timeout_ms=WAIT_TIMEOUT_MS)
 print("animation.create_and_wait:", finished["id"], finished.get("status"))
-
-# Alias form.
-same_result = client.animations.waitForCompletion(video["id"], timeout_ms=WAIT_TIMEOUT_MS)
-print("animations.waitForCompletion:", same_result["id"], same_result.get("status"))
 ```
 
-## Webhooks
+## Error Handling
 
-```python
-import hashlib
-import hmac
-import json
-import time
-
-from llamagen import construct_webhook_event, verify_webhook_signature
-
-payload = json.dumps({"type": "comic.completed", "data": {"id": "cm_demo"}}, separators=(",", ":"))
-secret = "whsec_demo"
-timestamp = str(int(time.time()))
-signature = hmac.new(
-    secret.encode("utf-8"),
-    f"{timestamp}.{payload}".encode("utf-8"),
-    hashlib.sha256,
-).hexdigest()
-headers = {
-    "X-Llama-Webhook-Timestamp": timestamp,
-    "X-Llama-Webhook-Signature": f"v1={signature}",
-}
-
-is_valid = verify_webhook_signature(
-    payload=payload,
-    headers=headers,
-    secret=secret,
-)
-event = construct_webhook_event(
-    payload=payload,
-    headers=headers,
-    secret=secret,
-)
-print("verify_webhook_signature:", is_valid)
-print("construct_webhook_event:", event["type"], event["data"]["id"])
-```
+API errors include the HTTP status, parsed server response, and a readable
+message. For example, a `429` response can include an error code and message
+such as insufficient credits.
 
-The helper verifies `X-Llama-Webhook-Timestamp` and
-`X-Llama-Webhook-Signature` with HMAC SHA-256 and a default 5-minute tolerance.
+```python
+import os
 
-## Errors
+from llamagen import (
+    LlamaGenAPIError,
+    LlamaGenClient,
+    LlamaGenConnectionError,
+    LlamaGenTimeoutError,
+)
 
-```python
-from llamagen import LlamaGenAPIError, LlamaGenConnectionError, LlamaGenTimeoutError
+client = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])
 
 try:
     usage = client.comic.usage()
 except LlamaGenAPIError as error:
-    print(error.status, error.data)
+    print("API request failed:", error)
+    print("HTTP status:", error.status)
+    print("Server response:", error.data)
 except LlamaGenConnectionError as error:
     print("Network connection failed:", error)
 except LlamaGenTimeoutError as error: