终端与 curl | UnderSky 文档

通过 GET /v1/models 发现模型，用 curl 调用 OpenAI 兼容端点、处理流式响应，并使用 Python SDK 对接 api.undersky.ai。

通过 https://api.undersky.ai 使用常规 HTTP 工具即可接入。在 Dashboard 创建 API Key、充值并管理账户。

UnderSky CLI（账户工具）

安装 undersky-cli / usai，用于登录、doctor 与控制面辅助：

curl -fsSL https://raw.githubusercontent.com/leaperone/UnderSky/main/scripts/install-cli.sh | sh

更新可执行 undersky-cli upgrade，或重新运行安装脚本。预编译包发布在 GitHub Releases 的 cli-v* 标签（linux/macOS，x64 与 arm64），附带 SHA256SUMS。若仓库为私有，安装与 upgrade 需设置具有 contents:read 的 GH_TOKEN（或 GITHUB_TOKEN）。

设置 API Key

在 shell 中导出模型 API Key，便于重复运行示例：

export UNDERSKY_API_KEY="sk-your-api-key"

请勿将真实 API Key 提交到代码仓库。若 Key 泄露，请在 Dashboard → Settings → API Keys 中轮换。

发现模型与端点

以下公开目录接口无需鉴权：

curl -sS https://api.undersky.ai/v1/models | jq '.data[] | {id, owned_by}'
curl -sS https://api.undersky.ai/openapi.json | jq '.paths | keys[:10]'

完整参考见 undersky.ai/docs。

Chat Completion

curl -sS https://api.undersky.ai/v1/chat/completions \
  -H "Authorization: Bearer $UNDERSKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-nano",
    "messages": [{"role": "user", "content": "Hello!"}]
  }' | jq '.choices[0].message.content'

流式响应

curl -N https://api.undersky.ai/v1/chat/completions \
  -H "Authorization: Bearer $UNDERSKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-nano",
    "stream": true,
    "messages": [{"role": "user", "content": "数到三。"}]
  }'

OpenAI SDK（Python）

pip install openai

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.undersky.ai/v1",
)

response = client.chat.completions.create(
    model="gpt-5-nano",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

点数与用量

余额与用量记录在 Dashboard → Settings → Credit & Usage 查看。已持有 scoped 控制令牌（lpc_…）的服务端集成可查询余额：

curl -sS https://api.undersky.ai/api/v1/credits/balance \
  -H "Authorization: Bearer lpc-your-control-token" | jq

脚本建议

用 jq 处理 JSON，用 -w "%{http_code}" 记录 HTTP 状态码，遇到 429 时退避重试。只解析响应体；不要将 API 错误与 shell 的 stderr 混为一谈。