Metadata-Version: 2.4
Name: llamagen-python
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
Project-URL: Source, https://github.com/LlamaGenAI/llamagen-python
Project-URL: Issues, https://github.com/LlamaGenAI/llamagen-python/issues
Author-email: "llamagen.ai" <support@llamagen.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,ai comic api,animation,comic,image-to-video,llamagen,sdk,text-to-video
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# LlamaGen Python SDK

Official Python SDK for LlamaGen's Comic API and Animation API.

Homepage: <https://llamagen.ai/comic-api>

## Install

```bash
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 llamagen import LlamaGenClient

WAIT_TIMEOUT_MS = 30 * 60 * 1000

client = LlamaGenClient(
    api_key=os.environ["LLAMAGEN_API_KEY"],
    timeout_ms=30000,
    max_retries=5,
    retry_delay_ms=500,
)

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"))

done = client.comic.wait_for_completion(created["id"], timeout_ms=WAIT_TIMEOUT_MS)
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):

```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`.

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",
    timeout_ms=30000,
    max_retries=5,
    retry_delay_ms=500,
)
```

The SDK uses Python's standard library HTTP stack and does not require runtime
dependencies.

## Comic API

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",
    "size": "1024x1024",
    "pagination": {"totalPages": 2, "panelsPerPage": 4},
    "comicRoles": [
        {
            "name": "The Little Prince",
            "image": "https://example.com/prince.png",
            "clothing": "green coat and yellow scarf",
        }
    ],
    "attachments": [{"type": "image", "url": "https://example.com/reference.png"}],
    "language": "en",
    "upscale": "2K",
})
```

Comic methods:

- `llamagen.comic.create(params)` calls `POST /v1/comics/generations`.
- `llamagen.comic.get(id, page=None, panel=None)` calls `GET /v1/comics/generations/{id}`.
- `llamagen.comic.continue_write(id, params)` extends an existing comic.
- `llamagen.comic.update_panel(id, params)` regenerates one panel.
- `llamagen.comic.usage()` calls `GET /v1/comics/usage`.
- `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.

Comic examples:

Create a comic generation:

```python
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 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(comic_id, page=0, panel=0)
print("comic.get panel:", panel.get("id", comic_id), panel.get("status"))
```

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"])

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"

continued = client.comic.continue_write(
    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"

updated = client.comic.update_panel(
    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:

```python
import os

from llamagen import LlamaGenClient

client = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])

usage = client.comic.usage()
print("comic.usage:", usage)
```

Upload a local reference image:

```python
import os
from pathlib import Path

from llamagen import LlamaGenClient

client = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])

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": {
        "duration": 5,
        "resolution": "720p",
        "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:

- `llamagen.animation.create(params)` calls `POST /v1/artworks/generations`.
- `llamagen.animation.get(id)` calls `GET /v1/artworks/generations/{id}`.
- `llamagen.animation.wait_for_completion(id, **options)` polls video status.
- `llamagen.animation.create_and_wait(params, **options)` creates and polls.

Animation examples:

Create an animation job:

```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": {
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9",
    },
})
print("animation.create:", video["id"], video.get("status"))
```

Fetch and wait for an animation:

```python
import os

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(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"])

finished = client.animation.create_and_wait({
    "prompt": "A paper boat sailing across a watercolor city at sunrise.",
    "videoOptions": {
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9",
    },
}, timeout_ms=WAIT_TIMEOUT_MS)
print("animation.create_and_wait:", finished["id"], finished.get("status"))
```

## Error Handling

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.

```python
import os

from llamagen import (
    LlamaGenAPIError,
    LlamaGenClient,
    LlamaGenConnectionError,
    LlamaGenTimeoutError,
)

client = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])

try:
    usage = client.comic.usage()
except LlamaGenAPIError as error:
    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:
    print("Request timed out:", error)
```

- `LlamaGenAPIError`: the API returned a non-2xx response, such as `401`, `403`, or `429`.
- `LlamaGenConnectionError`: the SDK could not connect to the API after retries.
- `LlamaGenTimeoutError`: the request timed out after retries.
