API 文档

Mirror AI 提供基于 HTTP + JSON 的玄学计算接口：八字、合盘、测字、纳甲、紫微斗数。所有 /v1/* 请求使用 Bearer 鉴权，按 endpoint 价格扣除 credits。

✓ 已登录，文档示例中的 YOUR_API_KEY 已自动替换为你的真实 key。

Quickstart

1. 在 /register 注册账号，登录后从 Dashboard 复制 API key。

2. 在 /billing 通过 Stripe 充值，每次调用按下方价格扣除 credits。

3. 用 Bearer token 调任意 endpoint。下面这个调用查询当前余额：

curl https://open.mymirrorai.com/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

resp = requests.get(
    "https://open.mymirrorai.com/v1/balance",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://open.mymirrorai.com/v1/balance", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
if (!resp.ok) throw new Error(await resp.text());
console.log(await resp.json());

响应：

{
  "user_id": "u_a1b2c3d4",
  "balance_credits": 1000,
  "daily_credits_limit": null
}

Authentication

所有 /v1/* 接口走 Authorization: Bearer <api_key>。 key 在 Dashboard 一处展示和重置。

key 在 Dashboard 重置后会立即吊销，所有正在使用旧 key 的客户端会得到 401。
请求体里如果带 user_id，必须跟 key 绑定的 user_id 一致，否则 403。多数 endpoint 可以省略 user_id，让服务器从 key 推断。
同一时刻同一 user 在飞的请求数有上限（默认 2），超出返 429 inflight_limit。
每用户每分钟请求数有上限（默认 10），超出返 429 rate_limited。

错误码与计费头

错误统一形如：

{
  "error": {
    "code": "insufficient_funds",
    "message": "Balance 50 is below endpoint cost 200."
  }
}

常见错误：

HTTP	code	含义
401	`unauthorized`	缺失 / 无效 / 已吊销的 Bearer key
402	`insufficient_funds`	余额不足以支付本次调用
403	`user_id_mismatch`	body 中 user_id 与 key 绑定的 user 不一致
400	`invalid_request` 等	请求体校验失败
429	`rate_limited` / `inflight_limit`	QPS / 并发上限
503	`stripe_not_configured`	服务端尚未配置 Stripe

所有计费 endpoint 的成功响应都带上以下 header：

Header	含义
`X-Charged-Credits`	本次调用扣的 credits（admin 旁路时为 0）
`X-Balance-After`	扣费后的账户余额
`X-Request-Id`	对账用 request_id，可在 `/v1/usage` 找回

1. Account

查余额、查使用记录、查 / 重置 API key。

GET /v1/me cookie auth · 免费

返回当前登录账号的概览（user_id / email / 余额 / 当前 API key）。鉴权方式：浏览器 session cookie（不是 Bearer）。Dashboard 用这个 endpoint 拉数据。

# /v1/me 用 session cookie，正常通过浏览器调；命令行不常用
curl https://open.mymirrorai.com/v1/me --cookie "mirror_session=…"

import requests
s = requests.Session()
s.post("https://open.mymirrorai.com/v1/auth/login",
       json={"email": "you@example.com", "password": "..."})
print(s.get("https://open.mymirrorai.com/v1/me").json())

// /v1/me uses session cookie; in a browser, just call fetch with credentials.
const r = await fetch("https://open.mymirrorai.com/v1/me", {
  credentials: "include",
});
console.log(await r.json());

GET /v1/balance 免费

查询当前账号的 credits 余额。

curl https://open.mymirrorai.com/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

r = requests.get(
    "https://open.mymirrorai.com/v1/balance",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(r.json())  # {"user_id":"u_…","balance_credits":1000}

const r = await fetch("https://open.mymirrorai.com/v1/balance", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
console.log(await r.json());

GET /v1/usage?limit=50 免费

列出最近的扣费 / 充值 / 退款记录。limit 默认 50，最大 500。

curl "https://open.mymirrorai.com/v1/usage?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

r = requests.get(
    "https://open.mymirrorai.com/v1/usage",
    params={"limit": 20},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
for row in r.json()["rows"]:
    print(row["ts"], row["endpoint"], row["amount_credits"])

const r = await fetch("https://open.mymirrorai.com/v1/usage?limit=20", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const { rows } = await r.json();
for (const row of rows) console.log(row.ts, row.endpoint, row.amount_credits);

POST /v1/me/api_key/rotate cookie auth · 免费

一键吊销当前 key 并生成新的。Dashboard 上「重置 Key」就是调用这个。响应的 new_api_key 是新 key 的明文，**只在这一次返回**，但同时存进库里供 Dashboard 重新展示。

2. BaZi · 八字

基于公历生日 + 出生时间排盘，AI 解读人生主题、年运、性格等。

POST /v1/ask 200 credits

同步返回完整答案。可不带 user_id，服务端会从 API key 推断。

请求体

字段	类型	说明
question 必填	string	自然语言问题
birth	object	`{year, month, day, hour?, minute?}` · 阳历
gender	male \| female	默认 `male`
session_id	string	用于多轮对话上下文记忆
llm_model	string	可选模型覆盖；默认 `gemini-3.1-pro-preview`

curl https://open.mymirrorai.com/v1/ask \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "今年事业怎么样？",
    "birth": {"year": 1990, "month": 5, "day": 12, "hour": 10},
    "gender": "male"
  }'

r = requests.post(
    "https://open.mymirrorai.com/v1/ask",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "question": "今年事业怎么样？",
        "birth": {"year": 1990, "month": 5, "day": 12, "hour": 10},
        "gender": "male",
    },
    timeout=180,
)
data = r.json()
print(data["answer"])
print("charged:", r.headers["X-Charged-Credits"])

const r = await fetch("https://open.mymirrorai.com/v1/ask", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    question: "今年事业怎么样？",
    birth: { year: 1990, month: 5, day: 12, hour: 10 },
    gender: "male",
  }),
});
const data = await r.json();
console.log(data.answer);

POST /v1/ask_stream 200 credits

同样的请求体，返回 text/event-stream 流。事件类型包括 plan、node_status、response_delta、response、billing。

curl -N https://open.mymirrorai.com/v1/ask_stream \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"今年事业怎么样？","birth":{"year":1990,"month":5,"day":12}}'

with requests.post(
    "https://open.mymirrorai.com/v1/ask_stream",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"question": "今年事业怎么样？",
          "birth": {"year": 1990, "month": 5, "day": 12}},
    stream=True,
    timeout=180,
) as r:
    for line in r.iter_lines(decode_unicode=True):
        if line.startswith("data:"):
            print(line)

const r = await fetch("https://open.mymirrorai.com/v1/ask_stream", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    question: "今年事业怎么样？",
    birth: { year: 1990, month: 5, day: 12 },
  }),
});
const reader = r.body.getReader();
const dec = new TextDecoder();
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(dec.decode(value));
}

3. HePan · 合盘

两人八字合盘，分析关系兼容度、相处建议等。

POST /v1/hepan/ask 100 credits

请求体

字段	类型	说明
question 必填	string	关系类问题
person_a 必填	object	`{name?, gender, birth, birth_time_unknown?}`
person_b 必填	object	同上

curl https://open.mymirrorai.com/v1/hepan/ask \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "我们适合长期发展吗？",
    "person_a": {"name": "A", "gender": "male",
                  "birth": {"year": 1990, "month": 5, "day": 12, "hour": 10}},
    "person_b": {"name": "B", "gender": "female",
                  "birth": {"year": 1992, "month": 8, "day": 20, "hour": 14}}
  }'

r = requests.post(
    "https://open.mymirrorai.com/v1/hepan/ask",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "question": "我们适合长期发展吗？",
        "person_a": {"name": "A", "gender": "male",
                     "birth": {"year": 1990, "month": 5, "day": 12, "hour": 10}},
        "person_b": {"name": "B", "gender": "female",
                     "birth": {"year": 1992, "month": 8, "day": 20, "hour": 14}},
    },
    timeout=180,
)
print(r.json()["answer"])

const r = await fetch("https://open.mymirrorai.com/v1/hepan/ask", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    question: "我们适合长期发展吗？",
    person_a: { name: "A", gender: "male",
                birth: { year: 1990, month: 5, day: 12, hour: 10 } },
    person_b: { name: "B", gender: "female",
                birth: { year: 1992, month: 8, day: 20, hour: 14 } },
  }),
});
console.log((await r.json()).answer);

4. CeZi · 测字

用户给一个汉字 + 问题，AI 基于字形 / 五行解读。最便宜的 endpoint，适合做 smoke test。

POST /v1/cezi/ask 30 credits

请求体

字段	类型	说明
question 必填	string	问题
character 必填	string	一个汉字

curl https://open.mymirrorai.com/v1/cezi/ask \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"这个项目合作能不能成？","character":"合"}'

r = requests.post(
    "https://open.mymirrorai.com/v1/cezi/ask",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"question": "这个项目合作能不能成？", "character": "合"},
    timeout=120,
)
print(r.json()["answer"])

const r = await fetch("https://open.mymirrorai.com/v1/cezi/ask", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    question: "这个项目合作能不能成？",
    character: "合",
  }),
});
console.log((await r.json()).answer);

5. NaJia · 纳甲 / 六爻

六爻起卦后基于纳甲法 + AI 给出判词。可让服务端摇卦，也可自行传入 6 爻数值。

POST /v1/najia/ask 50 credits（paraphrase=true 时 80）

请求体

字段	类型	说明
question 必填	string	问题
yao_values	int[6] (0–7)	6 爻数值；不传则服务端随机摇卦
paraphrase	boolean	是否额外跑一轮 LLM 把卦盘转写成更人话

curl https://open.mymirrorai.com/v1/najia/ask \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "这个项目三个月内能不能推进成功？",
    "yao_values": [0, 1, 2, 3, 4, 5]
  }'

r = requests.post(
    "https://open.mymirrorai.com/v1/najia/ask",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "question": "这个项目三个月内能不能推进成功？",
        "yao_values": [0, 1, 2, 3, 4, 5],
    },
    timeout=150,
)
out = r.json()
print(out["answer"])
print(out["gua"])  # 排好的卦盘 dict

const r = await fetch("https://open.mymirrorai.com/v1/najia/ask", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    question: "这个项目三个月内能不能推进成功？",
    yao_values: [0, 1, 2, 3, 4, 5],
  }),
});
console.log((await r.json()).answer);

6. ZWDS · 紫微斗数

排紫微命盘 + 流年流月解读。include_star_gong=true 会注入约 973 KB 的星耀宫位查表，价格翻倍。

POST /v1/zwds/ask 80 credits（include_star_gong=true 时 150）

请求体

字段	类型	说明
question 必填	string	问题
birth 必填	object	`{year, month, day, hour?}`
gender	male \| female	默认 `male`
target_years	int[]	要分析的流年，默认当前年
include_star_gong	boolean	注入星耀宫位大表（更精准但更贵）

curl https://open.mymirrorai.com/v1/zwds/ask \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "今年我的事业和感情运势如何？",
    "birth": {"year": 1990, "month": 5, "day": 12, "hour": 10},
    "gender": "male",
    "target_years": [2026]
  }'

r = requests.post(
    "https://open.mymirrorai.com/v1/zwds/ask",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "question": "今年我的事业和感情运势如何？",
        "birth": {"year": 1990, "month": 5, "day": 12, "hour": 10},
        "gender": "male",
        "target_years": [2026],
    },
    timeout=180,
)
print(r.json()["answer"])

const r = await fetch("https://open.mymirrorai.com/v1/zwds/ask", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    question: "今年我的事业和感情运势如何？",
    birth: { year: 1990, month: 5, day: 12, hour: 10 },
    gender: "male",
    target_years: [2026],
  }),
});
console.log((await r.json()).answer);

7. Billing

充值通过 Stripe Checkout 完成。Stripe webhook 自动入账。

GET /v1/topup_packs 公开 · 免费

列出充值套餐和 Stripe 配置状态。无需鉴权，前端可直接拉。

POST /v1/checkout/create 免费

创建 Stripe Checkout Session。请求体二选一：pack_id（套餐 ID）或 custom_yuan（自定义元数，1–9999）。返回 checkout_url，重定向用户的浏览器到这个 URL 即可。

curl https://open.mymirrorai.com/v1/checkout/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"custom_yuan": 50}'

r = requests.post(
    "https://open.mymirrorai.com/v1/checkout/create",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"custom_yuan": 50},
)
print(r.json()["checkout_url"])  # redirect the user here

const r = await fetch("https://open.mymirrorai.com/v1/checkout/create", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ custom_yuan: 50 }),
});
const { checkout_url } = await r.json();
window.location.href = checkout_url;

完整的 OpenAPI schema 由 Mirror AI 内部维护，所有 v1 endpoint 一向后兼容；如果你需要更深入的字段说明或者集成示例，直接联系运营同学。