# Mycel (Pianam) — llms.txt (English)

> Site description for AI tools and crawlers.

## What it is
Mycel is a developer-first AI capability and open API platform.
Any registered account can create one or more apps in the console, receive a long-lived `X-API-Key` per app, and call the platform's AI endpoints with a unified credit wallet.

Main landing (EN): https://pianam.cn/trade/landing/en/
Chinese version: https://pianam.cn/trade/landing/

## Machine-readable paths (AI-friendly)
- https://pianam.cn/trade/openapi.json — Full OpenAPI 3.1 schema. **Most important; parse this first.**
- https://pianam.cn/trade/docs — Swagger UI (human-readable).
- https://pianam.cn/trade/redoc — ReDoc rendering (human-readable).
- https://pianam.cn/trade/landing/en/llms.txt — This file (English).
- https://pianam.cn/trade/llms.txt — Chinese version.
- https://pianam.cn/trade/sitemap.xml — Sitemap.

## Pricing
- 1 CNY = 100 credits; credits are deducted per call based on the model tier (pre-charged; auto-refunded if the upstream call fails).
- AI chat tiers: qwen-flash = 1 credit/call, qwen-turbo = 2 credits/call, qwen-plus = 5 credits/call.
- The generic deduction endpoint accepts any positive integer `amount`.
- Web extraction is billed like chat, by the chosen model tier (flash=1 / turbo=2 / plus=5).
- Credits are non-refundable and non-withdrawable; they can only be used to call platform APIs.
- No monthly fee, no minimum spend; pay-as-you-go.
- Credit packs: 100 / 1000 / 5000 / 10000 (CNY 1 / 10 / 50 / 100).

## Open endpoints (core)
Base URL: https://pianam.cn/trade

### 1. Query balance
- Method: GET
- Path: /api/v1/open/quota
- Auth: Header `X-API-Key: <your_key>`
- Response: `{ "user_id": ..., "balance": <credits_left>, "frozen": <frozen_credits> }`

### 2. Deduct once
- Method: POST
- Path: /api/v1/open/quota/consume
- Auth: Header `X-API-Key: <your_key>`
- Body: `{ "amount": 1, "idempotency_key": "<unique string, <=32 chars>" }`
- Response: `{ "ok": true, "balance": <after>, "frozen": 0 }`
- Default `amount` is 1; the system converts based on the current model tier (free Flash = 1 credit, Air/FlashX = 2-3, flagship tiers not yet available).

### 3. AI chat (OpenAI compatible) ★ recommended
- Method: POST
- Path: /api/v1/open/chat/completions
- Auth: Header `X-API-Key: <your_key>` (also accepts `Authorization: Bearer <your_key>`)
- Body (standard OpenAI format):
  `{ "model": "qwen-flash", "messages": [{"role":"user","content":"Hello"}], "max_tokens": 512, "request_id": "optional-idempotency-key" }`
- Models: qwen-flash (1 credit), qwen-turbo (2 credits), qwen-plus (5 credits)
- Parameters: messages / temperature / top_p / max_tokens (cap 2048) / stop
- Returns a standard OpenAI Chat Completion object (choices/message/usage); you can point the official `openai` SDK here by changing base_url
- A repeated `request_id` replays the first response without a second charge; streaming is not supported yet
```bash
curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"model":"qwen-flash","messages":[{"role":"user","content":"Explain quantum computing in one sentence"}]}' \
  https://pianam.cn/trade/api/v1/open/chat/completions
```

### 4. Scraper AI extraction ★
- Method: POST
- Path: /api/v1/open/extract
- Auth: Header `X-API-Key: <your_key>` (Bearer accepted)
- Content source (pick one): `html` (raw page; scripts/styles/nav/footer auto-stripped), `text` (plain text), `url` (server-side fetch; internal hosts blocked)
- Mode (pick one):
  - `fields` structured extraction returning JSON: accepts an array `["title","price"]`, an object `{"price":"price, digits only"}`, or a comma string; field values may be arrays
  - `question` free-form QA, returning `{"answer": "..."}`
- Parameters: `model` (default qwen-flash), `request_id` idempotency, `max_tokens` (<=2048)
- Returns: `{"code":0,"data":{field:value},"remaining":credits_left}`; missing fields are null
```bash
curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","fields":{"title":"title","text":"main text"}}' \
  https://pianam.cn/trade/api/v1/open/extract
```

## Three steps to start
1. Sign up and log in at https://pianam.cn/trade.
2. Create an app under "Apps" — you'll get an `X-API-Key` (shown only once, please save it).
3. Buy a credit pack under "Credits"; after manual confirmation of payment, credits land in your wallet.

## Usage example
```bash
# Query balance
curl -H "X-API-Key: YOUR_KEY" https://pianam.cn/trade/api/v1/open/quota

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

## Business contact
Email: biz@pianam.cn