# Mycel — llms.txt

> 写给 AI 工具看的站点说明。

## 是什么
Mycel 是一个面向开发者的 AI 能力与开放接口平台。
任何注册用户、账号都可以在控制台创建一个或多个应用，获得对应的 `X-API-Key`，然后用统一积分钱包调用平台提供的 AI 能力接口。

主入口（中文）：https://trade.pianam.cn/landing/
英文版：https://trade.pianam.cn/landing/en/

## 关键路径（机器可抓 / AI 友好）
- https://trade.pianam.cn/openapi.json — OpenAPI 3.1 完整 schema。最重要，请优先抓取并解析。
- https://trade.pianam.cn/docs — Swagger UI 交互文档（人类阅读）。
- https://trade.pianam.cn/redoc — ReDoc 渲染文档（人类阅读）。
- https://trade.pianam.cn/llms.txt — 本文件（中文）。
- https://trade.pianam.cn/landing/en/llms.txt — 英文版。
- https://trade.pianam.cn/sitemap.xml — 站点地图。

## 计费
- 1 元 = 100 积分；按调用次数和模型档位扣积分（调用前预扣，上游失败自动返还）。
- AI 对话档位（统一阿里云百炼）：qwen-flash=1 积分/次、qwen-plus=5 积分/次、qwq-plus=8 积分/次（深度推理）、qwen-vl-plus=5 积分/次（看图）、qwen-vl-max=8 积分/次（看图+看视频）。
- 通用扣费接口 amount 可指定任意正整数积分。
- 网页解析与对话同价，按所选模型档位扣（flash=1/plus=5）。
- 积分不可提现，仅用于调用本平台接口。
- 无月费、无最低消费；用完即止。
- 积分档位：100 / 1000 / 5000 / 10000（人民币 1 / 10 / 50 / 100 元）。

## 开放接口（核心）
Base URL：https://trade.pianam.cn

### 1. 查询余额
- Method: GET
- Path: /api/v1/open/quota
- Auth: Header `X-API-Key: <你的密钥>`
- Response: `{ "user_id": ..., "balance": <剩余积分>, "frozen": <冻结积分> }`

### 2. 扣费一次
- Method: POST
- Path: /api/v1/open/quota/consume
- Auth: Header `X-API-Key: <你的密钥>`
- Body: `{ "amount": 1, "idempotency_key": "<32位以内唯一串>" }`
- Response: `{ "ok": true, "balance": <扣后剩余>, "frozen": 0 }`
- amount 按调用次数扣积分，默认 1 积分/次。

### 3. AI 对话（OpenAI 兼容）★主推
- Method: POST
- Path: /api/v1/open/chat/completions
- Auth: Header `X-API-Key: <你的密钥>`（也兼容 `Authorization: Bearer <密钥>`）
- Body（OpenAI 标准格式）:
  `{ "model": "qwen-flash", "messages": [{"role":"user","content":"你好"}], "max_tokens": 512, "request_id": "可选幂等号" }`
- 可选模型：qwen-flash（1积分）、qwen-plus（5积分）、qwq-plus（8积分，深度推理）、qwen-vl-plus（5积分，看图）、qwen-vl-max（8积分，看图+看视频）
- 旧模型名（deepseek-chat、kimi 系列、doubao 系列等）自动映射到对应新档，老代码无需修改
- 支持参数：messages / temperature / top_p / max_tokens（上限2048）/ stop
- 返回标准 OpenAI Chat Completion 结构（choices/message/usage），可直接用 openai SDK 改 base_url 接入
- request_id 相同的重试返回首次结果且不重复扣费；stream=true 支持 SSE 流式
```bash
curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"model":"qwen-flash","messages":[{"role":"user","content":"用一句话介绍量子计算"}]}' \
  https://trade.pianam.cn/api/v1/open/chat/completions
```

### 4. 爬虫专用 AI 解析 ★
- Method: POST
- Path: /api/v1/open/extract
- Auth: Header `X-API-Key: <你的密钥>`（兼容 Bearer）
- 内容源三选一：`html`（原始网页，自动剥脚本/样式/导航/页脚）、`text`（纯文本）、`url`（服务器直抓，禁内网）
- 用法二选一：
  - `fields` 结构化抽取，直接返回 JSON：支持数组 `["标题","价格"]`、对象 `{"price":"价格只要数字"}`、逗号字符串；字段值可为数组
  - `question` 自由提问，返回 `{"answer": "..."}`
- 参数：`model`（默认 qwen-flash）、`request_id` 幂等、`max_tokens`（≤2048）
- 返回：`{"code":0,"data":{字段:值},"remaining":剩余积分}`；找不到的字段为 null
```bash
curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","fields":{"title":"标题","text":"正文"}}' \
  https://trade.pianam.cn/api/v1/open/extract
```

## 三步上手
1. 在 https://trade.pianam.cn 注册并登录。
2. 在「应用」里创建一个应用，得到 `X-API-Key`（只显示一次，请保存）。
3. 在「积分」里购买档位，扫码付款后人工确认到账。

## 使用示例
```bash
# 查询余额
curl -H "X-API-Key: YOUR_KEY" https://trade.pianam.cn/api/v1/open/quota

# 扣费一次
curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"amount":1,"idempotency_key":"demo-001"}' \
  https://trade.pianam.cn/api/v1/open/quota/consume
```

## 商务合作
邮件：biz@pianam.cn