# EvoLink MCP 阅读说明

把本文件发送给您的 Agent，即可让它了解 EvoLink MCP 的工具与调用流程。阅读本文件不会安装服务、登录账户或授权付费生成。本文适用于通过浏览器登录的远程 MCP 连接；工具是否可用、参数和模型能力，以当前连接提供的工具定义及 `get_model` 返回为准。

- MCP 服务地址：`https://mcp.evolink.ai/mcp`
- 能力：查找模型、查看参数和价格、估价、生成图片/视频/音乐/语音、上传参考素材、查询和恢复任务。
- 计费单位：credits（积分），约 68 credits = 1 美元。只读查询和上传工具不收生成费用；三个 `generate_*` 工具会产生付费任务。上传仍受文件配额限制。
- 本文的模型、提示词、时长和金额是调用格式示例，不代表用户已经批准执行。实际使用前重新读取模型参数和报价。

## MCP 是什么

MCP（Model Context Protocol）是一套让 Agent 发现和调用外部工具的协议。用户在助手客户端添加 EvoLink MCP 并完成授权后，客户端会提供工具清单和参数定义；Agent 通过这些工具查模型、上传参考素材、估价、提交生成任务并取回结果。MCP 服务本身不是聊天模型，阅读本文也不会自动把服务加入客户端。

本文件是一份可保存、可作为附件发送给 Agent 的独立阅读说明，覆盖远程登录连接的全部 12 个工具。执行时以已连接服务的实时工具定义为准。模型列表、价格、支持参数和账户权限会变化，不应把示例或历史任务当成当前能力。

### 三个在线入口的区别

| 地址 | 用途 | Agent 怎么使用 |
|---|---|---|
| `https://mcp.evolink.ai/mcp` | EvoLink 媒体生成 MCP | 在支持 MCP 的客户端连接并完成浏览器授权，再调用本文介绍的工具 |
| `https://evolink.ai/docs/mcp` | 文档检索 MCP | 连接后搜索、读取 EvoLink 公开文档；这个服务不提供媒体生成工具 |
| `https://evolink.ai/docs/llms.txt` | 给 Agent 阅读的文档目录 | 直接读取纯文本，按其中的链接获取所需文章；不需要安装 MCP 连接 |

`https://docs.evolink.ai/llms.txt` 会跳转到上表的文档目录地址。目录可能把较大的 API 章节拆到 `/_llms/` 子目录文件，Agent 应继续沿链接读取。文档目录和文档检索 MCP 都服务于查资料，不能替代生成服务的连接、授权与费用确认。

## 能力范围

介绍 EvoLink MCP 时，可以说：“我能通过 EvoLink 生成或编辑图片、视频、音乐与语音；查询模型、参数、价格和余额；上传参考素材；查询任务并获取原始结果。”

“处理代码和文件、开发网站、整理数据、制作文档”取决于宿主 Agent 自己的工具，不是 EvoLink MCP 提供的功能。用户问整个助手能做什么时，可另行说明宿主能力，避免把它们归到 EvoLink。MCP 的余额和任务查询也不代表可以管理 API Key、取消任务或修改账户设置。

## 连接与授权

1. 在助手客户端的 MCP 设置中添加 `https://mcp.evolink.ai/mcp`。客户端是否支持远程 HTTP MCP、如何显示工具及是否需要刷新，由客户端决定。
2. 按客户端提示在浏览器登录 EvoLink 并同意连接；不要把 API Key 或访问令牌写进对话或本文。
3. 回到助手，确认 EvoLink 工具可见，再调用 `check_balance` 验证连接。看不到工具时检查连接、登录和客户端加载状态，不要直接提交生成。
4. 远程登录连接提供下面的 12 个工具。本地 API Key 运行方式的工具清单可能不同，例如一次性上传工具是否提供，应以实际清单为准。

连接授权允许助手访问工具，具体任务仍要遵守用户的生成范围和费用授权。账户已有余额、连接成功或上传成功都不能替代本次付费确认。

## 给 Agent 的工作规则

1. 先确认 EvoLink 工具已连接。看不到工具时指导用户完成连接和浏览器授权，再调用 `check_balance` 验证；不要声称读取本文件就完成了接入。
2. 用户要求媒体生成时，先用 `search_models` 找模型，再用 `get_model` 查看参数；不要猜模型 ID、参数名、枚举或默认值。用户明确指定其他平台时遵守用户要求。
3. 需要参考素材时先上传。远程 MCP 读不到用户电脑的路径，不能把 `/Users/...`、`C:\...` 或对话附件的内部地址当作模型可下载的 URL。
4. 对准备提交的同一组参数调用 `estimate_cost`。向用户说明模型、数量、时长/清晰度/声音、预计费用及未知费用，然后结束回复并等待明确确认。Agent 推荐的预算、示例预算和用户笼统的“试一下”不是金额授权。
5. 用户明确批准本次任务或限定批次与预算后才调用 `generate_*`。额外变体、重新生成和改变参数的提交都要有对应授权；不能擅自去掉用户要求的费用上限。
6. 提交成功后保存 `task_id` 和 `client_request_id`，只查询已有任务。完成后立即交付原始结果链接、模型和实际费用；生成请求不自动授权本地剪辑、合成、转码或质量修正。
7. 发现结果不符合要求时先交付并说明问题，让用户决定后续动作。只有明确要求或授权后期处理时才修改素材，并分别标明原始结果和修改后的版本。
8. 默认给出清楚的查看/下载链接。不要把 MP4 或其他非图片地址写成 `![图片](URL)`；不要把客户端是否显示缩略图当作任务是否成功的依据。

用户明确批准的有限批次可以在已批准的范围内继续；遇到超出范围、报价变化或未知费用，应再次确认。上述规则是 Agent 的执行要求，不代表服务端逐笔审批或客户端一定弹出确认框。

## 模型推荐规则

用户指定的模型或平台、任务功能和预算优先。未指定模型时，先查询以下平台优先候选，再用 `get_model` 比较适合该任务的型号：

| 任务 | 优先查询的模型系列 | 选型注意事项 |
|---|---|---|
| 图片、广告图和图片编辑 | GPT Image 2.5 / 2、Seedream 5.0 | 当前 ID 如 `gpt-image-2.5-flare`、`gpt-image-2.5-sunburst`、`gpt-image-2`、`doubao-seedream-5.0-pro`；核对文字、参考图、尺寸和计费方式 |
| 视频 | Seedance 2.5 / 2.0、Wan 3.0 | 按实际素材选文生、图生、参考生或编辑接口；不能把需要草稿任务的型号当普通文生视频 |
| 音乐或歌曲 | Suno v6 | 当前目录中的规范 ID 为 `suno-v6`，以目录实际别名为准 |
| 语音、配音或旁白 | 可用的语音模型 | 按语言、音色和参考声音选型；Suno 的音乐推荐不适用于配音 |

这些是平台推荐偏好，不是经过统计的热度或质量排行榜。逐个查询相关系列，不能只选搜索结果第一项。`search_models` 的 `recommendation` 若提供，`basis: platform_preference` 表示平台偏好，`use_case` 表示适用类别；仍需核对本次任务的功能和费用。关键词相关性优先，推荐偏好只在相关性和有无价格相同的情况下调整顺序。

优先候选不适合功能或预算时，选择其他可用型号并简短说明原因。同等适配时优先合适的非 Beta 接口；选 Beta 要说明理由。未核实的发布时间、可用性、参数和价格不能猜。参数或价格缺失时先核实或说明限制。GPT Image 的 token 单价不能当作每张图片的固定总价；实际提交仍要 `estimate_cost` 并遵守费用确认。

## 怎么读调用示例

下文 JSON 用 `name` 表示 MCP 工具名，`arguments` 表示工具参数，即 MCP `tools/call` 的参数对象。Agent 应使用客户端实际提供的 EvoLink 工具入口；前缀可能不同，不要机械照搬某个客户端的函数名。无需再直接调用平台 HTTP 生成接口。

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

本文不包含凭据。不要让用户在聊天中粘贴 API Key、访问令牌或上传令牌。`TASK_ID_FROM_RESPONSE`、`UPLOAD_ID_FROM_RESPONSE` 等示例值必须替换为工具实际返回的值。调用示例演示参数结构，不代表该模型是默认推荐。

## 工具总览

| 工具 | 主要用途 | 生成费用 |
|---|---|---|
| `search_models` | 找图片、视频或音频模型 | 无 |
| `get_model` | 查看模型输入参数、示例与价格 | 无 |
| `estimate_cost` | 验证输入并估价，不提交任务 | 无 |
| `generate_image` | 生成或编辑图片 | 有 |
| `generate_video` | 生成或编辑视频 | 有 |
| `generate_audio` | 生成音乐、歌曲或语音 | 有 |
| `get_task` | 查询一项任务、等待完成、读取结果 | 无 |
| `list_tasks` | 找最近任务或批量查询任务 | 无 |
| `check_balance` | 查余额、累计用量与额度 | 无 |
| `upload_file` | 上传公开素材链接或小文件数据 | 无 |
| `prepare_upload` | 为较大的本地文件申请一次性上传地址 | 无 |
| `get_upload` | 查询一次性上传状态和文件链接 | 无 |

## 1. search_models：查找模型

| 参数 | 类型 | 用法 |
|---|---|---|
| `type` | 字符串 | `image`、`video`、`audio`、`all`；默认 `all` |
| `query` | 字符串，可选 | 最多 100 字符的关键词，例如 `seedance`、`music` |
| `limit` | 整数 | 1–50，默认 20 |

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

读取返回的 `models[].id`、类型、起始价格和文档链接。起始价格不能当成这次任务的总价。没有匹配时减少关键词或扩大类型，随后用选中的 ID 调用 `get_model`。

## 2. get_model：读取模型参数与价格

必填参数 `model` 是 `search_models` 返回的模型 ID，长度 1–128 字符。

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

重点读取 `type`、`tool`、`required`、`parameters`、`example_input` 和 `prices`。`parameters` 说明参数的类型、必填项、可选值、范围及默认值。例如不同模型可能用 `size` 或 `aspect_ratio`，不能通用替换；支持 `image_urls` 的模型才可传参考图片。

模型特有参数放进生成调用的 `input` 对象；工具级参数如 `max_cost_usd` 放在 `arguments` 顶层。`model` 和 `callback_url` 不要放进 `input`。参数未完整记录或价格不可用时，说明限制，不要编造设置或零费用结论。

## 3. estimate_cost：验证输入并估价

| 参数 | 类型 | 用法 |
|---|---|---|
| `model` | 字符串，必填 | 选中的模型 ID |
| `input` | 对象，可选 | 准备提交给该模型的完整参数；实际生成使用相同参数 |
| `media_seconds` | 数值，可选 | 大于 0、最多 3600 秒；仅用于按输入时长计费且没有 `duration` 参数的模型 |

```json
{"name":"estimate_cost","arguments":{"model":"z-image-turbo","input":{"prompt":"白色背景上的红苹果，柔和自然光","size":"1:1"}}}
```

读取 `input_valid`、`problems`、`warnings` 和 `estimate`。输入存在问题时先改参数再报价。`input_valid: null` 表示没有完整的参数校验资料，不等于输入已通过验证。

`estimate.status` 的处理方式：

| 状态 | Agent 应做什么 |
|---|---|
| `estimated` | 说明返回的价格区间、依据及附加费用提示，再取得用户确认 |
| `partial` | 明确这是部分费用，不能当成总价或最高费用 |
| `needs_input` | 补充必要的时长等信息，重新估价 |
| `token_billed` | 说明需任务运行后才能知道实际费用 |
| 其他状态或无价格 | 明确无法可靠估价，不能自行按 0 元处理 |

公开价格估算与最终计费可能不同，最终以任务结算为准。参考视频、声音、清晰度或其他选项可能影响费用。余额充足不等于用户已授权花费。

`media_seconds` 是估价辅助信息，不会传给模型，也不会决定模型的输出时长。不能用它替代 `input.duration`，不能用它消除参考视频报价不完整的问题。实际连接的工具定义不含此参数时，不要传入。

先核对按秒单价对应的是输入素材时长还是输出成品时长。模型没有 `duration` 参数时，不要为了估价向 `input` 填入该字段。对于运行后才知道输出时长的音频，预计秒数只能帮助说明一个费用示例，不能证明最终总价或最高费用；无法可靠验证用户指定的费用上限时，应说明限制并等待用户决定。

## 三个 generate 工具的共同参数

| 参数 | 类型 | 用法 |
|---|---|---|
| `model` | 字符串，必填 | 与生成类型一致的模型 ID，长度 1–128 字符 |
| `input` | 对象，可选 | `get_model` 列出的模型参数 |
| `prompt` | 字符串，可选 | `input.prompt` 的快捷写法，最多 20000 字符；模型自己的限制仍适用 |
| `client_request_id` | 字符串，可选 | 16–96 字符，仅字母、数字、`.`、`_`、`-`；用于同一请求的网络错误恢复 |
| `max_cost_usd` | 数值，可选 | 大于 0、最多 10000 美元；必须来自用户明确批准的预算 |
| `media_seconds` | 数值，可选 | 与 `estimate_cost` 相同的估价辅助参数，仅在工具定义支持时使用 |

推荐把提示词只写在 `input.prompt`；顶层 `prompt` 与 `input.prompt` 内容冲突时会拒绝。`max_cost_usd` 是基于估价的提交检查，不是最终结算价格保证。当前工具定义要求总价估算完整时，带参考视频的部分报价、按 token 计费或无法报价的请求可能不能使用该参数；遇到拒绝时告知原因，不要自动删掉上限继续提交。

`client_request_id` 对应一项已授权的逻辑请求。只有在同一请求的网络错误或超时恢复中复用同一个值；改变参数或新增变体需要新的请求 ID 和相应授权。已有 `task_id` 时优先用 `get_task`，不要再次提交。

## 4. generate_image：生成或编辑图片

付费调用。先读取图片模型的参数、对相同输入报价并取得确认，再提交：

```json
{"name":"generate_image","arguments":{"model":"z-image-turbo","input":{"prompt":"白色背景上的红苹果，柔和自然光","size":"1:1"},"client_request_id":"image-apple-demo-001"}}
```

`z-image-turbo` 和示例设置只用于说明格式，执行前仍需查询和确认。编辑图片应选支持编辑/参考输入的模型，并按其定义传入参考地址，不能假设本例模型支持 `image_urls`。

工具通常等待图片结果，最多约 40 秒。如果返回的任务仍在运行，保存 `task_id` 并调用 `get_task`；不要再调 `generate_image` 来刷新。

## 5. generate_video：生成或编辑视频

付费调用。文生视频示例：

```json
{"name":"generate_video","arguments":{"model":"seedance-2.0-mini-text-to-video","input":{"prompt":"一只小猫走过草地，镜头缓慢前移，自然光","duration":8,"quality":"720p","aspect_ratio":"16:9","generate_audio":true,"content_filter":true},"client_request_id":"video-cat-demo-001"}}
```

图生视频、参考生视频、延长、编辑等功能由具体模型决定。按 `get_model` 的定义使用 `image_urls`、`video_urls`、`video_url` 或 `source_task_id`；不要照搬另一模型的输入字段。注意时长、清晰度、声音和参考素材的组合限制及费用。

视频通常立即返回 `task_id`，再用 `get_task` 等待。完成后直接给用户原始视频链接；生成请求不授权 Agent 自动拼接音轨、覆盖画面或本地修正。

## 6. generate_audio：生成音乐、歌曲或语音

付费调用。先按用户意图搜索 `audio` 模型，再读取该模型的示例与参数。语音示例：

```json
{"name":"generate_audio","arguments":{"model":"doubao-seed-audio-1-0","input":{"prompt":"欢迎使用 EvoLink，今天的天气真好。","format":"mp3"},"client_request_id":"audio-speech-demo-001"}}
```

音乐示例（简单模式，由模型生成歌词和风格）：

```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"}}
```

示例不是执行授权。音乐模型可能接受音乐描述、歌词或模式，语音模型可能接受文本、语言和声音参数；字段名以具体模型为准，不能一律使用 `prompt`。例如 Suno 的简单模式与自定义模式支持不同字段，Seed-Audio 的音频参考和图片参考不能同时使用。输入准备好后先估价、取得确认，再提交。

返回任务 ID 后使用 `get_task`。一项音乐任务可能含多首歌曲或多个音频/封面结果，应交付全部相关链接，不额外收费生成“补齐”结果。

## 7. get_task：查询进度与结果

| 参数 | 类型 | 用法 |
|---|---|---|
| `task_id` | 字符串，必填 | 生成工具返回的 ID，原样保存和使用 |
| `wait_seconds` | 整数 | 0–45，默认 30；0 表示立即查询 |

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

读取 `status`、`progress`、结果链接和费用。常见处理中状态包括 `pending`、`processing`；终态为 `completed`、`failed`、`cancelled`，以实际返回为准。

- 仍在运行：继续调用同一 ID 的 `get_task`，适当给用户进度；不要紧密循环 `wait_seconds: 0`。
- `completed`：立即交付结果、模型及最终费用。结果链接通常 24 小时后失效，提醒及时保存。
- `failed` / `cancelled`：说明返回的原因与费用信息，是否重新提交由用户决定。
- 单次查询超时：不能据此认定生成失败；继续查询原任务或用 `list_tasks` 恢复。

若返回提供 `delivery_markdown` 或结果资源链接，可直接使用其中的原始结果入口；仍需保留可点击的查看/下载链接。客户端可能不能内嵌媒体，不自动构造远程图片预览。

服务也可能随结果直接返回小尺寸图片内容块，供客户端显示图片缩略图或视频首帧；这些预览不是原始文件。优先使用工具已返回的内容和原始链接，不为做封面再次生成，也不因预览失败而修改、重编码或重新提交原任务。Logo、工具图标及预览的显示位置由客户端决定。

## 8. list_tasks：找回最近任务或批量查询

| 参数 | 类型 | 用法 |
|---|---|---|
| `task_ids` | 字符串数组，可选 | 1–50 个已知任务 ID，直接批量查询 |
| `status` | 字符串，可选 | `processing`、`completed`、`failed`、`cancelled`；仅用于最近任务查询 |
| `type` | 字符串，可选 | `image`、`video`、`audio`；仅用于最近任务查询 |
| `since` | 字符串，可选 | ISO 8601、Unix 秒时间戳或 `30m`、`2h`、`1d` 等，最多 40 字符 |
| `limit` | 整数 | 1–50，默认 20；用于最近任务查询 |

```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"]}}
```

传 `task_ids` 时按这些 ID 查询，其他筛选条件不生效。最近任务覆盖整个 EvoLink 账户，按时间从新到旧排列；不是当前对话的专属列表。根据模型、时间和任务信息确认要恢复的是哪一项，有歧义就请用户选择。

`processing` 筛选包含排队中的任务。`since` 对当前获取的一页最近任务进行筛选，不是扫描全部历史；找不到不等于从未提交成功。批量结果可能含 `missing`，请检查 ID、账户或有效期。

## 9. check_balance：查询余额和额度

无参数：

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

读取 `account_balance_credits`、美元换算、`spent_scope`、累计花费及额度信息。登录连接的 MCP 用量和额度覆盖该账户所有通过登录连接的助手，不是单个窗口、会话或本次任务的用量。

账户余额、MCP 额度和每日额度是不同限制。余额不足或额度不足时把原因告诉用户；不要自动充值、改额度、换凭据或绕过限制。

## 10. upload_file：公开链接或小文件上传

远程登录连接在 `file_url` 与 `base64_data` 中选且只选一种来源。

| 参数 | 类型 | 用法 |
|---|---|---|
| `file_url` | 字符串，可选 | 不含凭据、无需登录即可下载的公开 HTTPS 媒体链接 |
| `base64_data` | 字符串，可选 | 小文件的原始 base64 或 Data URL；登录方式解码后最多 1 MB |
| `mime_type` | 字符串，可选 | 原始 base64 必填；Data URL 已含类型时必须与其一致 |
| `file_name` | 字符串，可选 | 普通文件名，不含目录分隔符 |
| `upload_path` | 字符串，可选 | 存储中的相对目录，不含 `..`，不是本机路径 |

公开链接上传：

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

本地小文件的数据模板（占位值须替换为真实文件内容）：

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

读取返回的 `file_url`，按模型要求填入 `input.image_urls`、`input.video_urls` 或 `input.audio_urls`。公开 URL 上传的文件上限通常为 100 MB；1 MB 限制指登录方式的 base64 数据。模型自身还可能有更小的素材限制。

远程 MCP 没有可读取用户电脑的 `file_path`。部分本地 API Key 运行方式另有受信目录上传能力，不适用于本说明的远程连接。拒绝私网、localhost、需要认证或带凭据的地址；不要通过暴露本地文件来绕过。

上传文件通常保留 72 小时；不要把上传文件有效期和生成结果的 24 小时有效期混淆。

## 11. prepare_upload：较大本地文件的一次性上传

用于能执行本机命令的 Agent；适合超过 1 MB、最多 95 MB 的本地媒体。仅远程登录连接提供。

| 参数 | 类型 | 用法 |
|---|---|---|
| `file_name` | 字符串，必填 | 含真实扩展名，例如 `reference.mp4`；用于确定文件类型 |
| `upload_path` | 字符串，可选 | 相对存储目录，不含 `..` |

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

返回 `upload_id`、`upload_url`、`method`（PUT）、`command`、`max_bytes` 和 `expires_at`。保存 ID；把命令中的文件位置换成用户明确提供的本地文件，然后在用户电脑执行。

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

上传地址 15 分钟内有效，只能使用一次。没有独立 API Key 上传步骤；不要把上传地址公开发布或记录到公共日志。若本机 curl 不支持 `--fail-with-body`，可使用 `--fail`。这是文件传输，不是生成或后期修改。

成功响应通常包含 `file_url`；输出丢失时用 `get_upload` 恢复。不能执行本机命令的客户端应请用户提供公开素材链接，而不是声称已经上传对话附件。

## 12. get_upload：确认上传并读取文件链接

必填参数 `upload_id` 使用 `prepare_upload` 实际返回的 ID。

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

| `state` | 下一步 |
|---|---|
| `waiting` | 文件还没有上传；核对地址期限及本机上传命令 |
| `uploading` | 文件正在传输，稍后再次查询 |
| `done` | 读取 `file_url`，再用于模型输入 |
| `failed` | 告知上传错误，按用户意图准备新的上传地址 |

上传结果记录保留约 1 小时，且只允许原账户查询；记录过期不等于已存储的素材立刻被删除。大文件传输不能靠重复调用 `prepare_upload` 来查询进度。

## 完整调用顺序

### 无参考素材的生成

`check_balance` → `search_models` → `get_model` → 准备 `input` → `estimate_cost` → 展示方案与费用并等待用户明确确认 → `generate_image` / `generate_video` / `generate_audio` → 保存任务 ID → `get_task` → 交付原始结果。

### 有参考素材的生成

先确认模型接受该类参考素材。公开链接或小文件用 `upload_file`；较大的本地文件用 `prepare_upload` → 本机 PUT 上传 → `get_upload`。拿到实际 `file_url` 后放入模型要求的输入字段，再按完整生成流程报价、确认和提交。生成结果也可直接用作支持该输入的后续模型的参考，不必无意义地下载再上传。

### 断线或提交结果不明

- 已有任务 ID：直接 `get_task`。
- 丢失任务 ID：`list_tasks` 按最近时间和类型查找，再核对模型等信息。
- 收到要求复用 `client_request_id` 的网络恢复说明：对同一组已授权参数复用原 ID，不建立新的请求身份。
- 明确失败且想重新生成：先说明是否产生新费用，取得必要确认后再新建任务。

## 错误与结果交付

工具可能同时提供可读文字和结构化结果。返回 `isError: true`、`ok: false` 或错误信息时，按实际说明处理；不能把仅有工具返回当成成功。

- 参数错误：按 `get_model` 与错误中的参数名修正，再估价。
- 认证问题：指导用户重新连接或授权，不要求在聊天中提交凭据。
- 额度或余额不足：区分账户余额和额度，交给用户决定。
- 链接打不开：说明有效期和实际错误，必要时查询原任务；不要为换链接自动生成一次新任务。
- 预览空白或灰色：先保留原始查看/下载入口。客户端媒体显示可能受资源类型、链接期限或自身加载规则影响，不能保证本文件会让客户端显示缩略图。

建议交付：任务是否完成、实际模型、可用的原始结果链接、返回的最终费用和有效期。不要把估价、预扣与最终扣费混为同一件事；实际费用未返回时明确标注未知。

## 按需下载：Python 请求头

用户要求保存到本地、且 Agent 使用 Python `urllib` 下载原文件时，显式设置真实的产品 User-Agent。默认 Python 请求可能收到 403/1010；无需为此重新生成，也不必先改用其他下载工具。

```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)
```

产品应使用自己的真实名称和版本，不要伪装浏览器或 curl。下载媒体链接时不附加 API Key 或 Authorization。明确设置请求头后仍被拦截，要报告错误、核对链接有效期与实际拦截规则，不盲目重试。客户端内置预览可能不能设置请求头，需单独验证。先交付原始结果链接；下载是按需动作，不是生成结果交付的前置步骤。

以上方式已在测试云机对一张真实完成图片验证：同一 urllib 默认请求为 403/1010，仅加产品 UA 后 200，完整 PNG 下载通过；不表示所有视频、音频、出口或第三方客户端都已验证。[Python Request 官方说明](https://docs.python.org/3/library/urllib.request.html#urllib.request.Request)。

## 进一步查询

- [MCP 概述与客户端接入](https://evolink.ai/docs/cn/mcp/overview)
- [工具与用法](https://evolink.ai/docs/cn/mcp/tools)
- [费用与额度](https://evolink.ai/docs/cn/mcp/billing)
- [排查连接问题](https://evolink.ai/docs/cn/mcp/troubleshooting)
- [模型目录](https://evolink.ai/models)
- [价格](https://evolink.ai/pricing)
- [更新日志](https://evolink.ai/changelog)

生成前始终以已连接服务的工具定义、`get_model` 与本次 `estimate_cost` 返回核对最新能力和价格。