> ## Documentation Index
> Fetch the complete documentation index at: https://evolink.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tool and API reference

> Parameters, examples, results, protocol, and backend mapping for 15 tools

<span id="mcp-tools" />

## MCP tool reference

This page describes the 15 tools in the **1.6.1** OAuth remote MCP release. The connected server's `tools/list` is authoritative. Local stdio does not expose `prepare_upload` or `get_upload`; its `upload_file` also accepts paths within explicitly allowed directories.

The `name` and `arguments` examples describe MCP tool calls, not REST request bodies. An example does not authorize a paid generation.

| Tool | Purpose | Generation charge |
| - | - | - |
| search\_models | Search available models and aliases | None |
| recommend\_models | Compare models matching the request and reference types | None |
| search\_docs | Search the versioned official model-reference index | None |
| get\_model | Inspect parameters, schema, references, and pricing | None |
| estimate\_cost | Validate inputs and estimate cost | None |
| generate\_image | Generate or edit images | Paid |
| generate\_video | Generate, edit, or extend video | Paid |
| generate\_audio | Generate music, songs, or speech | Paid |
| get\_task | Inspect a task, results, and reported cost | None |
| list\_tasks | Query IDs or paginated account history | None |
| get\_task\_usage | Summarize reported costs within a bounded scan | None |
| check\_balance | Inspect account balance and shared limits | None |
| upload\_file | Upload a URL or base64 reference | No generation charge; file quotas apply |
| prepare\_upload | Prepare a one-use upload for a local file | No generation charge; file quotas apply |
| get\_upload | Recover an existing upload's status and URL | None |

### search\_models

| Parameter | Type | Required | Default / range |
| - | - | - | - |
| type | string | No | image/video/audio/all; default all |
| query | string | No | Search keywords, up to 100 characters |
| limit | integer | No | 1–50; default 20 |
| page | integer | No | 1–100000; default 1 |

```json theme={null}
{"name":"search_models","arguments":{"type":"image","query":"seedream","limit":5,"page":1}}
```

Returns models, total\_matches, page, page\_size, and next\_page. Entries include canonical IDs, aliases, references, documentation coverage, and starting prices. Ordering considers keyword relevance first, then price availability, editorial preference, and ID. It is not a quality or popularity ranking. Starting prices are not task totals, and availability can change between pages.

### recommend\_models

| Parameter | Type | Required | Default / range |
| - | - | - | - |
| type | string | Yes | image/video/audio |
| query | string | No | Up to 100 characters; all search terms must match |
| references | string\[] | No | image/video/audio; at most 3 entries; default empty |
| limit | integer | No | 1–10; default 3 |

```json theme={null}
{"name":"recommend_models","arguments":{"type":"video","query":"seedance","references":["image"],"limit":3}}
```

Returns documented candidates with reasons, reference\_inputs, selection\_basis, and unit pricing. Required reference types must have documented input fields. If no model matches, adjust the request transparently rather than dropping a necessary reference. Editorial preferences are not live popularity or release-date statistics.

### search\_docs

| Parameter | Type | Required | Default / range |
| - | - | - | - |
| query | string | Yes | 1–100 characters after trimming |
| type | string | No | image/video/audio/all; default all |
| limit | integer | No | 1–20; default 5 |

```json theme={null}
{"name":"search_docs","arguments":{"query":"first frame","type":"video","limit":5}}
```

Returns documents, total\_matches, scope, and source version. It searches bundled official model titles, IDs, and parameter descriptions for available models. It does not crawl the live documentation site or search account and billing documentation.

### get\_model

Required `model`: a string of 1–128 characters, using a returned canonical ID or supported alias.

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

Returns the canonical model, requirements, examples, public pricing, reference\_inputs, parameters\_source, and, when available, input\_schema with its source. Parameter references are versioned; account availability is queried live. Follow missing-information warnings rather than inventing defaults.

### estimate\_cost

| Parameter | Type | Required | Description |
| - | - | - | - |
| model | string | Yes | 1–128 characters |
| input | object | No | Planned model parameters; defaults to an empty object |
| media\_seconds | number | No | Greater than 0 and at most 3600; estimation hint only |

```json theme={null}
{"name":"estimate_cost","arguments":{"model":"z-image-turbo","input":{"prompt":"A cream ceramic coffee cup on a white background"}}}
```

Returns input\_valid, problems, warnings, estimate, pricing\_scope, final\_budget\_enforced, and balance/limits when available. The estimate status can be estimated, partial, token\_billed, needs\_input, or no\_price; see [billing](/docs/en/mcp/billing). A successful query does not prove valid input or a complete quote.

This tool has no `max_cost_usd` argument and does not produce the CLI's local quote\_id. MCP budget checks belong to generation tools. media\_seconds does not set output duration or fill unknown reference-video multipliers.

### generate\_image, generate\_video, generate\_audio

Choose the tool matching the output type. They share these top-level arguments:

| Parameter | Type | Required | Description |
| - | - | - | - |
| model | string | Yes | 1–128 characters; must match the media type |
| input | object | No | Parameters from get\_model; do not include model or callback\_url |
| prompt | string | No | Shortcut for input.prompt; up to 20000 characters, subject to model limits |
| client\_request\_id | string | No | 16–96 characters: letters, digits, . \_ -; reuse when recovering the same request |
| max\_cost\_usd | number | No | Greater than 0 and at most 10000; submission-time estimate check |
| media\_seconds | number | No | Greater than 0 and at most 3600; estimation hint only |

Inspect the model and inputs, estimate the complete request, disclose limitations, and obtain explicit cost approval before calling. This is an illustrative call shape:

```json theme={null}
{"name":"generate_image","arguments":{"model":"z-image-turbo","input":{"prompt":"A cream ceramic coffee cup on a white background"},"client_request_id":"coffee-image-demo-001"}}
```

Image generation waits for up to approximately 40 seconds, returning results if ready or a task\_id otherwise. Video and audio return a task\_id after submission; continue with get\_task. Submission can report a precharge, which must be distinguished from completed-task cost.

Query a running task rather than calling generation again to check progress. If the response is lost, retain the original ID, account, inputs, and request identifier. A different identifier creates a new paid intent. Client recovery protections do not prove identical backend idempotency guarantees across all production nodes.

### get\_task

| Parameter | Type | Required | Default / range |
| - | - | - | - |
| task\_id | string | Yes | Original supported task ID; 4–128 characters |
| wait\_seconds | integer | No | 0–45; default 30; 0 queries immediately |

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

Returns status, progress, results, reported cost, or error. Continue querying the same ID while it runs. Task failure does not prove a refund; report unknown settlement when evidence is absent. Original results are generally retained for 24 hours. Preview rendering depends on the host client.

### list\_tasks

| Parameter | Type | Required | Default / range |
| - | - | - | - |
| task\_ids | string\[] | No | 1–50 IDs; batch mode |
| status | string | No | processing/completed/failed/cancelled |
| type | string | No | image/video/audio |
| model | string | No | Exact model ID; 1–128 characters |
| page | integer | No | 1–100000; default 1 |
| since / until | string | No | ISO 8601, Unix seconds, or 30m/2h/1d; up to 40 characters |
| limit | integer | No | 1–50; default 20 |

```json theme={null}
{"name":"list_tasks","arguments":{"type":"video","since":"2h","page":1,"limit":20}}
```

```json theme={null}
{"name":"list_tasks","arguments":{"task_ids":["TASK_ID_ONE","TASK_ID_TWO"]}}
```

task\_ids cannot be combined with status/type/model/page/since/until. Batch mode returns tasks and missing; history returns total/page/page\_size/next\_page. processing includes queued tasks. Time filters apply to the selected page; total is counted before time filtering. History is account-wide, not limited to this conversation. An empty page does not prove that submission never happened.

### get\_task\_usage

| Parameter | Type | Required | Default / range |
| - | - | - | - |
| since | string | No | Default 30d; lower creation-time bound |
| until | string | No | Default current time; inclusive boundary |
| model | string | No | Exact ID; 1–128 characters |
| type | string | No | image/video/audio |
| max\_pages | integer | No | 1–20; default 5; 50 tasks per page |

```json theme={null}
{"name":"get_task_usage","arguments":{"since":"7d","type":"video","max_pages":5}}
```

Returns totals, by\_model, by\_status, coverage, and as\_of. Inspect missing\_cost\_tasks, truncated, concurrent\_change\_detected, and complete\_for\_retained\_tasks. It summarizes reported costs for retained completed account tasks. It is not a complete invoice, payment/refund ledger, MCP-only usage report, or settlement limit.

### check\_balance

No arguments:

```json theme={null}
{"name":"check_balance","arguments":{}}
```

Returns account\_balance\_credits/usd, spent\_scope, spent\_credits, and available total/daily limits with console links. OAuth Key spending includes the account's CLI and all OAuth MCP sessions, rather than only this conversation.

### upload\_file

| Parameter | Type | Required | Description |
| - | - | - | - |
| file\_url | string | One source required | Public HTTPS media; no private-network or credential URLs |
| base64\_data | string | One source required | At most 1 MiB decoded in remote mode |
| mime\_type | string | Conditional | Required for raw base64; data URLs contain MIME |
| file\_name | string | No | Plain filename, without directories |
| upload\_path | string | No | Relative directory, without .. |

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

Replace the URL with actual accessible media. Returns file\_url, file properties, and expiration information. References are generally retained for 72 hours. Remote MCP cannot accept file\_path. Local stdio can instead use an absolute path in an allowed directory; choose exactly one source. Successful upload does not prove that the selected model supports the media.

### prepare\_upload

Required `file_name`: string with an extension used to determine media type. Optional `upload_path`: relative directory.

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

Returns upload\_id, upload\_url, method:PUT, command, max\_bytes, and expires\_at. The URL lasts approximately 15 minutes, is single-use, and accepts at most **95 MiB**. Run the returned command where the file can actually be read, then use the confirmed file\_url. A browser attachment may not be accessible this way. The address contains temporary authorization; do not publish it or append a personal Key.

### get\_upload

Required `upload_id`, from the original prepare result:

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

States include waiting/uploading/done/failed/expired/outcome\_unknown. Use file\_url only after a confirmed done result. Server-local state lasts about one hour; compatible file services can provide receipts for approximately 72 hours. Unsupported or unverifiable receipts can yield outcome\_unknown. Querying does not upload the file again; retain the original ID and inspect status first.

### Results and errors

Tools return readable text and structuredContent; failures can include isError/error/next\_step. Completed media can include resource\_link and an optional image thumbnail. Hosts differ in content-block support. The original URL remains the delivery reference; previews are not guaranteed in every host.

Check tool errors and business fields such as input\_valid, estimate status, and task.status. HTTP 200 alone does not establish generation success. Submission timeout may follow task creation and is not proof of no charge. A failed query is not proof that the original task failed.

## Task progress and results

Use balance and model queries for free connection verification. Use get\_task/list\_tasks for existing tasks, then deliver original URLs and reported actual costs. The [workflow guide](/docs/en/mcp/overview#workflows) covers references, recovery, saving, and gray previews. A display problem must not trigger another paid generation.

<span id="api" />

## MCP protocol and backend APIs

| Mode | Execution path | Authentication and installation |
| - | - | - |
| Remote MCP | Client → hosted EvoLink MCP → platform API | Streamable HTTP and browser OAuth; no local server installation |
| Local stdio | Client → local MCP process → platform API | Node.js 18+, npx startup, and a personal API Key |

The remote endpoint is `https://mcp.evolink.ai/mcp`. Passport provides OAuth; the server requests [https://api.evolink.ai](https://api.evolink.ai) and the file service. MCP URLs, platform /v1 routes, documentation, and llms.txt are separate entry points.

### Initialize and call tools

Let the host or MCP SDK handle initialize, protocol versions, Accept, authentication, sessions, and content blocks. Read tools/list after initialization, then call tools/call:

```json theme={null}
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_balance","arguments":{}}}
```

Examples using name / arguments describe tool input, not REST request bodies. Tools can return text, structured data, resource links, and thumbnails; display depends on the host. Check tool errors and task status, not just HTTP success.

### Tools and backend operations

| MCP tool | Backend operation or implementation |
| - | - |
| search\_models | `GET /v1/models` plus aliases, availability, and references |
| get\_model, recommend\_models, search\_docs | Versioned references and account catalog, not same-name REST routes |
| estimate\_cost | `GET /web/api/models/pricing` and server-side estimation rules |
| generate\_image | `POST /v1/images/generations` |
| generate\_video | `POST /v1/videos/generations` |
| generate\_audio | `POST /v1/audios/generations` |
| get\_task | `GET /v1/tasks/{task_id}` |
| list\_tasks with task\_ids | `POST /v1/tasks/batch` |
| list\_tasks, get\_task\_usage | `GET /v1/tasks`, pagination, and bounded aggregation |
| check\_balance | `GET /v1/credits` |
| Upload authorization | `POST /v1/files/upload-token` |
| upload\_file | File service /url or /base64; local stdio can read allowed directories |
| prepare\_upload, get\_upload | Hosted single-use PUT URL and status; receipt recovery depends on file-service support |

Model parameters belong in arguments.input and are converted to REST requests by the server. media\_seconds is a billing hint; max\_cost\_usd only checks estimates before submission. Published 1.6.1 has no final settlement cap and does not automatically consume complete account quotes merely because new pricing APIs exist.

### Uploads, recovery, and access

Use a prepare\_upload PUT URL only in an environment that can read the file, then query get\_upload. A remote server cannot read desktop paths, and chat attachments may not expose original bytes. See [reference uploads](/docs/en/mcp/overview#files).

Save client\_request\_id, normalized inputs, account identity, and returned task\_id for paid submissions. Query the original task and history when the outcome is unknown; do not change identifiers to resubmit. Client identifiers alone cannot guarantee uniform backend protection against every duplicate charge.

OAuth exposes limited media operations, not arbitrary Key management or administrative APIs. No usable cancellation tool is currently provided; stopping a wait does not cancel the task. CLI commands and execution are documented separately in the [CLI reference](/docs/en/cli/reference#api).

<span id="cli-reference" />

## CLI command documentation

The complete CLI reference is now in the [separate CLI section](/docs/en/cli/reference#cli-reference). This page documents MCP tools and protocol.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.