Metadata-Version: 2.4
Name: llamagen-python
Version: 0.1.0
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

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

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

## Install

```bash
pip install llamagen-python
```

## Quick Start

```python
import os
from llamagen import LlamaGenClient

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

created = llamagen.comic.create({
    "prompt": "A 4-panel comic about Leo finding a glowing key in a quiet library.",
    "style": "manga",
    "fixPanelNum": 4,
})

done = llamagen.comic.wait_for_completion(created["id"])
print(done["status"], done.get("comics"))
```

## Client

```python
llamagen = LlamaGenClient(
    api_key="YOUR_API_KEY",
    base_url="https://api.llamagen.ai/v1",
    timeout_ms=30000,
    max_retries=2,
    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.

```python
generation = llamagen.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.
- `llamagen.comic.create_batch(params_list, concurrency=3)` submits many jobs.
- `llamagen.comic.wait_for_many(ids, concurrency=3)` polls many jobs.

JavaScript-style aliases are also available: `createComic`, `getComic`,
`continueComic`, `regeneratePanel`, `updateComicPanel`, `waitForCompletion`,
`createAndWait`, and `waitForMany`.

## Animation API

```python
video = llamagen.animation.create({
    "prompt": "A heroic fox detective walks through neon rain, cinematic camera move.",
    "videoOptions": {
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9",
        "image": "https://example.com/first-frame.png",
        "last_frame_image": "https://example.com/last-frame.png",
        "reference_images": ["https://example.com/character.png"],
    },
})

finished = llamagen.animation.wait_for_completion(
    video["id"],
    interval_ms=5000,
    timeout_ms=300000,
)
```

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.

`llamagen.animations` is an alias for `llamagen.animation`.

## Webhooks

```python
from llamagen import construct_webhook_event

event = construct_webhook_event(
    payload=raw_body,
    headers=request_headers,
    secret=os.environ["LLAMAGEN_WEBHOOK_SECRET"],
)
```

The helper verifies `X-Llama-Webhook-Timestamp` and
`X-Llama-Webhook-Signature` with HMAC SHA-256 and a default 5-minute tolerance.

## Publishing

Detailed release notes are in [`docs/RELEASE.md`](docs/RELEASE.md).

1. Update `version` in `pyproject.toml`.
2. Run tests and packaging checks:

```bash
python -m unittest discover -s tests
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
```

3. Publish to TestPyPI first:

```bash
python -m twine upload --repository testpypi dist/*
```

4. Install from TestPyPI in a clean environment and smoke-test:

```bash
python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ llamagen-python
```

5. Publish to PyPI:

```bash
python -m twine upload dist/*
```

Use a PyPI API token through `TWINE_USERNAME=__token__` and
`TWINE_PASSWORD=pypi-...` or configure a trusted publisher in PyPI for GitHub
Actions.

## Local Dev

```bash
python -m unittest discover -s tests
python -m compileall src tests
```
