# Use SeedRouter from AI Agents

An agent can use SeedRouter in three ways. They share the same API key, balance, models and limits, and they are billed the same.

| Way                         | Best for                                                  | Setup                                                                                                                     |
| --------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| [MCP server](https://seedrouter.ai/docs/api/mcp) | Claude Code, Cursor, Codex, VS Code and other MCP clients | Add `https://api.seedrouter.ai/v1/mcp` with your API key as a Bearer header                                               |
| Agent skill                 | Agents that load Agent Skills                             | The skill index is at [`/.well-known/agent-skills/index.json`](https://seedrouter.ai/.well-known/agent-skills/index.json) |
| HTTP API                    | Your own code, or an agent writing code for you           | [Quickstart](https://seedrouter.ai/docs/api/quickstart)                                                                                        |

To run the agent itself on SeedRouter's text models instead, see [Coding agents on SeedRouter](https://seedrouter.ai/docs/api/coding-agents).

## Set your key once

Create a key on the [API keys page](https://seedrouter.ai/apikeys) and export it, so the agent can read it without the key landing in your project files:

```bash
export SEEDROUTER_API_KEY=YOUR_API_KEY
```

The API keys page also has a **Connect via MCP** button that prints a ready setup for each MCP client.

## What an agent does on SeedRouter

1. **Find a model**: `list_models` over MCP, or the model list in [`/llms.txt`](https://seedrouter.ai/llms.txt). Each model with a landing page has a plain-text summary at `https://seedrouter.ai/models/<slug>/llms.txt` with its parameters, prices and examples.
2. **Read its input schema**: `get_model_schema` over MCP, or the model's documentation page.
3. **Use public media URLs**: generation endpoints accept reference images, videos and audio only as public `http(s)` URLs. Base64 input is rejected, so host local files somewhere reachable first.
4. **Check the price**: `get_pricing` over MCP returns the model's current rates in USD before anything is submitted.
5. **Submit and wait**: `submit_task`, then `get_task` with `wait_seconds: 50` until the task finishes. Over HTTP, submit to the model's endpoint and poll [`GET /v1/tasks/{id}`](https://seedrouter.ai/docs/api/tasks) about every three seconds.

Failed tasks are not charged. A submission is not idempotent: retrying a request whose response you did not receive creates and charges a second task, so check your [task history](https://seedrouter.ai/tasks) or balance first.

## Limits to plan around

| Limit                                                  | Default | Response when exceeded   |
| ------------------------------------------------------ | ------- | ------------------------ |
| Image and video tasks in progress at once, per account | 50      | HTTP `429`, code `30002` |

Requests can also be rate limited, which returns HTTP `429` as well. On HTTP `429`, wait for `Retry-After` when it is present; otherwise back off exponentially with jitter and a cap. Base the decision on the status code rather than parsing error bodies, because the text endpoints answer in the error format of their protocol. A batch job should keep a queue and submit new tasks as running ones finish, rather than sending everything at once. Contact [support@seedrouter.ai](mailto:support@seedrouter.ai) if you need a higher limit.

## Machine-readable entry points

| URL                                                                                                 | What it is                                                                                                            |
| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| [`/llms.txt`](https://seedrouter.ai/llms.txt)                                                       | Index of models, documentation and guides for language models                                                         |
| `/models/<slug>/llms.txt`                                                                           | One model's parameters, prices and examples                                                                           |
| `/docs/<page>.md`                                                                                   | Any documentation page as Markdown, for example [`/docs/api/overview.md`](https://seedrouter.ai/docs/api/overview.md) |
| [`/.well-known/agent-skills/index.json`](https://seedrouter.ai/.well-known/agent-skills/index.json) | Agent skill index                                                                                                     |
| [`/.well-known/api-catalog`](https://seedrouter.ai/.well-known/api-catalog)                         | API catalog (RFC 9727)                                                                                                |
| `https://api.seedrouter.ai/v1/mcp`                                                                  | [MCP server](https://seedrouter.ai/docs/api/mcp)                                                                                           |