Grok Imagine Video

Generate videos using xAI's Grok Imagine API directly from your messaging interface.

Setup

Important: You need your own xAI API key. Get it from https://console.x.ai/

For full installation instructions, see README.md

Quick setup:

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

Capabilities

• Text-to-image: Generate images from text descriptions (up to 10 variations)
• Image editing: Modify images using natural language
• Text-to-video: Create videos from text descriptions
• Image-to-video: Animate static images into motion
• Video editing: Modify videos using natural language
• Async generation: Handles long-running video jobs with polling
• Auto-delivery: Downloads and delivers images/videos via chat

Workflow

1. Image Generation

User says: "Create an image of a cyberpunk cityscape at night"

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

Images are generated instantly (no polling needed). Download promptly as URLs are temporary.

1b. Image Editing

User says: "Edit this image — make it look like a watercolor"

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. Text-to-Video

User says: "Generate a video of a sunset over the ocean"

# 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. Wait for Video Completion

Video generation takes 1-3 minutes. Poll with progress:

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. Download and Deliver

Download the completed video to the workspace:

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

Image-to-Video

Animate an image:

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
)

Video Editing

Edit an existing video:

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

Configuration

Important: Get your own API key from https://console.x.ai/ - do NOT use pre-configured keys.

export XAI_API_KEY="sk-..."

For OpenClaw integration, add to workspace .env or manage via gateway config.

See README.md for complete setup instructions.

Error Handling

Common errors and responses:

• Unauthorized / API key not set: → Get your key from https://console.x.ai/ and set export XAI_API_KEY="your-key" - See README.md for details
• Rate limit: "Too many requests" → Wait and retry
• Content policy: "Prompt violates content policies" → Rephrase prompt
• Timeout: Job took too long → Reduce duration or complexity

Always wrap API calls in try/except and provide user-friendly messages.

Best Practices

Prompt engineering (images):

• Be descriptive: "A collage of London landmarks in a stenciled street-art style"
• Specify style: "Watercolor painting of a mountain lake at dawn"
• Use multiple variations (n=4) to explore interpretations

Prompt engineering (videos):

• Be specific: "A golden retriever running through a sunny meadow"
• Include camera movement: "Slow pan from left to right"
• Specify lighting: "Warm golden hour lighting"

Performance:

• Images generate instantly — no polling needed
• Use 480p for faster video generation, 720p for higher quality
• Keep videos under 10 seconds unless essential
• Start with text-to-video, then edit if needed

User experience:

• Images: deliver immediately after generation
• Videos: send progress updates: "Generating video... 45% complete"
• Estimate time for videos: "This takes about 2-3 minutes"
• Confirm delivery: "Here's your image/video!"

Limits

• Images per request: 1-10
• Video duration: 1-15 seconds
• Video resolution: 480p (default) or 720p
• Rate limit: 60 requests/minute
• Max concurrent jobs: 15

See references/api_reference.md for full API documentation.

Integration with Other Skills

• Combine with ffmpeg-video-editor for post-processing (trimming, concatenation, filters)
• Use fal-ai for additional video effects
• Integrate with image-generation skills for source images

Troubleshooting

Job stuck in "pending": Check API key and quota

Video generation slow: Try 720p instead of 1080p

Failed jobs: Check error_code in response; see API reference

Download errors: Verify video_url is accessible and has not expired