Magic Hour

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install magic-hour
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 magic-hour。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

Magic Hour 是一个 AI 媒体生成技能，将 Agent 连接到包括 Sora 2、Veo 3.1、Kling 3.0、WAN 2.2、LTX 2.3、GPT-image、Nano Banana Pro、Flux 和 Z-Image 在内的视频和图像模型。它通过一个 API 密钥支持文本生成视频、图像生成视频和文本生成图像工作流，从而使模型选择和内容生产更容易实现自动化。
该技能既支持具有零本地安装的托管 MCP 服务器，也支持 Python SDK 脚本工作流。Openclaw Skills 用户可以通过结构化的 JSON 响应提交异步作业、监控项目状态、获取过期的输出 URL、下载生成的资产、估算 credit 使用情况以及处理失败。

应用场景

根据自然语言提示词为营销活动、演示文稿、原型和社交媒体创建电影级 AI 视频剪辑。
通过受控的摄像机运动、主体运动和视觉效果让本地图像或公开图像 URL 动起来。
生成产品概念、插图、社交图贴、写实场景和编辑后的图像。
制作垂直 9:16 短视频、横向 16:9 视频或正方形 1:1 社交内容。
通过一个界面比较多个视频模型的成本、时长、分辨率和质量。
排队运行长时间生成的任务，并在以后检查其状态，而不会阻塞 Agent。
当偏好零安装的托管集成时，将 Openclaw Skills 与兼容 MCP 的客户端一起使用。

工作原理

通过 MAGIC_HOUR_API_KEY 环境变量配置 Magic Hour API 密钥，或者附加带有 bearer 身份验证的托管 MCP 服务器。
选择生成工作流：文本生成视频、图像生成视频或文本生成图像。
选择兼容的模型、时长、分辨率、宽高比和可选的音频设置。
提交请求。API 会创建一个异步项目并返回项目标识符。
当启用等待时，脚本大约每五秒轮询一次；当使用 --no-wait 时，立即返回 status: "queued"。
读取结构化的 JSON 结果，包括项目 ID、状态、模型、输出 URL 或多个 URL 以及收取的 credit。
可选地使用 --download-dir 在临时输出 URL 过期之前将生成的文件保存到本地。
如果作业失败，请检查结构化错误，纠正不受支持的时长或分辨率等常见问题，然后重试一次；失败的作业会自动退款。

配置指南

Option 1: Hosted MCP server
当您的 Agent 支持 MCP 服务器时，请使用 https://mcp.magichour.ai/ 处的远程 MCP 端点。配置 Authorization: Bearer $MAGIC_HOUR_API_KEY 请求头。Claude Web 和桌面端使用 OAuth 与 Magic Hour MCP 客户端 ID。
Option 2: Python script workflow
在 https://magichour.ai/developer 创建免费的 Magic Hour 开发者账户和 API 密钥。新账户无需绑定卡片即可获得 400 个注册 credit 和每天 100 个 credit。
导出 API 密钥并安装官方 Python SDK：
export MAGIC_HOUR_API_KEY=mhk_...
pip install magic_hour
需要 Python 3.9 或更高版本。从技能目录运行包含的脚本：
python3 {baseDir}/scripts/text_to_video.py "a corgi surfing at golden hour, slow-motion, cinematic"
--model wan-2.2 --duration 5 --resolution 480p --aspect-ratio 16:9 --download-dir ./out python3 {baseDir}/scripts/image_to_video.py ./photo.png "slow push-in, hair moves in the wind"
--model kling-3.0 --duration 5 --resolution 720p python3 {baseDir}/scripts/generate_image.py "isometric cozy coffee shop, soft morning light"
--model nano-banana-pro --count 2 --aspect-ratio 1:1 python3 {baseDir}/scripts/status.py --kind video --wait 对于立即队列提交，请使用 --no-wait。在不支持的环境或直接 API 请求中使用时，请查阅技能的 references/models.md 和 references/api.md 文件中的模型目录和原始 HTTP 示例。

数据架构

Response object
每个脚本都会向标准输出打印一个 JSON 对象。典型字段包括：
Field Purpose
project_id 用于轮询或获取生成项目的标识符。
status 作业状态，例如 queued、completed 或 error。
model 用于请求的 Magic Hour 模型。
url / urls 生成媒体的临时 URL 或多个 URL。
downloaded_paths 提供 --download-dir 时的本地文件路径。
credits_charged 已完成请求所消耗的 credit。
error 结构化的失败详细信息，包括适用的错误消息。
Asset and metadata organization
视频项目通过 project_id 进行跟踪，并通过 status.py --kind video 查询。
图像生成可以通过 urls 集合返回多个输出。
本地文件写入提供给 --download-dir 的目录之下。
源图像可以是本地文件（会自动上传），也可以是公开的 HTTPS URL。
模型元数据包括支持的时长、每秒 credit、分辨率限制和宽高比行为。
成本计算方式为每秒 credit 乘以视频时长；图像生成通常每张图像花费约 5 到 50 个 credit。
失败会返回非零进程状态和类似于 {"status":"error","error":{...}} 的 JSON 载荷。

高级特性

托管的 MCP 集成可以在没有本地 SDK 安装的情况下公开图像、视频和音频生成工具。
MCP 工具支持通过
videoAssets_generatePresignedUrl
进行资产上传以及专用的 wait/status 操作。
多模型生成覆盖了从 WAN 2.2、LTX 2.3 和 MiniMax H3 到 Sora 2 和 Veo 3.1 的免费和高级选项。
异步执行支持队列作业、轮询、延迟状态检查和非阻塞 --no-wait 工作流。
自动本地下载保护资产免受过期的远程 URL 影响。
图像生成视频工作流会自动上传本地源图像，并保留源图像作为视觉基础。
视频生成支持特定于模型的时长验证、分辨率控制、宽高比和可选的 Veo 音频。
结构化 JSON 输出使该技能易于连接到管道、自动化脚本和其他 Openclaw Skills。
成本感知操作有助于 Agent 偏好免费模型，并在花费超过约 500 个 credit 之前通知用户。

name: magic-hour description: Generate AI video and images with the Magic Hour API (Sora 2, Veo 3.1, Kling 3.0, WAN 2.2, GPT-image, Nano Banana Pro). Text-to-video, image-to-video, image generation; free tier available. version: 1.0.0
homepage: https://github.com/RhythmP28/clawhub-magic-hour