langchain-magic-hour

LangChain tools for Magic Hour: 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 Python SDK. Sync and async. Works with langchain.agents.create_agent, LangGraph, or any LangChain tool-calling model.

Install

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:

export MAGIC_HOUR_API_KEY="mh_..."

Quickstart

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

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

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

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

Live example

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

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

Development

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
• Other Magic Hour integrations: Vercel AI SDK provider (magic-hour-ai-provider on npm), ComfyUI nodes, MCP server

MIT License.