UnderSky 文档

快速开始

创建 UnderSky 账户、生成 API Key、充值使用额度,并使用 curl、Python 或 Node 发起第一次兼容 OpenAI 的请求。继续了解流式响应、JSON、工具调用、媒体工作流和生产环境恢复。

本教程会带你从注册账户开始完成第一次 API 调用。文本模型、图片、音频和社交数据接口都使用同一个基础地址和 API Key。

1. 创建账户

前往 Dashboard,使用 GitHub 或 Google 登录。

2. 获取 API Key

进入 Dashboard → Settings → API Keys,创建新的 Key。Key 以 sk- 开头。

请把 API Key 存在密钥管理器中。完整 Key 只会显示一次。

3. 查询公开模型

模型列表不需要认证,可以在配置凭据前查询:

curl -sS https://api.undersky.ai/v1/models | jq '.data[] | {id, name, pricing}'

访问模型目录查看易读的价格和端点链接。定价页还列出媒体和数据服务。

4. 在付费请求前充值并确认额度

进入 Dashboard → Settings → Credit & Usage 充值,并确认余额至少为 $0.10。网关会在开始付费请求前检查这个最低余额。

5. 发送对话请求

测试路由时使用 auto,也可以从公开模型目录选择 gpt-6-luna 等具体模型。

curl
curl -sS https://api.undersky.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Hello from UnderSky!"}]
  }'

响应会在 choices[0].message.content 返回助手内容,并包含用于计费的 usage 字段。

6. 使用 SDK

UnderSky 接受 OpenAI 客户端格式。只需要替换 base URL 和 API Key,原有请求代码可以继续使用。

先安装对应语言的 SDK:

Python
python -m pip install openai
Node.js
npm 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-6-luna",
    messages=[{"role": "user", "content": "Give me one deployment checklist item."}],
)
print(response.choices[0].message.content)

7. 流式响应

把 stream 设为 true 后,接口会通过 Server-Sent Events 持续返回结果。读取每行 data:,直到收到 [DONE]。

流式 curl 请求
curl -N https://api.undersky.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "stream": true,
    "messages": [{"role": "user", "content": "Count from one to three."}]
  }'

参阅流式与对话指南了解事件解析和工具调用。

8. JSON 与工具调用

需要机器可读结果时,使用 response_format 和 JSON schema。需要执行动作时,传入 tools 数组,并在服务端执行模型返回的函数。

JSON 响应格式
{
  "model": "gpt-6-luna",
  "messages": [{"role": "user", "content": "Return the deployment state."}],
  "response_format": {"type": "json_object"}
}

Chat API 参考列出了支持的请求字段和响应结构。

9. 生成图片

图片生成是异步流程。先创建任务,再轮询任务 ID,或者提供回调 URL。

curl -sS https://api.undersky.ai/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A clean abstract cloud over a blue horizon"}'

参阅图片生成指南和图片 API 参考,了解如何轮询任务 ID。

10. 处理错误和限流

把下面的响应视为可恢复或需要处理的状态:

  • 401 表示 API Key 缺失、无效、过期或已撤销。修正密钥后再请求。
  • 402 表示额度不足。进入 Dashboard → Settings → Credit & Usage 充值。
  • 429 表示请求过快。使用带随机抖动的指数退避,并限制重试次数。
  • 5xx 表示网关或上游失败。幂等请求可以重试,再查看服务状态。

发布重试逻辑前,请阅读错误码参考和速率限制指南。

11. 查询用量和状态

进入 Dashboard → Settings → Credit & Usage 查看余额和近期用量。服务状态页展示端点和供应商可用性。

服务集成可以使用带有 credits:read 权限的控制令牌:

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

12. 检查已安装的 CLI

如果已安装 undersky-cli,可以运行诊断:

undersky-cli doctor

终端指南说明 CLI 的获取条件,并提供更多 curl 示例。使用 curl 或 OpenAI SDK 即可完成本教程,无需安装 CLI。

13. 继续阅读 API 参考

目录