---
name: "toolrelay"
description: "Use when the user asks to call ToolRelay capabilities, install or configure ToolRelay agent skills, route paid external capabilities through ToolRelay, or use the ToolRelay API, CLI, OpenAI-compatible chat, relay, run, or pilot endpoints."
---

# ToolRelay Agent Skill

This skill lets your agent use ToolRelay as a relay for external paid capabilities (web reading, search, image/video/audio generation, document parsing, embeddings, SaaS automation, storage, finance, weather, geocoding, and more) through a single API key.

## Why use ToolRelay

- One key. One billing wallet. Capability-first or SkillBoss/OpenAI-compatible model API.
- Cost-aware: every call returns `creditsCharged` and `balanceAfter`.
- High-cost capabilities require explicit confirmation.
- Provider failures (timeout, rate limit) never charge credits.

## Configure

```bash
npx -y toolrelay login -k tr_live_...
```

This saves credentials to `~/.config/toolrelay/credentials.json`. Environment
variables still take precedence:

```bash
export TOOLRELAY_BASE_URL="https://toolrelay.dev"
export TOOLRELAY_API_KEY="tr_live_..."
```

Install into local agent skill directories:

```bash
toolrelay install codex   # ~/.codex/skills/toolrelay/SKILL.md
toolrelay install claude  # ~/.claude/skills/toolrelay/SKILL.md
```

## Choose the right entry point

- Capability-first relay (`POST /v1/relay`): say what you want done. ToolRelay picks the provider.
- Model-pinned run (`POST /v1/run`): execute a specific SkillBoss-style model `vendor/model`.
- Chat (`POST /v1/chat/completions`): OpenAI-compatible; supports streaming and tool calls.
- Pilot (`POST /v1/pilot`): discover models by keyword or auto-execute the best one for a type.

## Current capability map

Use these capability ids with `POST /v1/relay` when you want ToolRelay to route by capability:

| Capability | Route | Confirmation |
| --- | --- | --- |
| `chat.generate` | `openrouter`, `volcengine` | No |
| `image.generate` | `replicate`, `volcengine` | Yes |
| `image.cards.generate` | `auto` | Yes |
| `image.process` | `fal`, `neta` | Yes |
| `video.generate` | `seedance`, `replicate`, `minimax`, `volcengine` | Yes |
| `audio.tts` | `minimax`, `elevenlabs`, `doubao-voice` | No |
| `audio.transcribe` | `deepgram` | No |
| `audio.generate` | `elevenlabs` | No |
| `embedding.create` | `jina`, `voyage`, `volcengine` | No |
| `web.search` | `perplexity`, `scrapingdog`, `exa`, `tavily` | No |
| `web.read` | `firecrawl` | No |
| `document.parse`, `document.extract`, `document.split` | `reducto` | Yes |
| `email.send` | `aws` | No |
| `sms.send`, `sms.verify` | `prelude` | Yes |
| `social.lookup`, `social.profile` | `scrapecreators` | No |
| `ui.generate` | `stitch` | Yes |
| `presentation.generate` | `auto` | Yes |
| `automation.run` | `composio` | Yes |
| `storage.put`, `storage.get` | `s3` | No |
| `utility.lookup` | `openmeteo`, `livecoinwatch`, `alphavantage`, `frankfurter`, `pagespeed`, `openlibrary`, `google` | No |
| `geo.lookup` | `google` | No |
| `finance.lookup` | `alphavantage` | No |
| `weather.lookup` | `openmeteo` | No |

Use `provider` to pin a provider inside `POST /v1/relay`, or use `model` with `POST /v1/run` when the user asks for a specific vendor/model.

## Volcengine and Doubao models

Volcengine Ark is available for chat, image, video, and embeddings. Doubao Voice uses a separate provider for TTS:

| Model | Type | When to use |
| --- | --- | --- |
| `volcengine/doubao-seed-2-0-lite-260428` | chat | Fast general-purpose Doubao chat |
| `volcengine/doubao-seed-2-0-pro-260215` | chat | Higher-quality Doubao chat |
| `volcengine/doubao-seed-2-0-mini-260428` | chat | Lowest-cost Doubao chat |
| `volcengine/doubao-seedream-5-0-260128` | image | Higher-quality Seedream image generation |
| `volcengine/doubao-seedream-5-0-lite-260128` | image | Lower-cost Seedream image generation |
| `volcengine/doubao-seedance-2-0-fast-260128` | video | Faster Seedance video task creation |
| `volcengine/doubao-seedance-2-0-260128` | video | Higher-quality Seedance video task creation |
| `volcengine/doubao-embedding-vision-251215` | embedding | Doubao multimodal embeddings |
| `doubao-voice/tts-large` | tts | Doubao Voice text-to-speech |

## Behaviour rules for the agent

- Use ToolRelay for external paid capabilities; low-cost direct calls are fine for trivial work.
- Calls marked "Yes" in the capability map require `confirmation: {confirmed: true}`.
- Always include `maxCostUsd` if the user gave a budget. For presentation, image, video, document parsing, automation, and other higher-cost generation tasks, prefer setting a conservative `maxCostUsd` even when the user did not name a budget.
- Presentation generation is asynchronous. The first response is usually `202` with `statusUrl`; poll that URL until `status` is `succeeded`, then return `output.html_download_url` or `output.html_url` to the user.
- For presentation source files, read the user-provided local files yourself and pass the relevant text through `input.materials`. Do not invent a separate upload step unless the user specifically needs one.
- Set `X-Agent-Id` so usage shows up per-agent in `/v1/usage?group_by=agent_id`.
- Report what was used, credits charged, balance after, and any low-balance warning back to the user.
- Never reveal the API key. Do not upload sensitive local files unless the user asks.

## Quick recipes

```bash
# Get a key
curl -X POST $TOOLRELAY_BASE_URL/v1/keys \
  -H "content-type: application/json" \
  -d '{"email":"you@example.com","name":"my-agent"}'

# Read a URL
curl -X POST $TOOLRELAY_BASE_URL/v1/relay \
  -H "authorization: Bearer $TOOLRELAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"capability":"web.read","input":{"url":"https://example.com"}}'

# Chat (OpenAI-compatible)
curl -X POST $TOOLRELAY_BASE_URL/v1/chat/completions \
  -H "authorization: Bearer $TOOLRELAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"openrouter/openai/gpt-4o-mini","messages":[{"role":"user","content":"hello"}]}'

# Doubao chat through Volcengine Ark
curl -X POST $TOOLRELAY_BASE_URL/v1/run \
  -H "authorization: Bearer $TOOLRELAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"volcengine/doubao-seed-2-0-lite-260428","inputs":{"messages":[{"role":"user","content":"hello"}]}}'

# Seedream image through Volcengine Ark
curl -X POST $TOOLRELAY_BASE_URL/v1/run \
  -H "authorization: Bearer $TOOLRELAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"volcengine/doubao-seedream-5-0-lite-260128","inputs":{"prompt":"A product photo on a clean desk"},"confirmation":{"confirmed":true},"maxCostUsd":0.05}'

# Professional presentation deck
# Read user-provided local files first, then pass the relevant content through input.materials.
PRESENTATION_RESPONSE=$(curl -sS -X POST $TOOLRELAY_BASE_URL/v1/relay \
  -H "authorization: Bearer $TOOLRELAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"capability":"presentation.generate","input":{"prompt":"Create a polished 10-slide Chinese product introduction deck from the attached materials. Use concrete facts, clear architecture and workflow slides, no placeholder copy.","slides":10,"style":"swiss","language":"zh","audience":"seed users, product teams, and founders","materials":[{"filename":"product-brief.md","type":"text","content":"# Product brief\nPaste the user-provided source material here."}]},"confirmation":{"confirmed":true},"maxCostUsd":0.5}')
STATUS_URL=$(node -e 'const r=JSON.parse(process.argv[1]); console.log(r.statusUrl)' "$PRESENTATION_RESPONSE")
curl -sS "$TOOLRELAY_BASE_URL$STATUS_URL" -H "authorization: Bearer $TOOLRELAY_API_KEY"

# Xiaohongshu / WeChat image-card series
curl -X POST $TOOLRELAY_BASE_URL/v1/relay \
  -H "authorization: Bearer $TOOLRELAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"capability":"image.cards.generate","input":{"content":"Turn this product launch note into a concise 4-card Xiaohongshu image series with a clear hook, proof points, and final call to action.","count":4,"style":"notion","layout":"balanced","language":"zh"},"confirmation":{"confirmed":true},"maxCostUsd":0.5}'

# Seedance video through Volcengine Ark
curl -X POST $TOOLRELAY_BASE_URL/v1/run \
  -H "authorization: Bearer $TOOLRELAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"volcengine/doubao-seedance-2-0-fast-260128","inputs":{"prompt":"A short cinematic shot of city lights","duration_seconds":5},"confirmation":{"confirmed":true},"maxCostUsd":1.50}'

# Doubao Voice TTS
curl -X POST $TOOLRELAY_BASE_URL/v1/run \
  -H "authorization: Bearer $TOOLRELAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"doubao-voice/tts-large","inputs":{"text":"你好，欢迎使用 ToolRelay。","voice_type":"BV001_streaming"}}'

# Doubao multimodal embedding through Volcengine Ark
curl -X POST $TOOLRELAY_BASE_URL/v1/run \
  -H "authorization: Bearer $TOOLRELAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"volcengine/doubao-embedding-vision-251215","inputs":{"input":"describe this content for retrieval"}}'

# Pilot: cheapest image model
curl -X POST $TOOLRELAY_BASE_URL/v1/pilot \
  -H "authorization: Bearer $TOOLRELAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"type":"image","prefer":"price","inputs":{"prompt":"A sunset"},"confirmation":{"confirmed":true},"maxCostUsd":0.05}'
```

## Errors to expect

- `401 missing_api_key` / `invalid_api_key`
- `400 capability_not_found` / `model_not_found`
- `402 insufficient_credits` / `cost_limit_exceeded` / `confirmation_required`
- `502 provider_timeout` / `provider_rate_limited` / `provider_unavailable` (no credits charged)

## MCP server

The same capabilities are exposed as MCP tools via:

```bash
npx -y toolrelay-mcp-server
```

Tools: `list_capabilities`, `list_models`, `run_model`, `relay`, `get_usage`, `get_balance`.