Metadata-Version: 2.5
Name: llama-index-tools-magic-hour
Version: 0.1.0
Summary: llama-index tools magic_hour integration (AI video and image generation)
Author-email: Rhythm Panchal <saimedha88@gmail.com>
Maintainer: RhythmP28
License-Expression: MIT
License-File: LICENSE
Keywords: image generation,image-to-video,kling,magic hour,sora,text-to-video,veo,video generation
Requires-Python: <4.0,>=3.10
Requires-Dist: llama-index-core<0.15,>=0.13.0
Requires-Dist: magic-hour>=0.75.0
Description-Content-Type: text/markdown

# Magic Hour Tool

[Magic Hour](https://magichour.ai) is an AI video and image generation API. One API key gives access to Sora 2, Veo 3.1, Kling 3.0, Seedance, MiniMax H3, WAN 2.2 and LTX 2.3 for video, and GPT-image, Nano Banana Pro, Seedream, Flux and Z-Image for images.

Get a free API key at the [Magic Hour developer page](https://magichour.ai/developer) (400 credits on signup + 100/day, no card required) and export it as `MAGIC_HOUR_API_KEY`.

## Installation

```bash
pip install git+https://github.com/RhythmP28/llama-index-tools-magic-hour  # until it lands on PyPI
```

## Usage

This tool has a more extensive example usage documented in a Jupyter notebook [here](https://github.com/RhythmP28/llama-index-tools-magic-hour/blob/main/examples/magic_hour.ipynb).

```python
from llama_index.tools.magic_hour import MagicHourToolSpec
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

magic_hour_tool = MagicHourToolSpec(
    api_key="your-key"
)  # or MAGIC_HOUR_API_KEY
agent = FunctionAgent(
    tools=magic_hour_tool.to_tool_list(),
    llm=OpenAI(model="gpt-4o"),
)

await agent.run("Make a 5 second 480p video of a corgi surfing at sunset")
```

Calling the spec directly:

```python
result = magic_hour_tool.text_to_video("a corgi surfing at sunset")
# {'project_id': 'cuid...', 'status': 'complete', 'credits_charged': 120,
#  'video_url': 'https://...'}
```

## Available Functions

All functions have sync and async (`a`-prefixed) variants and return a plain dict.

`text_to_video(prompt, model="wan-2.2", duration_seconds=5, resolution="480p", aspect_ratio="16:9")`: Generate a video from text. Returns `project_id`, `status`, `video_url`, `credits_charged`.

`image_to_video(image_url_or_path, prompt, model="wan-2.2", duration_seconds=5, resolution="480p")`: Animate an image (public URL or local path) into a video. Same return shape.

`generate_image(prompt, model="default", image_count=1, aspect_ratio="16:9")`: Generate images from text. Returns `project_id`, `status`, `image_urls`, `credits_charged`.

Constructor options: `api_key`, `wait_for_completion` (default `True`, polls until the job finishes), `download_outputs` (default `False`) and `download_directory`. Failed jobs are refunded automatically.

## Models

| Video model | Durations (s) | Credits / s | Notes |
| --- | --- | --- | --- |
| `wan-2.2` | 3-10, 15 | 24 | free tier, default |
| `ltx-2.3` | 1-10, 15, 20, 25, 30 | 24 | free tier |
| `minimax-h3` | 1-10, 15, 20, 25, 30 | 24 | free tier, up to 1080p |
| `seedance-1.5` | 4-12 | 30 | |
| `kling-2.6` | 5, 10 | 36 | |
| `kling-3.0` | 3-15 | 48 | |
| `veo3.1-lite` | 4, 6, 8, 16, ..., 56 | 48 | |
| `veo3.1` / `veo3.1-audio` | 4, 6, 8, 16, ..., 56 | 96 | audio variant generates sound |
| `sora-2` | 4, 8, 12, 24, 36, 48, 60 | 120 | max 720p |
| `seedance-2.0-mini` / `seedance-2.0` / `seedance-2.5` | 4-15 / 4-15 / 4-30 | | 720p |

Image models (about 5 credits per image): `default`, `gpt-image-2`, `nano-banana-pro`, `seedream-5-pro`, `flux-2-klein`, `z-image-turbo`, `qwen-edit`.

## Links

- [Magic Hour API docs](https://docs.magichour.ai)
- [Python SDK `magic_hour`](https://pypi.org/project/magic_hour/)
- Other integrations: [Vercel AI SDK provider](https://github.com/RhythmP28/magic-hour-ai-provider), [ComfyUI node](https://github.com/RhythmP28/comfyui-magic-hour), [MCP server](https://github.com/magichourhq)

This loader is designed to be used as a way to load data as a Tool in an Agent.
