# EvoLink MCP reading guide

Give this file to your agent to explain EvoLink MCP tools and the calling workflow. Reading it does not install the server, sign in, or authorize paid generation. This guide covers a remote connection authenticated through browser sign-in. The connected server's tool definitions and `get_model` responses are authoritative for available tools, parameters, and model capabilities.

- MCP server: `https://mcp.evolink.ai/mcp`
- Capabilities: discover models, read parameters and prices, estimate costs, generate images/video/music/speech, upload references, and query or recover tasks.
- Billing: approximately 68 credits = USD 1. Queries and upload tools do not charge generation fees. The three `generate_*` tools create paid tasks. Uploads remain subject to file quotas.
- Models, prompts, durations, and amounts below illustrate call formats. They are not user approval to execute. Read the current model details and estimate before submitting.

## What MCP does

MCP (Model Context Protocol) lets an Agent discover and call external tools. After the user adds EvoLink MCP to their assistant and completes authorization, the client exposes tool names and input schemas. The Agent uses those tools to discover models, upload references, estimate costs, submit generation tasks, and retrieve results. The MCP service is not a chat model, and reading this file does not add a connection to the client.

This file is a standalone guide that users can save and attach to their Agent. It covers all 12 tools in the remote browser-login connection. Always use the connected service's current tool schemas: models, prices, supported parameters, and account permissions can change, so examples and historical tasks do not establish current capabilities.

### The three online entry points

| Address | Purpose | How the Agent uses it |
|---|---|---|
| `https://mcp.evolink.ai/mcp` | EvoLink media generation MCP | Connect through an MCP-capable client, complete browser authorization, then call the tools described here |
| `https://evolink.ai/docs/mcp` | Documentation search MCP | Connect to search and read public EvoLink documentation; this service does not expose media generation tools |
| `https://evolink.ai/docs/llms.txt` | Documentation index for Agents | Read the text directly and follow links to relevant articles; no MCP connection is required |

`https://docs.evolink.ai/llms.txt` redirects to the documentation index above. Large API sections may link to generated indexes under `/_llms/`; follow those links to reach the documentation pages. Documentation retrieval does not replace a connection to the generation service, account authorization, or spending approval.

## Capability scope

Describe EvoLink MCP as media generation/editing, model/parameter/price discovery, reference uploads, task/result queries and balance queries. Coding, website development and general local file/document work depend on the host agent's own tools. If asked about the entire assistant, distinguish those capabilities from EvoLink MCP. Balance and task queries do not imply API key management, task cancellation or account-setting changes.

## Connection and authorization

1. Add `https://mcp.evolink.ai/mcp` in your assistant client's MCP settings. Support for remote HTTP MCP, tool display, and connection refresh depends on the client.
2. Follow the client's browser flow to sign in to EvoLink and authorize the connection. Do not put API keys or access tokens in the conversation or this file.
3. Return to the assistant, confirm the EvoLink tools are visible, and call `check_balance` to verify the connection. If tools are missing, check the connection, login, and client loading state before generating.
4. The remote browser-login connection exposes the 12 tools below. Local API-key deployments may expose a different list, including whether one-time upload tools are available; use the actual connected list.

Connection authorization grants tool access. Individual generation tasks still require the user's approval for their scope and cost. Available balance, a successful connection, or a completed upload does not approve a paid generation task.

## Instructions for the agent

1. Confirm that EvoLink tools are connected. If unavailable, help the user connect and complete browser authorization, then verify with `check_balance`. Reading this file alone does not establish a connection.
2. Use `search_models` and `get_model` before generation. Do not guess model IDs, parameter names, enums, or defaults. Follow the user's explicit choice of another platform when provided.
3. Upload references when needed. The remote server cannot read the user's local paths. Do not pass `/Users/...`, `C:\...`, or an internal chat attachment address as a downloadable model URL.
4. Call `estimate_cost` with the exact planned input. Explain the model, quantity, duration/resolution/audio, estimated price, and unknown charges. End the response and wait for explicit approval. An agent's suggested budget, an example amount, or a vague request to try something is not budget approval.
5. Submit only after approval for the task or a defined batch and budget. Additional variants, reruns, and changed inputs need corresponding authorization. Never remove a user-required cost cap automatically.
6. Save `task_id` and `client_request_id` after submission. Query the existing task. Once complete, immediately deliver original result links, the model, and actual cost. A generation request does not automatically authorize local editing, compositing, transcoding, or quality repair.
7. If quality is unsatisfactory, deliver the result and explain the issue, then let the user choose the next action. Modify media only when the user explicitly requests or authorizes it; distinguish originals from edited versions.
8. Provide clear view/download links by default. Never put MP4 or another non-image URL in `![image](URL)`. Whether the client displays a thumbnail does not determine whether generation succeeded.

A specifically approved batch may continue within its defined scope and budget. Ask again when scope or pricing changes, or costs become unknown. These are agent instructions, not a claim that the server requires individual approvals or every client displays a confirmation dialog.

## Model selection

Honor the user's explicit model/provider choice, required features and budget first. For an unspecified model, search these platform-preferred families and compare suitable candidates with `get_model`:

| Task | Preferred families | Selection notes |
|---|---|---|
| Images, advertising images and image editing | GPT Image 2.5 / 2, Seedream 5.0 | Current IDs include `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`, `gpt-image-2`, `doubao-seedream-5.0-pro`; verify references, output settings and billing |
| Video | Seedance 2.5 / 2.0, Wan 3.0 | Choose the appropriate text, image, reference or editing route; a draft-to-video route is not ordinary text-to-video |
| Music or songs | Suno v6 | Current canonical ID is `suno-v6`; use aliases actually returned by the catalog |
| Speech, narration or TTS | Available speech models | Match language, voice and reference support; the Suno music preference does not apply to narration |

These are editorial platform preferences, not measured popularity or quality rankings. Search relevant families rather than selecting the first result. If search returns `recommendation`, `basis: platform_preference` identifies the preference and `use_case` identifies its category; still check the actual task. Keyword relevance comes first; preferences break ties after price availability.

Choose another available model when it better fits the request or budget, and explain the choice briefly. Prefer a suitable non-Beta route when comparable; explain why if choosing Beta. Do not invent release dates, availability, parameters or rates. Resolve or disclose missing documentation or rates before proposing a paid call. GPT Image token rates are not a fixed per-image total; still use `estimate_cost` and follow spending approval.

## Reading the examples

Each JSON example is the parameter object for MCP `tools/call`: `name` identifies the tool and `arguments` contains its inputs. Use the EvoLink tool entry points actually exposed by the client; prefixes vary. Do not bypass MCP by calling the platform's HTTP generation API directly.

```json
{"name":"check_balance","arguments":{}}
```

This guide contains no credentials. Do not ask users to paste API keys, access tokens, or upload tokens into chat. Replace placeholders such as `TASK_ID_FROM_RESPONSE` and `UPLOAD_ID_FROM_RESPONSE` with actual returned values. Examples illustrate calling structure rather than default model recommendations.

## Tool overview

| Tool | Purpose | Generation fee |
|---|---|---|
| `search_models` | Find image, video, or audio models | No |
| `get_model` | Read input parameters, examples, and prices | No |
| `estimate_cost` | Validate input and estimate without submitting | No |
| `generate_image` | Generate or edit images | Yes |
| `generate_video` | Generate or edit videos | Yes |
| `generate_audio` | Generate music, songs, or speech | Yes |
| `get_task` | Query one task, wait, and read results | No |
| `list_tasks` | Find recent tasks or query known tasks in bulk | No |
| `check_balance` | Read balance, spending, and limits | No |
| `upload_file` | Store a public reference URL or small file data | No |
| `prepare_upload` | Obtain a one-time URL for a larger local file | No |
| `get_upload` | Read one-time upload status and its file URL | No |

## 1. search_models: discover models

| Argument | Type | Meaning |
|---|---|---|
| `type` | String | `image`, `video`, `audio`, or `all`; default `all` |
| `query` | Optional string | Keywords, up to 100 characters, such as `seedance` or `music` |
| `limit` | Integer | 1–50, default 20 |

```json
{"name":"search_models","arguments":{"type":"video","query":"seedance","limit":5}}
```

Read `models[].id`, type, starting price, and documentation links. A starting price is not the total for the proposed task. If no model matches, broaden the query. Next call `get_model` with a returned ID.

## 2. get_model: parameters and prices

Required `model`: a model ID from search, 1–128 characters.

```json
{"name":"get_model","arguments":{"model":"z-image-turbo"}}
```

Read `type`, `tool`, `required`, `parameters`, `example_input`, and `prices`. Parameter definitions specify types, required fields, enums, ranges, and defaults. A model may use `size` instead of `aspect_ratio`; these are not interchangeable. Only send reference images to models that accept them.

Put model-specific parameters inside generation `input`. Tool-level arguments such as `max_cost_usd` belong at the top of `arguments`. Do not put `model` or `callback_url` inside `input`. If documentation or pricing is missing, explain the limitation rather than inventing settings or assuming no charge.

## 3. estimate_cost: validate and estimate

| Argument | Type | Meaning |
|---|---|---|
| `model` | Required string | Selected model ID |
| `input` | Optional object | Exact planned model input; use the same values when generating |
| `media_seconds` | Optional number | Greater than 0, at most 3600; only for per-second models without a `duration` parameter |

```json
{"name":"estimate_cost","arguments":{"model":"z-image-turbo","input":{"prompt":"A red apple on a white background, soft natural light","size":"1:1"}}}
```

Read `input_valid`, `problems`, `warnings`, and `estimate`. Correct invalid inputs and estimate again. `input_valid: null` means complete validation information is unavailable, not that validation passed.

| `estimate.status` | Action |
|---|---|
| `estimated` | Explain the range, basis, and possible extras; obtain approval |
| `partial` | Explain that it is only part of the charge, not a total or upper bound |
| `needs_input` | Supply missing duration or other information and estimate again |
| `token_billed` | Explain that usage determines the charge after execution |
| Other or unavailable price | Explain that a reliable estimate is unavailable; do not treat it as zero |

Published estimates may differ from settlement. References, audio, resolution, and other options can affect cost. An adequate balance does not constitute approval.

`media_seconds` only assists estimation; it is not forwarded to the model and does not set output duration. It does not replace `input.duration` or resolve incomplete reference-video pricing. Omit it if the connected tool definition does not support it.

Before estimating per-second billing, check whether the rate applies to input media or generated output. If a model has no `duration` parameter, do not add that field to `input` merely to obtain an estimate. For audio whose output duration is known only after generation, expected seconds can illustrate a possible cost; they do not establish a final total or upper bound. Explain the limitation and wait for the user's decision when their requested spending cap cannot be verified reliably.

## Common arguments for the three generate tools

| Argument | Type | Meaning |
|---|---|---|
| `model` | Required string | Model ID matching the output type; 1–128 characters |
| `input` | Optional object | Parameters listed by `get_model` |
| `prompt` | Optional string | Shortcut for `input.prompt`, up to 20000 characters; model limits still apply |
| `client_request_id` | Optional string | 16–96 characters, letters/digits/`.`/`_`/`-`; same-request network recovery |
| `max_cost_usd` | Optional number | Greater than 0, at most USD 10000; must reflect an explicitly approved budget |
| `media_seconds` | Optional number | Estimation helper described above, when supported |

Prefer defining the prompt once in `input.prompt`. Conflicting top-level and nested prompts are refused. `max_cost_usd` checks an estimate before submission; it is not a guarantee about final settlement. When the connected tool requires a complete estimate, partial reference-video pricing, token billing, or missing pricing may make a cap unusable. Explain a refusal; do not silently remove the cap and submit.

A `client_request_id` identifies one authorized logical request. Reuse it only to recover the same request after a network error or timeout. Changed parameters or additional variants need a new request ID and corresponding approval. If a task ID is already known, use `get_task` instead of submitting again.

## 4. generate_image: create or edit an image

Paid. Read the selected image model, estimate the same input, obtain approval, and then submit:

```json
{"name":"generate_image","arguments":{"model":"z-image-turbo","input":{"prompt":"A red apple on a white background, soft natural light","size":"1:1"},"client_request_id":"image-apple-demo-001"}}
```

The example illustrates format, not approval. For editing, choose a model that supports references or editing and follow its input definition. Do not assume this example model accepts `image_urls`.

The tool normally waits up to about 40 seconds for image results. If still running, save `task_id` and use `get_task`. Do not call `generate_image` again to refresh progress.

## 5. generate_video: create or edit a video

Paid. Text-to-video example:

```json
{"name":"generate_video","arguments":{"model":"seedance-2.0-mini-text-to-video","input":{"prompt":"A kitten walks through grass, gentle camera push, natural light","duration":8,"quality":"720p","aspect_ratio":"16:9","generate_audio":true,"content_filter":true},"client_request_id":"video-cat-demo-001"}}
```

Image-to-video, reference-to-video, extension, and editing depend on the selected model. Use `image_urls`, `video_urls`, `video_url`, or `source_task_id` only when the model defines them. Check combination constraints and charges for duration, resolution, audio, and references.

Video usually returns `task_id` immediately. Wait with `get_task`. On completion, deliver the original video link directly. Generation does not authorize automatic audio replacement, overlays, or local repair.

## 6. generate_audio: music, songs, or speech

Paid. Search `audio` models for the requested use, then read the selected model's example and parameters. Speech example:

```json
{"name":"generate_audio","arguments":{"model":"doubao-seed-audio-1-0","input":{"prompt":"Welcome to EvoLink. The weather is lovely today.","format":"mp3"},"client_request_id":"audio-speech-demo-001"}}
```

Music example (simple mode, with model-generated lyrics and style):

```json
{"name":"generate_audio","arguments":{"model":"suno-v6","input":{"prompt":"A cheerful summer pop song about road trips and freedom"},"client_request_id":"audio-music-demo-001"}}
```

Examples are not execution approval. Music models may accept descriptions, lyrics, or modes; speech models may accept text, language, and voice settings. Field names are model-specific; do not assume every audio model uses `prompt`. For example, Suno's simple and custom modes support different fields, and Seed-Audio's audio and image references are mutually exclusive. Estimate the prepared input and obtain approval before submission.

Use `get_task` for the returned task ID. A music task may produce multiple tracks or audio/cover results; deliver all relevant links. Do not create paid tasks automatically to fill perceived gaps.

## 7. get_task: progress and results

| Argument | Type | Meaning |
|---|---|---|
| `task_id` | Required string | ID returned by the generate tool, preserved unchanged |
| `wait_seconds` | Integer | 0–45, default 30; 0 checks immediately |

```json
{"name":"get_task","arguments":{"task_id":"TASK_ID_FROM_RESPONSE","wait_seconds":30}}
```

Read `status`, `progress`, links, and charges. Running states commonly include `pending` and `processing`; terminal states are `completed`, `failed`, and `cancelled`. Follow actual responses.

- Running: continue querying the same ID and communicate progress. Avoid tight loops with `wait_seconds: 0`.
- `completed`: immediately deliver results, model, and final charge. Result links typically expire after 24 hours; advise saving them promptly.
- `failed` / `cancelled`: explain the returned error and billing information. Let the user decide whether to submit again.
- Query timeout: this does not prove generation failed. Query the original task again or recover it with `list_tasks`.

If the response provides `delivery_markdown` or result resource links, use the original result entry points. Always retain a clickable view/download link. Clients may not embed media; do not automatically construct remote image previews.

The service may also return small image content blocks for image thumbnails or a video's first frame. These previews are not the original files. Use content and original links already returned by the tool. Do not generate a new cover, edit or re-encode a result, or resubmit the task because a preview failed. The client controls the placement of Logos, tool icons, and previews.

## 8. list_tasks: recovery and batch queries

| Argument | Type | Meaning |
|---|---|---|
| `task_ids` | Optional string array | 1–50 known task IDs to query in bulk |
| `status` | Optional string | `processing`, `completed`, `failed`, `cancelled`; recent-task mode |
| `type` | Optional string | `image`, `video`, `audio`; recent-task mode |
| `since` | Optional string | ISO 8601, Unix seconds, or relative `30m`/`2h`/`1d`; up to 40 characters |
| `limit` | Integer | 1–50, default 20; recent-task mode |

```json
{"name":"list_tasks","arguments":{"type":"video","since":"2h","limit":10}}
```

```json
{"name":"list_tasks","arguments":{"task_ids":["TASK_ID_1_FROM_RESPONSE","TASK_ID_2_FROM_RESPONSE"]}}
```

When `task_ids` is supplied, other filters do not apply. Recent tasks cover the whole EvoLink account, newest first, not just the current chat. Identify the intended task from model, time, and task information; ask the user if ambiguous.

The `processing` filter includes queued tasks. `since` filters the fetched page rather than scanning all history. Absence from one result page does not prove submission failed. Batch results may contain `missing`; check IDs, account, or retention.

## 9. check_balance: balance and spending limits

No arguments:

```json
{"name":"check_balance","arguments":{}}
```

Read `account_balance_credits`, the USD approximation, `spent_scope`, total spending, and limits. With browser sign-in, MCP spending and limits cover all assistants connected to that account, not a single window, chat, or task.

Account balance, the MCP limit, and daily limits are distinct. Explain shortages. Do not automatically top up, change limits, switch credentials, or bypass restrictions.

## 10. upload_file: public URL or small file data

For remote sign-in, supply exactly one of `file_url` and `base64_data`.

| Argument | Type | Meaning |
|---|---|---|
| `file_url` | Optional string | Public HTTPS media URL downloadable without authentication or embedded credentials |
| `base64_data` | Optional string | Raw base64 or a Data URL; at most 1 MB decoded with sign-in |
| `mime_type` | Optional string | Required for raw base64; must match a Data URL's type when supplied |
| `file_name` | Optional string | Plain filename without directory separators |
| `upload_path` | Optional string | Relative storage directory without `..`; not a local path |

Public URL example:

```json
{"name":"upload_file","arguments":{"file_url":"https://example.com/reference.png","file_name":"reference.png"}}
```

Small-file template, replacing the placeholder with real file bytes:

```json
{"name":"upload_file","arguments":{"base64_data":"BASE64_ENCODED_FILE_BYTES","mime_type":"image/png","file_name":"reference.png"}}
```

Use returned `file_url` in the model's supported `input.image_urls`, `input.video_urls`, or `input.audio_urls`. Public URL uploads normally allow up to 100 MB; the 1 MB limit applies to sign-in base64. Models can impose smaller reference limits.

Remote MCP cannot read a local `file_path`. Some local API-key configurations support trusted-directory uploads, outside this guide's remote workflow. Private-network, localhost, authenticated, and credential-bearing URLs are refused; do not expose local files to bypass restrictions.

Uploaded references typically last 72 hours, distinct from generated results' 24-hour links.

## 11. prepare_upload: a one-time URL for larger local files

For agents able to execute commands on the user's computer, handling local media over 1 MB and up to 95 MB. Available with remote sign-in only.

| Argument | Type | Meaning |
|---|---|---|
| `file_name` | Required string | Actual filename including extension, such as `reference.mp4`; determines the media type |
| `upload_path` | Optional string | Relative storage directory without `..` |

```json
{"name":"prepare_upload","arguments":{"file_name":"reference.mp4"}}
```

The response provides `upload_id`, `upload_url`, `method` (PUT), `command`, `max_bytes`, and `expires_at`. Save the ID and run the supplied command on the user's computer, using the local file the user explicitly provided.

```bash
curl --fail-with-body --silent --show-error \
  --upload-file '/absolute/path/to/reference.mp4' \
  'UPLOAD_URL_FROM_PREPARE_UPLOAD'
```

The URL expires after 15 minutes and works once. No separate API-key upload step is needed. Do not publish the upload URL or put it in public logs. Use `--fail` if the installed curl lacks `--fail-with-body`. This transfers a file; it does not generate or modify media.

Successful output usually contains `file_url`; recover lost output with `get_upload`. Clients unable to run local commands should request a public reference URL instead of claiming to have uploaded a chat attachment.

## 12. get_upload: confirm upload and recover its URL

Required `upload_id`: the actual ID from `prepare_upload`.

```json
{"name":"get_upload","arguments":{"upload_id":"UPLOAD_ID_FROM_RESPONSE"}}
```

| `state` | Action |
|---|---|
| `waiting` | No file received yet; check the deadline and local upload command |
| `uploading` | Transfer in progress; query again later |
| `done` | Read `file_url` and use it as a supported model input |
| `failed` | Explain the upload error and prepare a new URL when appropriate |

Upload-result records last about one hour and are accessible only to the original account. Record expiry does not immediately delete the stored reference. Repeated `prepare_upload` calls do not query an existing transfer.

## Complete workflows

### Generation without references

`check_balance` → `search_models` → `get_model` → prepare `input` → `estimate_cost` → explain the plan and wait for explicit approval → one `generate_image` / `generate_video` / `generate_audio` call → save the task ID → `get_task` → deliver original results.

### Generation with references

Confirm the model accepts that reference type. Use `upload_file` for public URLs or small data. For larger local files use `prepare_upload` → local PUT transfer → `get_upload`. Insert the real `file_url` in the model's required input field, then estimate, obtain approval, and submit. Existing generation result URLs can be used directly as references when supported, without needless download/re-upload.

### Disconnect or uncertain submission

- Known task ID: use `get_task`.
- Lost task ID: use `list_tasks` and identify the task by time, type, model, and other details.
- A network-recovery response requests the same `client_request_id`: retry the identical authorized input with that ID, not a new request identity.
- Confirmed failure and a requested rerun: explain possible new charges, obtain necessary approval, then create a new task.

## Errors and delivery

Tools may return readable text and structured data. Follow `isError: true`, `ok: false`, or error information; receiving a tool response alone does not mean the operation succeeded.

- Invalid input: correct it using `get_model` and the named invalid parameter; estimate again.
- Authentication: help the user reconnect or authorize without sharing credentials in chat.
- Balance or limits: distinguish the account balance from spending limits and let the user decide.
- Broken link: explain retention and the actual error; query the original task when useful. Do not create a paid task merely to refresh a link.
- Blank/gray preview: retain original view/download links. Resource type, retention, or client loading rules can affect display. This guide cannot guarantee embedded thumbnails.

Deliver completion status, actual model, original result links, final returned cost, and expiry information. Keep estimates, reservations, and final charges distinct. If final cost is unavailable, say so.

## Requested downloads: Python request headers

When the user requests a local download and the agent uses Python `urllib`, explicitly set a truthful product User-Agent. A default Python request may receive 403/1010; this does not require generating again or switching download tools first.

```python
from shutil import copyfileobj
from urllib.request import Request, urlopen

# Use the original URL returned by get_task and the user's output path.
request = Request(result_url, headers={"User-Agent": "EvoLinkClient/1.0"})
with urlopen(request, timeout=60) as response:
    with open(output_path, "wb") as output:
        copyfileobj(response, output)
```

Use your application's real name and version, rather than impersonating a browser or curl. Do not send API keys or Authorization headers to media URLs. If a product UA still receives a block, report the error and check URL expiry and the actual blocking rule instead of retrying blindly. Built-in client previews may not allow custom headers and need separate verification. Deliver original links first; downloading is optional rather than a prerequisite for delivery.

This method was verified on the test cloud host for one actual completed image: the same urllib request changed from 403/1010 to 200 with only a product UA, and the full PNG downloaded successfully. Other media, network exits and third-party clients were not thereby verified. See the [official Python Request documentation](https://docs.python.org/3/library/urllib.request.html#urllib.request.Request).

## Further reading

- [MCP overview and client setup](https://evolink.ai/docs/en/mcp/overview)
- [Tools and usage](https://evolink.ai/docs/en/mcp/tools)
- [Billing and limits](https://evolink.ai/docs/en/mcp/billing)
- [Connection troubleshooting](https://evolink.ai/docs/en/mcp/troubleshooting)
- [Model catalog](https://evolink.ai/models)
- [Pricing](https://evolink.ai/pricing)
- [Changelog](https://evolink.ai/changelog)

Before generating, verify current capabilities and prices against the connected tool definitions, `get_model`, and this task's `estimate_cost` response.