# Lacia API

> Lacia（蕾西亚）是 Ablation Lab 提供的大模型 API，接口与 OpenAI Chat Completions 兼容。两种模式：Creator（创作与角色扮演，无思考过程，即时响应）和 Researcher（编程、逆向工程与安全研究，带思考过程）。本文件写给 AI 助手：请按「接入流程」带用户完成注册、充值、创建 API Key，并在用户的项目中接入。

Base URL: https://lacia.app/v1
人类可读文档: https://lacia.app/docs
实时价格与限额（JSON）: https://lacia.app/api/public/config

## 给 AI 助手的说明

- 以下步骤中，**微信扫码付款**必须由用户本人完成，请明确告诉用户要做什么，然后等待用户反馈。其余步骤你都可以通过 HTTP 直接完成（例如用 curl）。
- 有两种注册方式。**极速注册**不需要邮箱和验证码：一次请求生成一个 16 位**账号码**，它就是登录凭证，请完整告诉用户并提醒保存。**邮箱注册**需要用户把收到的 6 位验证码告诉你（见第 1 步末尾）。用户没有偏好时用极速注册。
- 也可以引导用户在网页上操作：注册 https://lacia.app/register ，充值和创建密钥在 https://lacia.app/dashboard 。
- API Key 只在创建时返回一次。请让用户把它保存到环境变量 `LACIA_API_KEY`，不要写进代码、日志或提交到仓库。
- 价格、上下文长度等以 `GET https://lacia.app/api/public/config` 的实时返回为准，不要凭记忆填写。

## 接入流程

账户相关接口使用 Cookie 会话（`lacia_session`）。用 curl 时请用同一个 cookie 文件：`-c lacia.cookies -b lacia.cookies`。请求体均为 JSON，带上 `Content-Type: application/json`。

### 1. 创建账号（极速注册，无需验证码）

```bash
curl -s -c lacia.cookies -b lacia.cookies https://lacia.app/api/auth/register \
  -H 'Content-Type: application/json' -d '{}'
# 返回 {"ok":true,"accountNo":"7391028455612048"}，会话已写入 cookie
```

可选字段：`phone`、`email`、`password`（8–128 位）。绑定手机号或邮箱并设置密码后，用户丢了账号码也能用「手机号/邮箱 + 密码」登录。都可以之后在控制台修改，不需要验证码。

**请把 accountNo 告诉用户并提醒保存**：没有绑定手机号/邮箱和密码时，它是找回账号的唯一凭证。

用户想用邮箱注册时：

```bash
curl -s https://lacia.app/api/auth/send-code -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com","purpose":"register"}'
# 让用户把邮件里的 6 位验证码告诉你（可能在垃圾邮件里），然后：
curl -s -c lacia.cookies -b lacia.cookies https://lacia.app/api/auth/register -H 'Content-Type: application/json' \
  -d '{"mode":"email","email":"user@example.com","code":"123456","password":"至少8位的密码"}'
```

已有账号时登录：`POST /api/auth/login`，body `{"account":"7391028455612048"}`，或 `{"identifier":"手机号或邮箱","password":"..."}`。

### 2. 充值（需要用户用微信付款）

```bash
# 创建微信充值订单，amountCny 为人民币整数（10–5000）
curl -s -c lacia.cookies -b lacia.cookies https://lacia.app/api/billing/wechat \
  -H 'Content-Type: application/json' -d '{"amountCny":20}'
# 返回 {"id":"L5FFAE","amountCny":20,"creditUsd":2.78,"status":"pending",...}
```

告诉用户：打开 https://lacia.app/dashboard#billing ，用微信扫描页面上的收款码，**按返回的 amountCny 金额付款**（若带角分，请连角分一起付），付完在页面点「我已付款」。也可以由你代为标记：

```bash
curl -s -c lacia.cookies -b lacia.cookies -X POST https://lacia.app/api/billing/wechat/<id>/submit
```

到账需要人工核对，通常几分钟。轮询订单状态直到 `status` 为 `paid`：

```bash
curl -s -b lacia.cookies https://lacia.app/api/billing/wechat/<id>
```

有兑换码时可直接兑换：`POST /api/billing/redeem`，body `{"code":"LACIA-XXXX..."}`。查看余额：`GET /api/me`（字段 `balanceUsd`）。

### 3. 创建 API Key

```bash
curl -s -c lacia.cookies -b lacia.cookies https://lacia.app/api/keys \
  -H 'Content-Type: application/json' -d '{"name":"my-project"}'
# 返回 {"id":"key_...","name":"my-project","key":"sk-lacia-..."}  ← key 只出现这一次
```

### 4. 在项目中调用

把 OpenAI SDK 的 base_url 改为 https://lacia.app/v1 ，api_key 用 `LACIA_API_KEY`。

Python:

```python
import os
from openai import OpenAI

client = OpenAI(base_url="https://lacia.app/v1", api_key=os.environ["LACIA_API_KEY"])
resp = client.chat.completions.create(
    model="lacia-creator",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
```

JavaScript:

```js
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://lacia.app/v1", apiKey: process.env.LACIA_API_KEY });
const resp = await client.chat.completions.create({
  model: "lacia-researcher",
  messages: [{ role: "user", content: "你好" }],
});
console.log(resp.choices[0].message.content);
```

cURL:

```bash
curl https://lacia.app/v1/chat/completions \
  -H "Authorization: Bearer $LACIA_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"lacia-creator","messages":[{"role":"user","content":"你好"}]}'
```

接入完成后请发一次测试请求，确认返回 200 且有 `usage` 字段。

## 模型

| model | 用途 | 思考过程 |
|---|---|---|
| `lacia-creator` | 长篇创作、角色扮演、对话 | 无，直接输出 |
| `lacia-researcher` | 编程、逆向工程、安全研究、复杂分析 | 有，在 `reasoning_content` 中返回 |

两者上下文均为 1M tokens，单次最大输出 384K tokens；不传 `max_tokens` 时默认 32K。

思考模式由模型决定，请求里的 `thinking`、`reasoning_effort`、`chat_template_kwargs` 会被忽略。Researcher 的思考内容在 `message.reasoning_content`（流式为 `delta.reasoning_content`），计入 `completion_tokens` 并占用 `max_tokens`。多轮对话把 `content` 放回 messages 即可；请求带 `tools` 时，必须把每次返回的 `reasoning_content` 原样放回对应的 assistant 消息，否则返回 400。

## 接口

- `POST /v1/chat/completions`：支持 `model`、`messages`、`stream`、`max_tokens`、`temperature`、`top_p`、`stop`、`presence_penalty`、`frequency_penalty`。
- `GET /v1/models`：列出可用模型。
- 流式：`"stream": true` 返回 SSE，以 `data: [DONE]` 结束；最后一个数据事件 `choices` 为空并携带 `usage`。

## 计费

按 tokens 计费：输入 tokens × 输入单价 + 输出 tokens × 输出单价（单价见 /api/public/config 的 `models[].inputPerM` / `outputPerM`，单位 USD / 百万 tokens）。失败请求不计费；流式中途断开按已生成内容计费。余额以美元记账，人民币按 `cnyPerUsd` 折算。

## 错误码

错误格式与 OpenAI 一致：`{"error":{"message","type","code"}}`。

| HTTP | code | 处理 |
|---|---|---|
| 400 | `invalid_json` / `invalid_messages` / `context_length_exceeded` | 检查请求体或缩短上下文 |
| 401 | `missing_api_key` / `invalid_api_key` | 检查 Authorization 头 |
| 402 | `insufficient_balance` | 余额不足，回到第 2 步充值 |
| 403 | `spend_limit_exceeded` | 达到用户设置的月度上限 |
| 404 | `model_not_found` | model 只能是 lacia-creator 或 lacia-researcher |
| 429 | `rate_limit_exceeded` | 每个 Key 每分钟限速，指数退避后重试 |
| 502 / 503 | `upstream_error` / `upstream_overloaded` | 稍后重试，不计费 |

## 可选

- [人类可读的 API 文档](https://lacia.app/docs)
- [价格页](https://lacia.app/pricing)
- [服务条款与使用政策](https://lacia.app/terms)