快速开始
创建 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 -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 -m pip install openainpm install openaifrom 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 -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 数组,并在服务端执行模型返回的函数。
{
"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。