grok-imagine-video

Grok Imagine Video

直接通过消息界面使用 xAI 的 Grok Imagine API 生成视频。

设置

**重要：**你需要自己的 xAI API 密钥。请从 https://console.x.ai/ 获取。

完整安装说明请参阅 README.md。

快速设置：

# Set your xAI API key (YOUR key, not pre-configured)
export XAI_API_KEY="your-api-key-here"

功能

• 文本生成图像：根据文本描述生成图像（最多 10 个变体）
• 图像编辑：使用自然语言修改图像
• 文本生成视频：根据文本描述创建视频
• 图像生成视频：将静态图像制作成动态影像
• 视频编辑：使用自然语言修改视频
• 异步生成：通过轮询处理耗时较长的视频任务
• 自动交付：下载图像/视频并通过聊天发送

工作流

1. 图像生成

用户说：“生成一张夜晚赛博朋克城市景观的图像”

python3 - << 'EOF'
import os
import sys
sys.path.insert(0, 'scripts')
from grok_video_api import GrokImagineVideoClient

client = GrokImagineVideoClient(os.getenv("XAI_API_KEY"))
result = client.generate_image("A cyberpunk cityscape at night, neon lights reflecting on wet streets")
print(f"Image URL: {result}")
EOF

图像会即时生成（无需轮询）。请及时下载，因为 URL 是临时的。

1b. 图像编辑

用户说：“编辑这张图像——让它看起来像水彩画”

python3 - << 'EOF'
import os
import sys
sys.path.insert(0, 'scripts')
from grok_video_api import GrokImagineVideoClient

client = GrokImagineVideoClient(os.getenv("XAI_API_KEY"))
result = client.edit_image(
    image_url="https://example.com/photo.jpg",
    prompt="Make it look like a watercolor painting"
)
print(f"Edited image: {result}")
EOF

2. 文本生成视频

用户说：“生成一段海上日落的视频”

# Use the Python client
python3 - << 'EOF'
import os
import sys
sys.path.insert(0, 'scripts')
from grok_video_api import GrokImagineVideoClient

client = GrokImagineVideoClient(os.getenv("XAI_API_KEY"))
result = client.text_to_video("A beautiful sunset over the ocean", duration=10)
print(f"Job started: {result['job_id']}")
EOF

3. 等待视频完成

视频生成需要 1-3 分钟。请轮询并显示进度：

python3 - << 'EOF'
import os
import sys
sys.path.insert(0, 'scripts')
from grok_video_api import GrokImagineVideoClient

client = GrokImagineVideoClient(os.getenv("XAI_API_KEY"))

def progress(response):
    print(f"Polling... {'Done!' if 'video' in response else 'Pending'}")

final = client.wait_for_completion("request-id-here", progress_callback=progress)
print(f"Video ready: {final['video']['url']}")
EOF

4. 下载并交付

将生成完成的视频下载到工作区：

python3 - << 'EOF'
import os
import sys
sys.path.insert(0, 'scripts')
from grok_video_api import GrokImagineVideoClient

client = GrokImagineVideoClient(os.getenv("XAI_API_KEY"))
output = "/data/workspace/videos/sunset.mp4"
client.download_video(final, output)  # pass the full response dict
print(f"Downloaded: {output}")
EOF

图像生成视频

为图像添加动画效果：

from grok_video_api import GrokImagineVideoClient

client = GrokImagineVideoClient(api_key)
result = client.image_to_video(
    image_url="https://example.com/photo.jpg",
    prompt="Make the clouds move slowly",
    duration=10
)

视频编辑

编辑现有视频：

result = client.edit_video(
    video_url="https://example.com/source.mp4",
    edit_prompt="Add a warm sunset filter and slow down to 50% speed"
)

配置

**重要：**请从 https://console.x.ai/ 获取自己的 API 密钥，不要使用预配置的密钥。

export XAI_API_KEY="sk-..."

如需与 OpenClaw 集成，请将其添加到工作区 .env，或通过网关配置进行管理。

完整设置说明请参阅 README.md。

错误处理

常见错误及处理方法：

• 未授权 / 未设置 API 密钥：→ 从 https://console.x.ai/ 获取密钥，并设置 export XAI_API_KEY="your-key"——详情请参阅 README.md
• 速率限制：“请求过多” → 等待后重试
• 内容政策：“提示词违反内容政策” → 改写提示词
• 超时：任务耗时过长 → 缩短时长或降低复杂度

务必使用 try/except 包装 API 调用，并提供便于用户理解的提示。

最佳实践

提示词工程（图像）：

• 描述具体：“以模板街头艺术风格拼贴伦敦地标”
• 指定风格：“描绘黎明时分山间湖泊的水彩画”
• 使用多个变体（n=4）探索不同解读

提示词工程（视频）：

• 描述具体：“一只金毛寻回犬在阳光明媚的草地上奔跑”
• 加入镜头运动：“从左向右缓慢平移”
• 指定光线：“温暖的黄金时刻光线”

性能：

• 图像即时生成，无需轮询
• 使用 480p 加快视频生成，使用 720p 获得更高画质
• 除非确有需要，否则将视频时长控制在 10 秒以内
• 先使用文本生成视频，必要时再编辑

用户体验：

• 图像：生成后立即交付
• 视频：发送进度更新：“正在生成视频……已完成 45%”
• 预估视频耗时：“大约需要 2-3 分钟”
• 确认交付：“这是你的图像/视频！”

限制

• 每次请求的图像数量：1-10
• 视频时长：1-15 秒
• 视频分辨率：480p（默认）或 720p
• 速率限制：每分钟 60 次请求
• 最大并发任务数：15

完整 API 文档请参阅 references/api_reference.md。

与其他技能集成

• 搭配 ffmpeg-video-editor 进行后期处理（剪辑、拼接、滤镜）
• 使用 fal-ai 添加更多视频效果
• 与 image-generation 技能集成以生成源图像

故障排除

任务卡在“pending”状态：检查 API 密钥和配额

视频生成缓慢：尝试使用 720p，而不是 1080p

任务失败：检查响应中的 error_code；请参阅 API 参考

下载错误：确认 video_url 可访问且尚未过期