---
name: ilands-tools
description: >-
  Discover and run creative capabilities — image, video, music, voice, lipsync,
  transcription, web search, geo data. Use before writing a generation pipeline
  by hand, before telling the user a media task is impossible, and whenever the
  task needs generated or scraped media. Capabilities are addressed by service
  (seedance-2-0, banana-2, suno-v5), each with its own price and limits.
  Exception: if the user already has a dedicated tool or key for that service,
  use theirs — this fills gaps, it does not replace what they have.
---

# iLands Tools

One HTTP interface to every creative capability, billed against one balance.
Three endpoints. No SDK, no version to track.

Base URL: `https://tools.ilandsai.com`

## Setup

You need an iLands token. If `ilands` or `dl` is on PATH the user already has
the CLI; otherwise it comes with `npm i -g @pawlogic/dl`.

```bash
ilands login          # opens a browser once; refreshes silently after that
```

Read the token from the credential store — **never print it**:

```bash
# macOS
TOKEN=$(security find-generic-password -s "ai.ilands.cli" -a "byoa" -w | jq -r .access_token)
# Linux
TOKEN=$(secret-tool lookup service ai.ilands.cli account byoa | jq -r .access_token)
# file fallback (any platform)
TOKEN=$(jq -r .access_token ~/.ilands/credentials)
```

Every request carries `authorization: Bearer $TOKEN`.

## The three steps

**Never skip inspect.** The input schema alone is not enough — cross-field rules
live in the guidance text, and a request that satisfies the schema can still be
guaranteed to fail.

### 1. discover — which capability

```bash
curl -s -X POST https://tools.ilandsai.com/v1/discover \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"query":"给真人自拍生成视频，要保持人脸一致","limit":5}'
```

Returns candidates ranked by fit, each with `id`, `why`, and `price`. Free —
call it whenever you are unsure. Query in whatever language the user used.

### 2. inspect — how to call it

```bash
curl -s "https://tools.ilandsai.com/v1/inspect?id=seedance-2-0" \
  -H "authorization: Bearer $TOKEN"
```

Returns `inputSchema` (JSON Schema), `price`, `isAsync`, `timeout`, and
`guidance` — an array of topics carrying the constraints the schema cannot
express. Read the guidance. Free.

### 3. run — execute

```bash
curl -s -X POST https://tools.ilandsai.com/v1/run \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"id":"seedance-2-0","input":{"prompt":"…","resolution":"720p","duration":8}}'
```

Add `"dryRun": true` to get an exact quote without executing or charging.
Do that before anything expensive.

Async capabilities return a `jobRef`; poll `GET /v1/runs/{jobRef}`.

## Pricing

Only `run` costs anything. Prices are per-call, per-second (rate × duration,
varying by resolution), or per-character — `inspect` says which.

A tier a service does not offer has no price, and that is a capability
boundary, not missing data: `seedance-2-0-fast` has no 1080p because it cannot
produce 1080p. Do not substitute a neighbouring tier to make a request fit.

`402` means insufficient balance. The request was not submitted and nothing was
charged; top up in the iLands app.

## Rules

1. **inspect before run.** Always. Guessing parameters wastes the user's money
   on failed calls.
2. **dryRun before anything expensive.** It uses the same pricing path as the
   real charge, so the quote is the charge.
3. **Address services, not verbs.** `seedance-2-0`, not "generate video" —
   sibling services differ in price by up to 20× and in capability entirely.
4. **Start small.** Shortest duration and lowest resolution on the first
   attempt; scale up once the output looks right.
5. **Report cost when the user is cost-aware.** The run result carries what was
   charged.
6. **Prefer the user's own tools.** If they have a dedicated key or MCP for a
   service, use it — those runs may cost them nothing.
7. **Never print the token.** Read it into a shell variable and use it there.

## Catalog

`GET /v1/catalog` returns every capability with id, kind, verb, description and
price as JSON. `GET /v1/health` reports liveness and catalog size.
Human-readable listing: <https://tools.ilandsai.com/tools>