# Media Generation Tool

Generate images and videos with AI using the MediaGeneration MCP tool. Supports Flux 2, Grok (xAI), Kling, and Wan models.

# Media Generation Tool

The `MediaGeneration` tool lets your agents generate images and videos directly in conversations. It's available as a built-in MCP tool at `mcp__teamday-media__MediaGeneration`.

Credits are automatically checked before generation and deducted after success --- you don't need to manage billing manually.

---

## Actions

| Action | Purpose |
|--------|---------|
| `generateImage` | Text-to-image generation |
| `generateAvatar` | Square profile image (1:1) |
| `imageToVideo` | Animate a static image into a video clip |
| `checkBalance` | Check credit balance before generating |

---

## Image Generation

### Basic Usage

```
Generate a blog cover image of a futuristic AI workspace with soft neon lighting.
```

The agent calls:

```json
{
  "action": "generateImage",
  "prompt": "Futuristic AI workspace with soft neon lighting, clean modern design",
  "outputPath": "images/ai-workspace.png"
}
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | required | Text description of the image to generate |
| `model` | string | `flux-2-flex` | Image model to use (see Models below) |
| `aspectRatio` | enum | `landscape_16_9` | Aspect ratio for the image |
| `outputPath` | string | `generated-image.png` | File path relative to workspace |

### Aspect Ratios

| Value | Use Case |
|-------|----------|
| `landscape_16_9` | Blog covers, headers |
| `landscape_4_3` | Standard landscape |
| `square` | Social media, thumbnails |
| `portrait_9_16` | Mobile, stories |
| `portrait_4_5` | Instagram, portraits |

### Image Models

| Model | Provider | Cost | Best For |
|-------|----------|------|----------|
| `flux-2-flex` | FAL.AI | 4c | General purpose, prompt expansion (safe default) |
| `grok-imagine-image` | xAI | 3c | Fast, affordable creative images |
| `grok-imagine-image-pro` | xAI | 11c | Higher quality output |
| `gpt-image-1` | OpenAI | 6c | Photorealism, reliable text rendering (medium quality) |
| `gpt-image-1-hd` | OpenAI | 22c | OpenAI high-quality tier — use when text clarity or fine detail matters |

---

## Avatar Generation

A convenience action that forces `square` aspect ratio --- ideal for profile pictures.

```json
{
  "action": "generateAvatar",
  "prompt": "Professional headshot, friendly smile, neutral background",
  "outputPath": "avatar.png"
}
```

---

## Video Generation

### Image-to-Video

Animate a static image into a short video clip. Requires either `imagePath` (local file in workspace) or `imageUrl` (public URL).

```json
{
  "action": "imageToVideo",
  "imagePath": "images/product-shot.png",
  "prompt": "Subtle zoom in with gentle particle effects",
  "videoModel": "kling",
  "duration": 5,
  "outputPath": "videos/product-animation.mp4"
}
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `imagePath` | string | --- | Path to source image in workspace |
| `imageUrl` | string | --- | Public URL of source image (alternative to imagePath) |
| `prompt` | string | `""` | Motion/style description |
| `videoModel` | string | `kling` | Video model: `kling`, `wan`, or `grok` |
| `duration` | number | `5` | Duration in seconds (5 or 10) |
| `outputPath` | string | `generated-video.mp4` | Output file path |

### Video Models

| Model | Provider | 5s Cost | 10s Cost | Notes |
|-------|----------|---------|----------|-------|
| `kling` | FAL.AI | 53c | $1.05 | Premium quality, best motion |
| `wan` | FAL.AI | 30c | --- | Fast generation |
| `grok` | xAI | 38c | 75c | Requires `imageUrl` (public URL) |

**Note:** Grok video generation requires a public image URL (`imageUrl`), not a local file path. Upload the image first or provide an existing URL.

---

## Checking Balance

Before generating expensive media, check if the user has enough credits:

```json
{
  "action": "checkBalance",
  "estimateAction": "video",
  "videoModel": "kling",
  "duration": 10
}
```

Returns:

```json
{
  "sufficient": true,
  "balanceCents": 1250,
  "estimatedCostCents": 105,
  "balanceFormatted": "$12.50",
  "costFormatted": "$1.05"
}
```

---

## How It Works

1. **Agent calls the tool** --- the MCP server runs inside the computer service
2. **Balance pre-check** --- verifies the organization has enough credits
3. **API call** --- sends the request to FAL.AI or xAI depending on the model
4. **File saved** --- downloads the result and saves it to the workspace
5. **Credits deducted** --- only on successful generation

All generated files are saved to the agent's workspace (space directory). The agent can then reference them in responses, embed them in documents, or use them as inputs for further processing.

---

## Tips for Agents

- Always specify `outputPath` with a meaningful filename
- Use `checkBalance` before expensive video generation
- For blog images, use `landscape_16_9` aspect ratio
- For profile pictures, use `generateAvatar` (not `generateImage` with `square`)
- Grok models are the most affordable option for images (3c vs 4c for Flux)
- Kling produces the best video quality but costs more

---

## Pricing Summary

All costs are per generation in USD cents.

**Images:**

| Model | Cost per Image |
|-------|---------------|
| `grok-imagine-image` | 3c |
| `flux-2-flex` | 4c |
| `gpt-image-1` | 6c |
| `grok-imagine-image-pro` | 11c |
| `gpt-image-1-hd` | 22c |

**Videos:**

| Model + Duration | Cost |
|-----------------|------|
| `wan` 5s | 30c |
| `grok` 5s | 38c |
| `kling` 5s | 53c |
| `grok` 10s | 75c |
| `kling` 10s | $1.05 |