Documentation

API 文档

用 AI 助手接入？把 /llms.txt 发给它，里面有完整的注册、充值和调用流程。

Lacia API 与 OpenAI Chat Completions 接口兼容。已有 OpenAI SDK 代码只需修改 base_url 与 api_key。

快速开始

注册账号并在控制台充值。
在控制台 → API Keys 创建密钥（只显示一次，请妥善保存）。
设置环境变量 LACIA_API_KEY，运行下面任一示例。

认证

所有 /v1 接口都需要在请求头中携带 API Key：

Authorization: Bearer sk-lacia-xxxxxxxxxxxxxxxx

请勿在前端代码、公开仓库或客户端 App 中暴露密钥。泄露后请立即在控制台删除并重新生成。

Base URL 与模型

Base URL

https://lacia.app/v1

协议

HTTPS，JSON，UTF-8

兼容

OpenAI Chat Completions（含流式）

Chat Completions

POST/v1/chat/completions

请求参数

参数	类型	说明
`model`	string，必填	`lacia-creator` 或 `lacia-researcher`
`messages`	array，必填	对话消息，每项包含 `role`（system / user / assistant）与 `content`
`stream`	boolean	是否以 SSE 流式返回，默认 false
`max_tokens`	integer	最大输出 tokens。不传时默认 32K；超过模型上限（384K）时自动截断为上限
`temperature`	number	0–2，越高越发散
`top_p`	number	核采样，0–1
`stop`	string \| array	停止序列
`presence_penalty` / `frequency_penalty`	number	-2–2，降低重复

请求示例

{
  "model": "lacia-creator",
  "messages": [
    {"role": "system", "content": "你是一位黑色幽默的叙述者。"},
    {"role": "user", "content": "开场白，两百字以内。"}
  ],
  "temperature": 0.9,
  "max_tokens": 800
}

响应示例

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "lacia-creator",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 42, "completion_tokens": 186, "total_tokens": 228}
}

流式输出

设置 "stream": true，响应为 text/event-stream。每个事件形如 data: {...}，增量文本在 choices[0].delta.content，以 data: [DONE] 结束。最后一个数据事件的 choices 为空数组并携带 usage。

思考模式

两种模式的思考行为是固定的，请求中传入的 thinking、reasoning_effort、chat_template_kwargs 等字段会被忽略。

模型	思考模式	说明
`lacia-creator`	关闭	直接输出正文，首字更快，适合创作与对话
`lacia-researcher`	开启	先推理再回答，适合复杂分析与代码任务

Researcher 的思考过程在 message.reasoning_content（流式时为 delta.reasoning_content）中返回，最终答案仍在 content。思考内容计入 completion_tokens 并按输出单价计费，也占用 max_tokens 额度。多轮对话时把 content 放回 messages 即可；如果请求带了 tools（工具调用），需要把每次返回的 reasoning_content 原样放回对应的 assistant 消息，否则会返回 400。

用量统计

每个成功响应都包含 usage 字段：

prompt_tokens

输入 tokens，按输入单价计费

completion_tokens

输出 tokens，按输出单价计费

total_tokens

两者之和

控制台的「用量统计」按天与模型汇总，「请求日志」可查看每次请求的 tokens、费用、耗时和状态。极少数情况下模型服务未返回 usage，系统会按字符数估算并在日志中标注「估算」。

列出模型

GET/v1/models

curl https://lacia.app/v1/models -H "Authorization: Bearer $LACIA_API_KEY"

错误码

错误响应与 OpenAI 格式一致：

{"error": {"message": "账户余额不足，请前往控制台充值", "type": "insufficient_quota", "code": "insufficient_balance"}}

HTTP	code	原因与处理
400	`invalid_json` / `invalid_messages`	请求体格式错误，检查 JSON 与 messages
400	`context_length_exceeded`	输入过长，缩短上下文
401	`missing_api_key` / `invalid_api_key`	缺少或无效的 API Key
402	`insufficient_balance`	余额不足，充值后重试
403	`spend_limit_exceeded`	达到你设置的每月消费上限
404	`model_not_found`	model 参数不正确
429	`rate_limit_exceeded`	超出每分钟请求数，指数退避后重试
502	`upstream_error`	模型服务异常，可重试，不计费
503	`upstream_overloaded`	模型服务繁忙，稍后重试，不计费

速率与限额

速率限制按 API Key 和模式分别计算，见下表。需要更高配额请联系我们。
可在控制台设置每月消费上限，达到后请求返回 403，下月自动恢复。
可设置低余额提醒，余额低于阈值时控制台会显示提醒。