**3. Alternative — Direct MCP installation** (Claude Code / Desktop / Cursor):

**Claude Code:**

**Cursor** — Settings → MCP → Add:
- Command: `npx -y @evolinkai/evolink-media@latest`
- Environment: `EVOLINK_API_KEY=your-key-here`

After setup, restart your client. The MCP tools (`generate_image`, `generate_video`, `generate_music`, etc.) will appear automatically.

## Core Principles

1. **Guide, don't decide** — Present options and recommendations, but let the user make the final choice.
2. **User drives creative vision** — Ask for a description before suggesting parameters. Never assume style or format.
3. **Smart context awareness** — Remember what was generated in this session. Proactively offer to iterate, vary, or combine results.
4. **Intent first, parameters second** — Understand *what* the user wants before asking *how* to configure it.

## MCP Tool Reference

You have these tools available. Call them directly — no curl, no scripts, no extra dependencies.

| Tool | When to use | Returns |
|------|-------------|---------|
| `list_models` | User asks which model to use or wants to compare options | Formatted model list |
| `estimate_cost` | User asks about a specific model's capabilities or pricing | Model info + pricing link |
| `generate_image` | User wants to create or edit an image | `task_id` (async) |
| `generate_video` | User wants to create a video | `task_id` (async) |
| `generate_music` | User wants to create music or a song | `task_id` (async) |
| `upload_file` | User needs to upload a local file (image/audio/video) for generation workflows | File URL (synchronous) |
| `delete_file` | User needs to free file quota or remove an uploaded file | Deletion confirmation |
| `list_files` | User wants to see uploaded files or check storage quota | File list + quota info |
| `check_task` | Poll generation progress after submitting a task | Status, progress%, result URLs |

**Critical:** `generate_image`, `generate_video`, and `generate_music` all return a `task_id` immediately. You MUST call `check_task` repeatedly until `status` is `"completed"` or `"failed"`. Never report "done" based only on the initial response.

## Generation Flow

### Step 1: API Key Check

`EVOLINK_API_KEY` is automatically injected by OpenClaw. If a `401` error occurs mid-session, tell the user:
> "Your API key doesn't seem to be working. You can check or regenerate it at evolink.ai/dashboard/keys"

### File Upload & Management

When the user wants to use a **local file** for generation workflows:

1. Call `upload_file` with `file_path`, `base64_data`, or `file_url`
2. The upload is **synchronous** — you get a `file_url` back immediately
3. Use that `file_url` as input for `generate_image` (image_urls), `generate_video` (image_urls), or digital-human generation

**Supported formats:** Images (JPEG/PNG/GIF/WebP only), Audio (all formats), Video (all formats). Max **100MB**. Files expire after **72 hours**.

**Quota management:** Users have a file quota (100 default / 500 VIP). If quota is full:
1. Call `list_files` to see uploaded files and remaining quota
2. Call `delete_file` with the `file_id` to remove files no longer needed

### Step 2: Understand Intent

Start by understanding what the user wants to create:
- **Intent is clear** (e.g., "make a video of a cat dancing in rain") → Go directly to Step 3
- **Intent is ambiguous** (e.g., "I want to try this") → Ask: "What kind of content would you like — a video, an image, or music?"

Do NOT ask all parameters upfront. Ask only what's needed, only when it's needed.

### Step 3: Gather Missing Information

Check what the user has provided and **only ask about what's missing**.

#### For Image Generation

| Parameter | Ask when | Notes |
|-----------|----------|-------|
| **prompt** | Always required | Ask what they want to see |
| **model** | User asks or quality matters | Default: `gpt-image-1.5`. Suggest `gpt-4o-image` [BETA] for highest quality, `z-image-turbo` for speed |
| **size** | User mentions orientation or platform | **GPT models** (gpt-image-1.5, gpt-image-1, gpt-4o-image): `1024x1024`, `1024x1536`, `1536x1024`. **Other models**: ratio format `1:1`, `16:9`, `9:16`, `2:3`, `3:2`, etc. Omit to use model default. |
| **n** | User wants variations | 1–4 images |
| **image_urls** | User wants to edit or reference existing images | Up to 14 URLs; triggers image-to-image mode |
| **mask_url** | User wants to edit only part of an image | PNG mask; only works with `gpt-4o-image` |

#### For Video Generation

| Parameter | Ask when | Notes |
|-----------|----------|-------|
| **prompt** | Always required | Ask what scene they want |
| **model** | User asks or specific feature needed | Default: `seedance-1.5-pro`. See Model Quick Reference |
| **duration** | User mentions length | Range varies by model |
| **aspect_ratio** | User mentions portrait/vertical/widescreen | Default: `16:9` |
| **quality** | User mentions resolution preference | `480p` / `720p` / `1080p` |
| **image_urls** | User provides a reference image | 1 image = image-to-video; 2 images = first+last frame (`seedance-1.5-pro` only) |
| **generate_audio** | Using `seedance-1.5-pro` or `veo3.1-pro` [BETA] | Ask: "Want auto-generated audio (voice, SFX, music) added to the video?" |

#### For Music Generation

Music has two required fields — always collect both before calling `generate_music`.

**Decision tree (ask in this order):**

1. **Vocals or instrumental?**
   → Sets `instrumental: true/false`

2. **Simple mode or custom mode?**
   - **Simple mode** (`custom_mode: false`): AI writes lyrics and chooses style from your description. Easiest to use.
   - **Custom mode** (`custom_mode: true`): You control style tags, song title, and write lyrics with section markers like `[Verse]`, `[Chorus]`, `[Bridge]`.
   → Sets `custom_mode: true/false`

3. **If custom mode**, additionally collect:
   - `style`: genre + mood + tempo tags (e.g., `"pop, upbeat, female vocals, 120bpm"`)
   - `title`: song name (max 80 chars)
   - `vocal_gender`: `m` (male) or `f` (female) — optional

4. **Duration preference?**
   - `duration`: target length in seconds (30–240s). If not specified, model decides length.

5. **Optional for both modes:**
   - `negative_tags`: styles to exclude (e.g., `"heavy metal, screaming"`)
   - `model`: default `suno-v4`. Suggest `suno-v5` for studio-grade quality.

> **Rule:** NEVER call `generate_music` without both `custom_mode` and `instrumental` set. They are required API fields with no defaults.

### Step 4: Generate & Poll

1. Call the appropriate `generate_*` tool with the collected parameters
2. Tell the user: *"Generating your [type] now — estimated ~Xs. I'll update you on progress."*
   - Use `task_info.estimated_time` from the response if available
3. Poll with `check_task`, reporting updates:
   - **Image:** every 3–5 seconds
   - **Video:** every 10–15 seconds
   - **Music:** every 5–10 seconds
4. Report `progress` percentage to the user during polling
5. After 3 consecutive `processing` responses, reassure: *"Still working, this can take a moment..."*
6. **On `completed`:** Share the result URL(s). Remind: *"Download links expire in 24 hours — save them promptly."*
   - Check `result_data[]` for metadata (title, duration, tags for music)
7. **On `failed`:** Show error details and suggestion from `check_task` output. Offer to retry if retryable.

## Error Handling

### HTTP Errors (immediate)

| Error | What to tell the user |
|-------|----------------------|
| 401 Unauthorized | "Your API key isn't working. Check or regenerate it at evolink.ai/dashboard/keys" |
| 402 Payment Required | "Your account balance is low. Add credits at evolink.ai/dashboard/billing" |
| 429 Rate Limited | "Too many requests — let's wait 30 seconds and try again" |
| 503 Service Unavailable | "Evolink servers are temporarily busy. Let's try again in a minute" |

### Task Errors (from check_task when status is "failed")

| Error Code | Retryable | Action |
|------------|-----------|--------|
| `content_policy_violation` | No | Revise prompt — avoid real photos, celebrities, NSFW, violence |
| `invalid_parameters` | No | Check param values against model limits |
| `image_dimension_mismatch` | No | Resize image to match requested aspect ratio |
| `image_processing_error` | No | Check image format (JPG/PNG/WebP), size (<10MB), URL accessibility |
| `generation_timeout` | Yes | Retry; simplify prompt or lower resolution if repeated |
| `quota_exceeded` | Yes | Wait, then retry. Suggest topping up credits |
| `resource_exhausted` | Yes | Wait 30-60s and retry |
| `service_error` | Yes | Retry after 1 minute |
| `generation_failed_no_content` | Yes | Modify prompt and retry |

## Model Quick Reference

### Video Models (37 total — showing key picks)

| Model | Best for | Features | Audio |
|-------|----------|----------|-------|
| `seedance-1.5-pro` *(default)* | Image-to-video, first-last-frame | i2v, 4–12s, 1080p | auto |
| `seedance-2.0` | Next-gen motion (API pending) | placeholder | — |
| `sora-2-preview` | Cinematic preview | t2v, i2v, 1080p | — |
| `kling-o3-text-to-video` | Text-to-video, 1080p | t2v, 3–15s | — |
| `veo-3.1-generate-preview` | Google video preview | t2v, 1080p | — |
| `MiniMax-Hailuo-2.3` | High-quality video | t2v, 1080p | — |
| `wan2.6-text-to-video` | Alibaba latest t2v | t2v | — |
| `sora-2` [BETA] | Cinematic, prompt adherence | t2v, i2v, 1080p | — |
| `veo3.1-pro` [BETA] | Top quality + audio | t2v, 1080p | auto |

### Image Models (20 total — showing key picks)

| Model | Best for | Speed |
|-------|----------|-------|
| `gpt-image-1.5` *(default)* | Latest OpenAI generation | Medium |
| `gemini-3.1-flash-image-preview` | Nano Banana 2 — Google fast gen | Fast |
| `z-image-turbo` | Quick iterations | Ultra-fast |
| `doubao-seedream-4.5` | Photorealistic | Medium |
| `qwen-image-edit` | Instruction-based editing | Medium |
| `gpt-4o-image` [BETA] | Best quality, complex editing | Medium |
| `gemini-3-pro-image-preview` | Google generation preview | Medium |

### Music Models (all [BETA])

| Model | Quality | Max Duration | Notes |
|-------|---------|--------------|-------|
| `suno-v4` *(default)* | Good | 120s | Balanced, economical |
| `suno-v4.5` | Better | 240s | Style control |
| `suno-v4.5plus` | Better | 240s | Extended features |
| `suno-v4.5all` | Better | 240s | All v4.5 features |
| `suno-v5` | Best | 240s | Studio-grade output |

## Async Timing Guide

| Type | Typical time | Poll every | Max wait before warning |
|------|-------------|------------|------------------------|
| Image | 3–30 seconds | 3–5s | 5 minutes |
| Video | 30–180 seconds | 10–15s | 10 minutes |
| Music | 30–120 seconds | 5–10s | 5 minutes |

If a task exceeds the max wait time, inform the user: *"This is taking longer than expected. The task may still be running in the background — you can check it again with the task ID: [id]"*

## Cross-media Suggestions

After a successful generation, proactively offer connected creative options:

- **After image:** "Want to animate this into a video? I can use it as a reference image for `seedance-1.5-pro`."
- **After video:** "Would you like music to go with this? I can generate something that matches the mood."
- **After music:** "Want a visual to pair with this track? I can generate a matching image or video loop."
- **Anytime:** "Want a variation with a different style or model?"

## Without MCP Server — Direct File Hosting API

When MCP tools are not available, you can still use Evolink's file hosting service via `curl`. This is useful for uploading images, audio, or video files to get publicly accessible URLs.

**Base URL:** `https://files-api.evolink.ai`
**Auth:** `Authorization: Bearer $EVOLINK_API_KEY`

### Upload a Local File

Use `file_url` from the response as a publicly accessible link. Files expire after **72 hours**.

### List Files & Check Quota

{
  "evolink-media": {
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@evolinkai/evolink-media@latest"],
    "env": { "EVOLINK_API_KEY": "your-key-here" }
  }
}

{
  "mcpServers": {
    "evolink-media": {
      "command": "npx",
      "args": ["-y", "@evolinkai/evolink-media@latest"],
      "env": { "EVOLINK_API_KEY": "your-key-here" }
    }
  }
}

curl -X POST https://files-api.evolink.ai/api/v1/files/upload/stream \
  -H "Authorization: Bearer $EVOLINK_API_KEY" \
  -F "file=@/path/to/file.jpg"

curl -X POST https://files-api.evolink.ai/api/v1/files/upload/url \
  -H "Authorization: Bearer $EVOLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_url": "https://example.com/image.jpg"}'

{
  "data": {
    "file_id": "file_abc123",
    "file_url": "https://...",
    "download_url": "https://...",
    "file_size": 245120,
    "mime_type": "image/jpeg",
    "expires_at": "2025-03-01T10:30:00Z"
  }
}

curl https://files-api.evolink.ai/api/v1/files/list?page=1&pageSize=20 \
  -H "Authorization: Bearer $EVOLINK_API_KEY"

curl https://files-api.evolink.ai/api/v1/files/quota \
  -H "Authorization: Bearer $EVOLINK_API_KEY"