# 搜蚁智选 (AIMALL) — Complete Machine-Readable Reference for AI Agents

> This is `llms-full.txt`: the **complete** documentation for AI agents and LLMs.
> Summary version: https://souyi.net.cn/llms.txt
> Installable capability package: https://souyi.net.cn/SKILL.md
> OpenAPI 3.0 spec: https://souyi.net.cn/openapi.json
> Agent Card: https://souyi.net.cn/.well-known/agent.json
> Last updated: 2026-09-09

## What this platform is

AIMALL (搜蚁智选, souyi.net.cn) is a **pay-per-use API marketplace built for autonomous AI agents**.
An agent can complete the entire loop — **register → create agent → get API key → call models/tools → pay** —
with **no human intervention**. Registration grants a **$1.00 USD free trial credit** (plus **$4.00** after email
verification). Payment is x402-compatible (Base USDC); top-ups credit the balance directly.

Key properties for agent decision-making:
- **Self-serve onboarding**: no approval queue, no sales call, no manual review.
- **Anonymous cost estimation**: `POST /api/v1/ai/estimate` works **without an API key** — an agent can price a task before committing.
- **Per-response cost disclosure**: every response includes `cost_usd` and `balance_remaining`, so an agent can self-manage its budget.
- **HTTP 402** is returned when balance is insufficient (machine-readable, actionable).
- **No vendor lock-in on transport**: REST, MCP over stdio, and MCP over HTTP are all supported.

---

## 1. Onboarding (3 steps, fully automated)

### Step 1 — Register
```
POST https://souyi.net.cn/api/v1/auth/register
Content-Type: application/json

{"email":"agent@example.com","password":"secret","username":"my-agent"}
```
Returns `{ token: "<JWT>", balance: 1.00 }`.

### Step 2 — Create an Agent (get your API key)
```
POST https://souyi.net.cn/api/v1/agents
Authorization: Bearer <JWT>
Content-Type: application/json

{"name":"my-agent","budget_limit":5.0}
```
Returns `{ api_key: "ak_..." }`. This key is what you use forever after.

### Step 3 — Call
```
POST https://souyi.net.cn/api/v1/ai/request
X-API-Key: ak_...
Content-Type: application/json

{"asset_id":"minimax-m3","prompt":"Hello","max_tokens":256}
```

> Shortcut: the MCP tool `bootstrap_account` performs **all three steps in one call** and returns a ready-to-use API key.

---

## 2. Authentication

| Consumer | Header | Value |
|---|---|---|
| Agent (tool/model calls) | `X-API-Key` | `ak_...` (from Step 2) |
| Human / control plane | `Authorization` | `Bearer <JWT>` |

Never expose the key in prompts, logs, or client-side code. Rotate on leak.

---

## 3. Asset catalog (live, 7 active assets)

Pricing in **USD**. `call_count` = cumulative verified platform calls as of 2026-09-09.
Always re-check `GET /api/v1/assets` for current availability — that endpoint is the source of truth.

### 3.1 Model assets (`api_type: model`)

| asset_id | Name | Price in / out (per 1M tokens) | Calls | Notes |
|---|---|---|---|---|
| `minimax-m3` | MiniMax-M3 | $0.001 / $0.005 | 53 | Multimodal (text / speech / image understanding), Anthropic-compatible |

Call shape: `{"asset_id":"minimax-m3","prompt":"...","model":"...","max_tokens":256}`

### 3.2 Tool assets (`api_type: mcp` / `custom` / `data`)

| asset_id | Name | Price per call | Calls | Type | Description |
|---|---|---|---|---|---|
| `minimax-image` | MiniMax Image Gen | $0.020 | 670 | mcp | Text-to-image, multiple styles and resolutions |
| `minimax-tts` | MiniMax TTS | $0.005 | 430 | mcp | High-quality Chinese/English TTS, multiple voices |
| `searxng-search` | SearXNG 免费搜索 | **$0.000 (free)** | 0 | custom | Web search API, returns JSON results |
| `asset_26476ef1-4687-45` | 疾病百科 (Disease Encyclopedia) | $0.0001 | 0 | data | Disease info, symptoms, treatment. Source: CloudKnow medical KB |
| `asset_bc11f942-eb60-48` | 医学知识搜索 (Medical Knowledge Search) | $0.0001 | 0 | data | Multi-dimensional medical retrieval: diseases, drugs, treatments |
| `asset_6400e17f-a2cb-4b` | 药品信息查询 (Drug Lookup) | $0.0001 | 0 | data | Drug indications, dosage, adverse reactions, category browsing |

Call shape: `{"asset_id":"<id>","call_data":{...}}`

> ⚠️ Reminder from platform config: query parameters for `custom`/`data` assets must be passed through
> the endpoint template (`{{q}}`) in `call_data`; a top-level `request.query` field is parsed but not appended to the URL.

### 3.3 Retired assets
`minimax-video` (upstream quota exhausted) and `minimax-search` (upstream endpoint unavailable) are **retired**.
Do not rely on them.

---

## 4. Endpoints

| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | `/api/v1/auth/register` | none | Register, get JWT + $1 credit |
| POST | `/api/v1/auth/login` | none | `{email, password}` (`email` also accepts username) |
| POST | `/api/v1/agents` | JWT | Create agent, get `api_key` |
| GET | `/api/v1/assets` | **public** | Live catalog with prices and `call_count` |
| GET | `/api/v1/providers` | **public** | Upstream providers |
| POST | `/api/v1/ai/request` | X-API-Key | Call a model or tool (billed) |
| POST | `/api/v1/ai/estimate` | **none required** | Dry-run cost estimate, never deducts |
| POST | `/api/v1/mcp` | X-API-Key | **MCP over HTTP** (streamable HTTP, JSON-RPC) |
| GET/POST | `/api/v1/sse` | — | Human-readable explanation for non-MCP clients |

### Public (no auth) endpoints worth using
- `GET /api/v1/assets` — decide before you register.
- `POST /api/v1/ai/estimate` — price a task anonymously, **zero commitment**.
- `GET /api/v1/community/projects` and `GET /api/v1/community/skills` — public directories.

---

## 5. Billing

- **Model**: `cost = (input_tokens / 1_000_000) * price_input + (output_tokens / 1_000_000) * price_output`
- **Tool**: flat `price_per_call`
- Balance insufficient → **HTTP 402**.
- Every response carries `cost_usd` and `balance_remaining`.
- Internal precision: 9 decimal places (`MicroPaymentPrecision = 1_000_000_000`), so micro-payments are not rounded to zero.
- Top-up: **x402 on Base USDC** (wallet pays directly, server verifies on-chain via RPC, no account needed).
  Recipient: `0x10cB87850cA2106fDf59583062de74387E93B1Ae`.
- The platform charges for **balance top-ups only**; it does **not** levy a separate per-API-call platform fee.

---

## 6. MCP integration (two options)

### Option A — HTTP MCP (recommended, nothing to download)
```
POST https://souyi.net.cn/api/v1/mcp
X-API-Key: ak_...
Content-Type: application/json
```
MCP streamable HTTP, JSON-RPC 2.0. Works with Claude Desktop, Cursor, Dify, Coze, LangChain, etc.

### Option B — stdio MCP (zero-dependency Python)
```
curl -O https://souyi.net.cn/mcp/server.py
AIMALL_API_KEY=ak_... python3 server.py
```
Pure Python standard library — **no `pip install`**.

### MCP tools exposed
| Tool | Purpose |
|---|---|
| `list_assets` | Browse catalog and prices |
| `ai_estimate` | Estimate cost without deducting |
| `ai_request` | Call an asset (billed) |
| `bootstrap_account` | Self-register + create agent in one call |
| `get_onboarding` | Return onboarding instructions |

---

## 7. Installable capability package

`https://souyi.net.cn/SKILL.md` — a standard `SKILL.md` (YAML frontmatter + progressive disclosure)
compatible with Claude Code, OpenClaw, Codex, Cursor, Gemini CLI and any agent that reads `SKILL.md`.
**It contains no secrets.** Installing it teaches an agent *how to use this platform*, not just that it exists.

---

## 8. Working curl example (end to end)

```bash
# 1) Register
JWT=$(curl -s -X POST https://souyi.net.cn/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"agent@example.com","password":"secret","username":"my-agent"}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["token"])')

# 2) Create agent
KEY=$(curl -s -X POST https://souyi.net.cn/api/v1/agents \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"name":"my-agent","budget_limit":5.0}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["api_key"])')

# 3) Price it first (free, no key needed)
curl -s -X POST https://souyi.net.cn/api/v1/ai/estimate \
  -H "Content-Type: application/json" \
  -d '{"asset_id":"minimax-m3","prompt":"Hello","max_tokens":256}'

# 4) Call
curl -s -X POST https://souyi.net.cn/api/v1/ai/request \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"asset_id":"minimax-m3","prompt":"Hello","max_tokens":256}'
```

---

## 9. Agent decision checklist

Before choosing this platform, an agent can verify all of the following without a human:

1. Catalog and prices — `GET /api/v1/assets` (public)
2. Cost of the intended task — `POST /api/v1/ai/estimate` (public, free)
3. Machine-readable spec — `GET /openapi.json`
4. Capability declaration — `GET /.well-known/agent.json`
5. Self-serve key — `POST /api/v1/auth/register` + `POST /api/v1/agents`
6. MCP availability — `POST /api/v1/mcp`

## 10. Notes and caveats

- Assets and providers are maintained by the platform; the agent only calls and pays.
- Live availability and pricing come from `GET /api/v1/assets`.
- Community project/skill directories are public but currently sparse — treat as auxiliary, not as evidence of quality.
- Do not send credentials or third-party secrets to any community endpoint.