Metadata-Version: 2.5
Name: langchain-magic-hour
Version: 0.1.0
Summary: LangChain tools for Magic Hour: AI text-to-video, image-to-video and image generation (Sora 2, Veo 3.1, Kling 3.0, WAN 2.2, GPT-image, Nano Banana Pro, ...)
Project-URL: Homepage, https://github.com/RhythmP28/langchain-magic-hour
Project-URL: Repository, https://github.com/RhythmP28/langchain-magic-hour
Project-URL: Documentation, https://docs.magichour.ai
Project-URL: Magic Hour, https://magichour.ai
Author: Rhythm Panchal
License-Expression: MIT
License-File: LICENSE
Keywords: ai video,image generation,image-to-video,kling,langchain,magic hour,magichour,sora,text-to-video,veo
Classifier: Development Status :: 4 - Beta
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 :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: langchain-core>=0.3
Requires-Dist: magic-hour>=0.70
Requires-Dist: pydantic>=2
Description-Content-Type: text/markdown

# langchain-magic-hour

LangChain tools for [Magic Hour](https://magichour.ai): AI **text-to-video**, **image-to-video** and **image generation** behind one API key. Models include Sora 2, Veo 3.1, Kling 3.0, Seedance, MiniMax H3, WAN 2.2, LTX 2.3 (video) and GPT-image, Nano Banana Pro, Seedream, Flux, Z-Image (image).

Built on the official [`magic_hour`](https://pypi.org/project/magic_hour/) Python SDK. Sync and async. Works with `langchain.agents.create_agent`, LangGraph, or any LangChain tool-calling model.

## Install

```bash
pip install langchain-magic-hour
# or
uv add langchain-magic-hour
```

Get a free API key at https://magichour.ai/developer (400 credits on signup + 100/day, no card) and export it:

```bash
export MAGIC_HOUR_API_KEY="mh_..."
```

## Quickstart

```python
from langchain_magic_hour import MagicHourTextToVideoTool, MagicHourToolkit

tool = MagicHourTextToVideoTool(download_dir="outputs")  # download_dir is optional
print(
    tool.invoke(
        {"prompt": "a corgi surfing at golden hour", "model": "wan-2.2", "duration_seconds": 5}
    )
)
# {"project_id": "...", "status": "complete", "model": "wan-2.2", "video_url": "https://...", "credits_charged": 120, ...}

# In an agent (pip install "langchain[anthropic]")
from langchain.agents import create_agent

agent = create_agent(model="claude-sonnet-4-6", tools=MagicHourToolkit().get_tools())
result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Make a 5s clip of rain on a window, then a 16:9 poster image of the same scene.",
            }
        ]
    }
)
print(result["messages"][-1].content)
```

## Tools

| Tool | `name` | Inputs | Returns (JSON string) |
|---|---|---|---|
| `MagicHourTextToVideoTool` | `magic_hour_text_to_video` | `prompt`, `model="wan-2.2"`, `duration_seconds=5`, `resolution="480p"`, `aspect_ratio="16:9"`, `audio`, `name` | `project_id`, `status`, `video_url`, `video_urls`, `credits_charged`, `width`, `height`, `fps` |
| `MagicHourImageToVideoTool` | `magic_hour_image_to_video` | `image_url_or_path` (https URL or local file, uploaded automatically), `prompt`, `model`, `duration_seconds`, `resolution`, `audio`, `name` | same as above |
| `MagicHourImageGenerationTool` | `magic_hour_generate_image` | `prompt`, `model="default"`, `image_count=1`, `aspect_ratio="1:1"`, `name` | `project_id`, `status`, `image_urls`, `credits_charged` |
| `MagicHourToolkit` | – | same constructor options | `get_tools()` returns all three |

Constructor options (all tools and the toolkit): `api_key` (defaults to `MAGIC_HOUR_API_KEY`), `download_dir` (download outputs locally and add `downloaded_paths` to the result; off by default), `wait_for_completion=True` (poll until done), `timeout`.

Errors (bad model/duration, insufficient credits, API errors) are returned as `{"status": "error", "error": {...}}` so an agent can recover instead of crashing. Failed jobs are auto-refunded by Magic Hour.

## Video models

| Model | Durations (s) | Credits / sec | 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**, max 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 | native audio |
| `sora-2` | 4, 8, 12, 24, 36, 48, 60 | 120 | max 720p |
| `seedance-2.0-mini` / `seedance-2.0` | 4-15 | 96 / 120 | max 720p |
| `seedance-2.5` | 4-30 | 120 | max 720p |

Resolutions: `480p`, `720p`, `1080p`. Aspect ratios: `16:9`, `9:16`, `1:1`. A 5s 480p `wan-2.2` clip costs 120 credits.

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

The model table is informational; unknown model ids are passed straight to the API so new models work without upgrading.

## Async

```python
result = await tool.ainvoke({"prompt": "..."})
```

## Live example

`examples/agent_demo.py` runs the toolkit against the real API (needs `MAGIC_HOUR_API_KEY`):

```bash
uv run --with "langchain[anthropic]" examples/agent_demo.py
```

## Development

```bash
uv sync --all-groups
uv run pytest        # offline, SDK is mocked
uv build
```

## Links

- Magic Hour API docs: https://docs.magichour.ai
- LangChain integration guide: [docs/langchain-integration.md](docs/langchain-integration.md)
- Other Magic Hour integrations: [Vercel AI SDK provider](https://github.com/RhythmP28/magic-hour-ai-provider) (`magic-hour-ai-provider` on npm), [ComfyUI nodes](https://github.com/RhythmP28/comfyui-magic-hour), [MCP server](https://github.com/magichourhq)

MIT License.
