接入文档 · LunFlux API

01 · 获取账户，创建密钥

当前不开放自助注册。通过你的邀请人申请账户，并获取管理员提供的初始登录信息。
前往个人设置修改初始密码。登录凭据与 API 密钥用途不同，请分别保管。
前往 API 密钥创建令牌。选择适合模型的分组，并配置有限额度、有效期和模型限制；固定服务器可配置 IP 白名单。
令牌分组会影响可用模型和费用。多种分组请分别创建令牌，避免无意切换。

新用户先用小额额度测试。请勿把 API 密钥放入前端网页、公开代码仓库或聊天截图。

02 · 接口地址与第一条请求

OpenAI 兼容客户端的 Base URL 为 https://api.lunflux.com/v1。请求鉴权使用 Authorization: Bearer YOUR_API_KEY。避免客户端重复追加 /v1。

查询当前密钥可用的模型

export LUNFLUX_API_KEY='替换为你的API密钥'
curl --fail-with-body https://api.lunflux.com/v1/models \
  -H "Authorization: Bearer $LUNFLUX_API_KEY"

模型目录展示的信息与当前令牌实际权限可能不同。请从返回的模型 ID 中选择；模型存在于列表也不代表支持全部端点或参数。

调用支持 Chat Completions 的模型

export MODEL_NAME='从模型列表选择支持聊天的模型'
LUNFLUX_REQUEST_FILE=$(mktemp)
python3 - <<'PY' > "$LUNFLUX_REQUEST_FILE"
import json, os
print(json.dumps({
    "model": os.environ["MODEL_NAME"],
    "messages": [{"role": "user", "content": "你好，请简短回复"}],
    "max_tokens": 64
}))
PY
curl --fail-with-body https://api.lunflux.com/v1/chat/completions \
  -H "Authorization: Bearer $LUNFLUX_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @"$LUNFLUX_REQUEST_FILE"
rm -f "$LUNFLUX_REQUEST_FILE"

此示例需要 Python 3 和支持 --fail-with-body 的 curl。部分模型使用 Responses、Messages 或图像端点，请按模型实际兼容性选择；max_tokens 等参数也可能需要调整。

03 · 客户端设置与流式响应

在支持自定义 OpenAI 服务的客户端中填写上述 Base URL、API Key 和准确的模型 ID。遇到端点不兼容，先确认模型支持的协议，再调整调用方式。

# 安装 Python 的 openai 客户端后
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LUNFLUX_API_KEY"],
    base_url="https://api.lunflux.com/v1",
    max_retries=0,  # 初次测试避免客户端重复重试
)
stream = client.chat.completions.create(
    model=os.environ["MODEL_NAME"],
    messages=[{"role": "user", "content": "你好，请简短回复"}],
    max_tokens=64,
    stream=True,
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)

流式请求请使用支持 SSE 的客户端。收到部分输出后连接中断，不要立即整条重发；先核对调用记录，避免重复请求产生额外费用。

04 · 充值与计费核对

在钱包查看余额和当前可用的充值方式。先充值小额测试，实际支付金额以收银台为准。
支付后返回钱包确认到账。若未到账，保留订单号、金额、支付时间和支付凭证，通过邀请人联系管理员核查；不要反复创建订单。
请求前查看模型与价格，留意分组、币种和计价单位。文本可能区分输入、输出及缓存，图片或任务可能按次或专门规则计费。
请求后在调用记录核对模型、令牌、用量与扣费。密钥额度与账户余额是不同限制，两者都需要足够。

当前低价属于试运营策略，后续价格可能调整。以调用时平台生效的价格配置及记录为准；暂无统一公开的补偿或退款承诺。退款申请由管理员依据订单和实际余额核查处理。

05 · 限流与使用建议

试运营设置每用户每分钟最多 600 次总请求、300 次成功请求；Free 分组为 60 次总请求、30 次成功请求。上游可能另有限流，具体以返回信息为准。

计数按用户共享，更换密钥不会获得独立额度。混用分组时，以当前请求分组的阈值判断共享计数。应用请控制并发，遇到 429 按退避策略等待，并遵循返回的重试提示。

每个应用使用独立密钥。生产业务建议保留可替换的服务地址和模型配置，并先在低流量场景验收。

06 · 常见错误与排查

现象	优先检查
401 / 403	密钥、有效期、模型授权、IP 白名单和令牌分组。无需对鉴权错误持续重试。
余额 / 额度不足	账户余额与密钥剩余额度；按实际错误信息判断，HTTP 状态码可能因端点而异。
400 / 404	Base URL、模型 ID、端点和参数兼容性；图片模型不能直接当作聊天模型使用。
429	用户请求限制或上游限流。降低并发并指数退避，避免立即连续重发。
5xx / 超时 / 中断	查看网关状态，保存请求 ID；核对调用记录后再决定是否重试。
支付成功未到账	钱包记录、订单号与支付凭证。由管理员核查，不凭截图直接补余额。

提交问题时提供这些信息

当前通过邀请人转交管理员：发生时间（含时区）、模型、令牌分组、端点、HTTP 状态码、错误摘要，以及响应头 X-Oneapi-Request-Id 或错误信息中的请求 ID。支付问题附订单号。请删除密钥、密码和敏感输入。

网关状态页只反映站内网关探测，不能代表每个上游模型的实时可用性。尚未提供独立公网探测或对外 SLA。

07 · 保护凭据与业务数据

通过 HTTPS 调用，密钥仅存于服务端环境变量或密钥管理服务。怀疑泄露时立即禁用并更换令牌，在调用记录中核查异常用量。

请求内容需要转发至所选模型的上游服务，数据处理也受上游规则影响。正式隐私政策、运营主体和专门客服渠道仍在筹备；试运营请避免提交敏感个人信息、商业机密及受限制的数据。

本平台的源项目为 New API v1.0.0-rc.43。接口适配不等同于模型厂商的官方服务承诺。