Skill: evolinkai/evolink-media (version 1.3.0)

--- name: evolink-media description: AI video, image & music generation. 60+ models — Sora, Veo 3, Kling, Seedance, GPT Image, Suno v5, Hailuo, WAN. Text-to-video, image-to-video, text-to-image, AI music. One API key. version: 1.3.0 metadata: openclaw: requires: env: - EVOLINK_API_KEY primaryEnv: EVOLINK_API_KEY emoji: 🎨 homepage: https://evolink.ai --- # Evolink Media — AI Creative Studio You are the user's AI creative partner, powered by Evolink Media. With the MCP server (`@evolinkai/evolink-media`) bridged via mcporter, you get 9 tools connecting to 60+ models across video, image, music, and digital-human generation. Without the MCP server, you can still use Evolink's file hosting API directly. ## After Installation When this skill is first loaded, check your available tools and greet the user: - **MCP tools available + `EVOLINK_API_KEY` set:** "Hi! I'm your AI creative studio — I can generate videos, images, and music using 60+ AI models. What would you like to create today?" - **MCP tools available + `EVOLINK_API_KEY` not set:** "To start creating, you'll need an EvoLink API key — sign up at evolink.ai and grab one from the dashboard. Ready to go?" - **MCP tools NOT available:** "I have the Evolink skill loaded, but the MCP server isn't connected yet. For the full experience (generate videos, images, music), bridge the MCP server via mcporter — it takes one command. Want me to help you set it up? In the meantime, I can still help you upload and manage files using Evolink's file hosting API." Do NOT list features, show a menu, or describe tools. Just ask one question to move forward. ## MCP Server Setup For the best experience, bridge the Evolink MCP server to unlock all generation tools. **MCP Server:** `@evolinkai/evolink-media` ([GitHub](https://github.com/EvoLinkAI/evolink-media-mcp) · [npm](https://www.npmjs.com/package/@evolinkai/evolink-media)) **1. Get API Key:** Sign up at [evolink.ai](https://evolink.ai) → Dashboard → API Keys **2. Bridge via mcporter** (recommended for OpenClaw users): ```bash mcporter call --stdio "npx -y @evolinkai/evolink-media@latest" list_models ``` Or add to mcporter config: ```json { "evolink-media": { "transport": "stdio", "command": "npx", "args": ["-y", "@evolinkai/evolink-media@latest"], "env": { "EVOLINK_API_KEY": "your-key-here" } } } ``` **3. Alternative — Direct MCP installation** (Claude Code / Desktop / Cursor): **Claude Code:** ```bash claude mcp add evolink-media -e EVOLINK_API_KEY=your-key -- npx -y @evolinkai/evolink-media@latest ``` **Claude Desktop** — add to `claude_desktop_config.json`: ```json { "mcpServers": { "evolink-media": { "command": "npx", "args": ["-y", "@evolinkai/evolink-media@latest"], "env": { "EVOLINK_API_KEY": "your-key-here" } } } } ``` **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 ```bash 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" ``` ### Upload from URL ```bash 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"}' ``` ### Response ```json { "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" } } ``` Use `file_url` from the response as a publicly accessible link. Files expire after **72 hours**. ### List Files & Check Quota ```bash 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" ``` ### Delete a File ```bash curl -X DELETE https://files-api.evolink.ai/api/v1/files/{file_id} \ -H "Authorization: Bearer $EVOLINK_API_KEY" ``` **Supported:** Images (JPEG/PNG/GIF/WebP), Audio (all formats), Video (all formats). Max **100MB**. Quota: 100 files (default) / 500 (VIP). > **Tip:** For full generation capabilities (create videos, images, music), bridge the MCP server `@evolinkai/evolink-media` via mcporter — see MCP Server Setup above. ## References - `references/api-params.md`: Complete API parameter reference for all tools

path: _meta.json
content: slug: evolink-media
version: 1.2.0

path: references/api-params.md
content: # Evolink Media API — Parameter Reference

Complete API parameter reference for all Evolink Media MCP tools.

**Base URL:** `https://api.evolink.ai`
**Auth:** `Authorization: Bearer {EVOLINK_API_KEY}`
**All generation endpoints are async** — they return `task_id` immediately; poll with `check_task`.

---

## generate_image

**Endpoint:** `POST /v1/images/generations`

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | **Yes** | — | Image description. Max 2000 characters. |
| `model` | enum | No | `gpt-image-1.5` | See Image Models below. |
| `size` | string | No | model default | Aspect ratio format: `1:1`, `16:9`, `9:16`, `2:3`, `3:2`, `4:3`, `3:4`, `4:5`, `5:4`, `21:9`. Pixel format (gpt-4o-image only): `1024x1024`, `1024x1536`, `1536x1024`. |
| `n` | integer 1–4 | No | 1 | Number of images to generate in one request. |
| `image_urls` | string[] | No | — | Reference image URLs for image-to-image or editing. Max 14 images. JPEG/PNG/WebP, ≤4MB each. |
| `mask_url` | string | No | — | PNG mask URL for partial inpainting. Only supported by `gpt-4o-image`. White areas = edit, black areas = keep. |

### Image Models (20)

#### Stable

| Model | Description | Key capability |
|-------|-------------|----------------|
| `gpt-image-1.5` *(default)* | OpenAI GPT Image 1.5 — latest generation | text-to-image, image-editing |
| `gpt-image-1` | OpenAI GPT Image 1 — high-quality generation | text-to-image, image-editing |
| `gemini-3.1-flash-image-preview` | Nano Banana 2 — Google Gemini 3.1 Flash | text-to-image, image-editing, fast |
| `gemini-3-pro-image-preview` | Google Gemini 3 Pro — image generation preview | text-to-image |
| `z-image-turbo` | Z-Image Turbo — fastest generation | text-to-image, ultra-fast |
| `doubao-seedream-4.5` | ByteDance Seedream 4.5 — photorealistic | text-to-image, photorealistic |
| `doubao-seedream-4.0` | ByteDance Seedream 4.0 — high-quality | text-to-image |
| `doubao-seedream-3.0-t2i` | ByteDance Seedream 3.0 — text-to-image | text-to-image |
| `doubao-seededit-4.0-i2i` | ByteDance Seededit 4.0 — image-to-image editing | image-editing |
| `doubao-seededit-3.0-i2i` | ByteDance Seededit 3.0 — image-to-image editing | image-editing |
| `qwen-image-edit` | Alibaba Qwen — instruction-based editing | image-editing, instruction-based |
| `qwen-image-edit-plus` | Alibaba Qwen Plus — advanced editing | image-editing, instruction-based |
| `wan2.5-t2i-preview` | Alibaba WAN 2.5 — text-to-image preview | text-to-image |
| `wan2.5-i2i-preview` | Alibaba WAN 2.5 — image-to-image preview | image-editing |
| `wan2.5-text-to-image` | Alibaba WAN 2.5 — text-to-image | text-to-image |
| `wan2.5-image-to-image` | Alibaba WAN 2.5 — image-to-image | image-editing |

#### Beta

| Model | Description | Key capability |
|-------|-------------|----------------|
| `gpt-image-1.5-lite` [BETA] | OpenAI GPT Image 1.5 Lite — fast lightweight | text-to-image, fast |
| `gpt-4o-image` [BETA] | OpenAI GPT-4o Image — best prompt understanding + editing | text-to-image, image-editing, best-quality |
| `gemini-2.5-flash-image` [BETA] | Google Gemini 2.5 Flash — fast image generation | text-to-image, fast |
| `nano-banana-2-lite` [BETA] | Nano Banana 2 Lite — versatile general-purpose | text-to-image, fast |

---

## generate_video

**Endpoint:** `POST /v1/videos/generations`

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | **Yes** | — | Video description. Max 5000 characters. |
| `model` | enum | No | `seedance-1.5-pro` | See Video Models below. |
| `duration` | integer | No | model default | Duration in seconds. Range varies by model. |
| `quality` | enum | No | model default | `480p` / `720p` / `1080p` / `4k`. Availability varies by model. |
| `aspect_ratio` | enum | No | `16:9` | `16:9` / `9:16` / `1:1` / `4:3` / `3:4` / `21:9` / `adaptive` |
| `image_urls` | string[] | No | — | Reference images. **1 image** = image-to-video. **2 images** = first-frame + last-frame (`seedance-1.5-pro` only). Max 9 images. JPEG/PNG/WebP, ≤30MB each. |
| `generate_audio` | boolean | No | model default | Auto-generate synchronized audio. Supported by `seedance-1.5-pro` (default: `true`) and `veo3.1-pro` [BETA]. |

### Video Models (37)

#### Stable

| Model | Description | Key features |
|-------|-------------|--------------|
| `seedance-1.5-pro` *(default)* | ByteDance Seedance 1.5 Pro | text-to-video, image-to-video, first-last-frame, 4–12s, 1080p, audio-generation |
| `seedance-2.0` | ByteDance Seedance 2.0 (placeholder, API pending) | text-to-video, image-to-video |
| `doubao-seedance-1.0-pro-fast` | ByteDance Seedance 1.0 Pro Fast | text-to-video, fast |
| `sora-2-preview` | OpenAI Sora 2 Preview | text-to-video, image-to-video, 1080p |
| `kling-o3-text-to-video` | Kuaishou Kling O3 — text-to-video | text-to-video, 3–15s, 1080p |
| `kling-o3-image-to-video` | Kuaishou Kling O3 — image-to-video | image-to-video, 1080p |
| `kling-o3-reference-to-video` | Kuaishou Kling O3 — reference-guided | reference-to-video, 1080p |
| `kling-o3-video-edit` | Kuaishou Kling O3 — video editing | video-edit, 1080p |
| `kling-v3-text-to-video` | Kuaishou Kling V3 — text-to-video | text-to-video, 1080p |
| `kling-v3-image-to-video` | Kuaishou Kling V3 — image-to-video | image-to-video, 1080p |
| `kling-o1-image-to-video` | Kuaishou Kling O1 — image-to-video | image-to-video |
| `kling-o1-video-edit` | Kuaishou Kling O1 — video editing | video-edit |
| `kling-o1-video-edit-fast` | Kuaishou Kling O1 — fast video editing | video-edit, fast |
| `kling-custom-element` | Kuaishou Kling — custom element video | custom-element |
| `veo-3.1-generate-preview` | Google Veo 3.1 — generation preview | text-to-video, 1080p |
| `veo-3.1-fast-generate-preview` | Google Veo 3.1 — fast generation preview | text-to-video, fast, 1080p |
| `MiniMax-Hailuo-2.3` | MiniMax Hailuo 2.3 — high-quality | text-to-video, 1080p |
| `MiniMax-Hailuo-2.3-Fast` | MiniMax Hailuo 2.3 Fast | text-to-video, fast, 1080p |
| `MiniMax-Hailuo-02` | MiniMax Hailuo 02 | text-to-video |
| `wan2.5-t2v-preview` | Alibaba WAN 2.5 — text-to-video preview | text-to-video |
| `wan2.5-i2v-preview` | Alibaba WAN 2.5 — image-to-video preview | image-to-video |
| `wan2.5-text-to-video` | Alibaba WAN 2.5 — text-to-video | text-to-video |
| `wan2.5-image-to-video` | Alibaba WAN 2.5 — image-to-video | image-to-video |
| `wan2.6-text-to-video` | Alibaba WAN 2.6 — text-to-video | text-to-video |
| `wan2.6-image-to-video` | Alibaba WAN 2.6 — image-to-video | image-to-video |
| `wan2.6-reference-video` | Alibaba WAN 2.6 — reference-guided | reference-to-video |

#### Beta

| Model | Description | Key features |
|-------|-------------|--------------|
| `sora-2` [BETA] | OpenAI Sora 2 — cinematic video | text-to-video, image-to-video, 1080p |
| `sora-2-pro` [BETA] | OpenAI Sora 2 Pro — premium cinematic | text-to-video, image-to-video, 1080p, premium |
| `sora-2-beta-max` [BETA] | OpenAI Sora 2 Beta Max — maximum quality | text-to-video, 1080p, max-quality |
| `sora-character` [BETA] | OpenAI Sora Character — character-consistent | text-to-video, character-consistency |
| `veo3.1-pro` [BETA] | Google Veo 3.1 Pro — top-tier cinematic + audio | text-to-video, 1080p, audio-generation |
| `veo3.1-fast` [BETA] | Google Veo 3.1 Fast — fast high-quality | text-to-video, fast, 1080p |
| `veo3.1-fast-extend` [BETA] | Google Veo 3.1 Fast Extend — extended generation | text-to-video, fast, extend |
| `veo3` [BETA] | Google Veo 3 — cinematic video | text-to-video, 1080p |
| `veo3-fast` [BETA] | Google Veo 3 Fast — fast video | text-to-video, fast |
| `grok-imagine-text-to-video` [BETA] | xAI Grok Imagine — text-to-video | text-to-video |
| `grok-imagine-image-to-video` [BETA] | xAI Grok Imagine — image-to-video | image-to-video |

---

## generate_music

**Endpoint:** `POST /v1/audios/generations`

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | **Yes** | — | **Simple mode:** music description (max 500 chars). **Custom mode:** full lyrics with section tags like `[Verse]`, `[Chorus]`, `[Bridge]`, `[Outro]` (max 3000 chars for v4, 5000 for v4.5+). |
| `model` | enum | No | `suno-v4` | See Music Models below. |
| `custom_mode` | boolean | **Yes** | — | `false` = AI generates lyrics and style from your description. `true` = you control style, title, and lyrics. **No default — must always be set.** |
| `instrumental` | boolean | **Yes** | — | `true` = no vocals (instrumental only). `false` = with vocals. **No default — must always be set.** |
| `style` | string | No* | — | Comma-separated genre/mood/tempo tags. e.g. `"pop, upbeat, female vocals, 120bpm"`. *Required when `custom_mode: true`. |
| `title` | string | No* | — | Song title. Max 80 characters. *Required when `custom_mode: true`. |
| `negative_tags` | string | No | — | Styles to exclude. e.g. `"heavy metal, distorted guitar"`. |
| `vocal_gender` | enum | No | — | `m` (male) or `f` (female). Only effective in custom mode. |

### Music Models (5, all [BETA])

| Model | Quality | Max duration | Notes |
|-------|---------|--------------|-------|
| `suno-v4` *(default)* | Good | 120s | Balanced quality, economical |
| `suno-v4.5` | Better | 240s | Improved style control |
| `suno-v4.5plus` | Better | 240s | Extended v4.5 features |
| `suno-v4.5all` | Better | 240s | Full v4.5 feature set |
| `suno-v5` | Best | 240s | Studio-grade, best quality |

---

## Digital Human

**Note:** Digital human generation uses `omnihuman-1.5` — audio-driven digital human video generation with lip-sync, portrait animation, and auto-masking support.

---

## check_task

**Endpoint:** `GET /v1/tasks/{task_id}`

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Task ID |
| `model` | string | Model used for generation |
| `status` | enum | `pending` / `processing` / `completed` / `failed` |
| `progress` | integer | Progress percentage (0–100) |
| `results[]` | string[] | Direct result URLs — images, video MP4, or audio files |
| `result_data[].video_url` | string | Video download URL |
| `result_data[].image_url` | string | Image download URL |
| `result_data[].audio_url` | string | Audio file download URL |
| `result_data[].stream_audio_url` | string | Streaming audio URL |
| `result_data[].title` | string | Music track title (music only) |
| `result_data[].duration` | number | Duration in seconds |
| `result_data[].tags` | string | Auto-generated style tags (music only) |
| `task_info.estimated_time` | integer | Estimated seconds remaining |
| `task_info.can_cancel` | boolean | Whether the task can be cancelled |
| `usage.credits_reserved` | number | Credits charged for this task |
| `usage.billing_rule` | string | Billing rule applied |
| `error.code` | string | Error code (only when `status: "failed"`) |
| `error.message` | string | Error description (only when `status: "failed"`) |
| `error.type` | string | Error type (only when `status: "failed"`) |

**Note:** All result URLs expire in **24 hours**. Download promptly.

### Status Values

| Status | Meaning | Action |
|--------|---------|--------|
| `pending` | Queued, not started | Continue polling |
| `processing` | Generation in progress | Continue polling, report `progress` |
| `completed` | Generation finished | Extract URLs from `results[]` or `result_data[]` |
| `failed` | Generation failed | Read `error.code` + `error.message`, surface to user |

---

## File Management API

**Base URL:** `https://files-api.evolink.ai` (different from generation API)
**Auth:** `Authorization: Bearer {EVOLINK_API_KEY}` (same API key)

All file endpoints are **synchronous** — no task polling needed.

### upload_file

Three upload methods available:

| Method | Endpoint | Content-Type | Use when |
|--------|----------|-------------|----------|
| Base64 | `POST /api/v1/files/upload/base64` | `application/json` | Have base64 data |
| Stream | `POST /api/v1/files/upload/stream` | `multipart/form-data` | Have a local file |
| URL | `POST /api/v1/files/upload/url` | `application/json` | Have a remote URL |

**MCP Tool Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file_path` | string | One of three | Local file path. Uses stream upload internally. |
| `base64_data` | string | One of three | Base64-encoded data (raw or Data URL format). |
| `file_url` | string | One of three | Remote URL. Server downloads and stores it. |
| `upload_path` | string | No | Server-side subdirectory for organizing uploads. |
| `file_name` | string | No | Custom file name. |

**Response Fields:**

| Field | Type | Description |
|-------|------|-------------|
| `data.file_id` | string | Unique file identifier (use for delete) |
| `data.file_name` | string | Stored file name |
| `data.original_name` | string | Original file name |
| `data.file_size` | number | File size in bytes |
| `data.mime_type` | string | MIME type (e.g., `image/jpeg`) |
| `data.file_url` | string | Public URL — use as `image_urls` input |
| `data.download_url` | string | Direct download URL |
| `data.upload_time` | string | Upload timestamp |
| `data.expires_at` | string | Expiration timestamp |

### delete_file

**Endpoint:** `DELETE /api/v1/files/{file_id}`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file_id` | string | Yes | File ID to delete |

### list_files

**Endpoints:** `GET /api/v1/files/list` + `GET /api/v1/files/quota` (called together)

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | Page number (default: 1) |
| `page_size` | integer | No | Files per page (default: 20, max: 100) |

### File API Constraints

- **Supported formats:**
  - Images: JPEG, PNG, GIF, WebP (only these 4 types)
  - Audio: all formats (`audio/*`) — MP3, WAV, FLAC, AAC, OGG, M4A, etc.
  - Video: all formats (`video/*`) — MP4, MOV, AVI, MKV, WebM, FLV, etc.
- **Max file size:** 100MB
- **File expiry:** 72 hours from upload (auto-deleted)
- **File quota:** 100 files (default) / 500 files (VIP)
- **Same-name override:** Uploading a file with an existing name overwrites the old file (may have cache delay)
- **1 file per request**

### File API Error Codes

| Code | Description | Resolution |
|------|-------------|------------|
| 400 | Bad request | Check parameters |
| 401 | Unauthorized | Verify API key |
| 403 | Forbidden | Check account permissions |
| 404 | File not found | Verify file_id |
| 40001 | File too large | Compress to under 100MB |
| 40002 | File type not allowed | Check supported formats |
| 40003 | Quota exceeded | Delete files with `delete_file` to free quota |
| 40004 | URL download failed | Verify the source URL is accessible |
| 500 | Server error | Retry |
| 50001 | Storage service error | Retry after 1 minute |

---

## Polling Strategy

### Recommended Intervals

| Type | Initial wait | Poll interval | Max wait |
|------|-------------|---------------|----------|
| Image | 3s | 3–5s | 5 minutes |
| Video | 15s | 10–15s | 10 minutes |
| Music | 5s | 5–10s | 5 minutes |

### Algorithm

1. Submit generation → receive `task_id`
2. Wait the initial delay for the media type
3. Call `check_task` → inspect `status`
4. If `pending` or `processing`: wait poll interval, repeat step 3
5. If `completed`: extract URLs from `results[]` (array of strings) or `result_data[]` (objects with typed fields)
6. If `failed`: read `error.code` and `error.message`, surface to user with actionable suggestion

### Timeout Handling

After max wait time, inform the user:
*"This is taking longer than expected. The task ID is `{task_id}` — you can check it again later."*

---

## Error Codes

### HTTP Status Codes

| Code | Meaning | Resolution |
|------|---------|------------|
| 400 | Bad request — invalid params or content blocked | Check required fields; revise prompt |
| 401 | Invalid or missing API key | Verify `EVOLINK_API_KEY` at evolink.ai/dashboard/keys |
| 402 | Insufficient credits | Top up at evolink.ai/dashboard/billing |
| 403 | Access denied | Check account permissions |
| 404 | Resource not found | Verify `task_id` is correct |
| 413 | Payload too large | Compress images to under 4MB |
| 429 | Rate limit exceeded | Wait 30–60 seconds, then retry |
| 500 | Internal server error | Retry after 1 minute |
| 502 | Upstream unavailable | Retry after 1 minute |
| 503 | Service unavailable | Retry after 1–2 minutes |

### Task Error Codes (from check_task when status is "failed")

| Code | Retryable | Description | Resolution |
|------|-----------|-------------|------------|
| `content_policy_violation` | No | Prompt blocked by safety filter | Rephrase; avoid explicit violence, NSFW, real person names |
| `invalid_parameters` | No | Invalid parameter values | Check param values against model limits |
| `image_dimension_mismatch` | No | Image dimensions don't match request | Resize image to match requested aspect ratio |
| `image_processing_error` | No | Failed to process input image | Check format (JPG/PNG/WebP), size (<10MB), URL accessibility |
| `model_unavailable` | No | Model temporarily offline | Call `list_models` to find available alternatives |
| `generation_timeout` | Yes | Generation exceeded time limit | Retry; simplify prompt or lower resolution if repeated |
| `quota_exceeded` | Yes | Account credits depleted | Wait, then retry. Top up at evolink.ai/dashboard/billing |
| `resource_exhausted` | Yes | Server resources temporarily full | Wait 30–60 seconds and retry |
| `service_error` | Yes | Internal service error | Retry after 1 minute |
| `generation_failed_no_content` | Yes | Generation produced no output | Modify prompt and retry |
| `upstream_error` | Yes | Upstream provider error | Retry after 1 minute |
| `rate_limited` | Yes | Rate limit at task level | Wait 30 seconds and retry |
| `unknown_error` | Yes | Unclassified error | Retry; contact support if persistent |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: suspicious | SkillSpector: clean (LOW)