StarAPI 接入文档
OpenAI 兼容协议,一个 Key 调用 50+ 模型。沿用你熟悉的 SDK,只改 base_url 与 api_key,即可完成迁移。
快速开始
三步完成第一次调用,所有示例均可直接复制,替换自己的 Key 即可运行:
- 注册并登录后,进入控制台「令牌」页面,点击「添加令牌」创建 API Key(以
sk-开头),复制保存 - 确认账户有可用额度(新用户注册即送体验额度,「总览」页可查余额)
- 从下方 curl 或 Python 示例中选一个,把
sk-xxxx替换成自己的 Key,直接运行
方式一:curl(任何终端可用,最快验证)
curl -X POST https://cloudapis.cloud/v1/chat/completions \ -H "Authorization: Bearer sk-你的密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "zai-org/GLM-5.3", "messages": [{"role": "user", "content": "你好"}] }'
返回 JSON 中 choices[0].message.content 就是模型回复。看到回复即说明 Key、网络、计费全部正常。
方式二:Python(OpenAI 官方 SDK)
# 先安装 SDK:pip install openai from openai import OpenAI client = OpenAI( api_key="sk-你的密钥", # ← 替换成控制台创建的令牌 base_url="https://cloudapis.cloud/v1" # ← StarAPI 接入地址,固定不变 ) resp = client.chat.completions.create( model="zai-org/GLM-5.3", # 任意可用模型,见「可用模型」章节 messages=[ {"role": "user", "content": "你好, StarAPI!"} ] ) print(resp.choices[0].message.content) # 打印模型回复 print(resp.usage.total_tokens) # 本次消耗的 Token 数
api_key 换成你的令牌;model 换成想用的模型名(完整名单见下方「可用模型」)。其余代码原样复制即可。zai-org/GLM-5.3、Qwen/Qwen3.5-35B-A3B,复制时请保留前缀和大小写,这是最常见的填错点。鉴权与地址
所有请求通过 HTTP Header 携带密钥:
Authorization: Bearer sk-starapi-xxxxxxxx Content-Type: application/json
| 接入方式 | Base URL | 说明 |
|---|---|---|
| HTTPS(推荐) | https://cloudapis.cloud/v1 | 经 Nginx 反代,支持 SSE,即开即用 |
https://cloudapis.cloud/v1,支持 SSE;SDK 与第三方工具直接填入即可调用。接口一览
| 接口 | 方法 | 用途 |
|---|---|---|
/v1/chat/completions | POST | 对话补全(核心,已验证可用) |
/v1/models | GET | 查询可用模型列表(已验证可用) |
/v1/embeddings | POST | 文本向量化(待向量模型上架) |
/v1/images/generations | POST | 图像生成(待图像模型上架) |
/v1/audio/speech | POST | 语音合成(待语音模型上架) |
对话补全
from openai import OpenAI client = OpenAI( api_key="sk-你的密钥", base_url="https://cloudapis.cloud/v1" ) resp = client.chat.completions.create( model="Qwen/Qwen3.5-35B-A3B", # 任意可用模型 messages=[ {"role": "system", "content": "你是一个专业的技术助理,回答简洁准确"}, {"role": "user", "content": "解释一下什么是 API 网关"} ], temperature=0.7, # 越高越发散,越低越稳定(0~2) max_tokens=1024 # 限制回复长度,控制成本 ) print(resp.choices[0].message.content)
三种消息角色
system:给模型设定身份与规则,放第一条,可选user:用户说的话assistant:模型之前的回复——想多轮对话,就把历史按顺序传回来
多轮对话完整示例
history = [
{"role": "system", "content": "你是一个耐心的编程助教"}
]
while True:
q = input("你: ")
if q in ("exit", "quit"):
break
history.append({"role": "user", "content": q})
resp = client.chat.completions.create(
model="zai-org/GLM-5.3",
messages=history
)
answer = resp.choices[0].message.content
print("AI:", answer)
# 关键:把模型回复也存入历史,模型才"记得"上文
history.append({"role": "assistant", "content": answer})
message.reasoning_content 是思考过程,message.content 才是最终答案;思维链 Token 同样计入用量,统计成本时请留意。流式输出(SSE)
加一个 stream=True,模型就会像打字机一样逐字返回,体感等待时间大幅缩短。StarAPI 已关闭 Nginx 缓冲,首字延迟极低:
from openai import OpenAI client = OpenAI( api_key="sk-你的密钥", base_url="https://cloudapis.cloud/v1" ) stream = client.chat.completions.create( model="zai-org/GLM-5.3", messages=[{"role": "user", "content": "写一首关于星辰的诗"}], stream=True # ← 只有这里和普通调用不同 ) full = "" for chunk in stream: delta = chunk.choices[0].delta.content if delta: # 跳过空片段(如角色/思维链块) full += delta print(delta, end="", flush=True) print() # 结束换行,full 即完整回复
resp.choices[0].message.content(那是非流式取法);每个 chunk 只有一小段 delta.content,自己拼接成完整文本即可。常用客户端接入
任何支持「自定义 OpenAI 接口地址」的 AI 客户端都能直接用 StarAPI,只需填 3 个参数:
| 参数 | 填什么 | 从哪获取 |
|---|---|---|
| API 地址 / Base URL | https://cloudapis.cloud/v1 | 固定值,直接复制 |
| API Key | sk-你的密钥 | 控制台「令牌」页创建 |
| 模型名 | 如 zai-org/GLM-5.3 | 下方「可用模型」或控制台「模型广场」 |
常见客户端配置位置
| 客户端 | 配置入口 |
|---|---|
| Cherry Studio | 设置 → 模型服务 → 添加 → 供应商选「OpenAI」→ 填入上表三项 |
| ChatBox | 设置 → 模型 → AI 模型提供方选「自定义添加」→ 填入上表三项 |
| LobeChat / NextChat | 设置 → 语言模型 → OpenAI → 打开「自定义 Base URL」→ 填入上表三项 |
| Dify / LangChain | 模型供应商 → OpenAI-API-compatible → 填入上表三项 |
/chat/completions,所以 Base URL 必须带 /v1 结尾;这是客户端接入最常见的填错点。可用模型(节选)
以下为各厂商代表模型,名称区分大小写、必须带厂商前缀,请整行完整复制:
| 模型名(完整复制) | 厂商 | 适用场景 |
|---|---|---|
zai-org/GLM-5.3 | 智谱 AI | 通用对话、推理,国内直连稳定 |
Qwen/Qwen3.5-35B-A3B | 阿里通义 | 中文对话、Agent、深度推理 |
deepseek-ai/DeepSeek-V3.2 | 深度求索 | 代码、数学推理 |
THUDM/GLM-4-32B-0414 | 智谱 AI | 轻量任务、批量处理,高性价比 |
zai-org/GLM-4.5V | 智谱 AI | 图文理解、视觉问答 |
inclusionAI/Ling-flash-2.0 | 蚂蚁百灵 | 快速对话、日常问答 |
sensenova-6.8-flash-lite | 商汤日日新 | 快速响应、中文创作 |
openai/gpt-6-astra | OpenAI | 旗舰通用对话 |
anthropic/claude-opus-5.5 | Anthropic | 长文写作、复杂代码 |
google/gemini-3.1-pro-preview | 超长上下文、多模态 | |
bytedance/doubao-seed-2-1-pro | 字节豆包 | 中文创作、营销文案 |
x-ai/grok-4.7 | xAI | 实时信息、推理 |
GET /v1/models 或在控制台「模型广场」查看全部 50+ 模型的价格与实时状态。部分海外旗舰模型依赖对应上游渠道余额,若调用返回 402 请先在控制台充值或改用国内模型。/v1/embeddings)与图像生成(/v1/images/generations)接口协议已就绪,待相应模型上架后即可按同样方式调用,可用性以「模型广场」为准。错误码说明
| 状态码 | 含义 | 处理建议 |
|---|---|---|
401 | 密钥无效或已删除 | 检查 Key 是否正确、是否被禁用;确认 Authorization: Bearer sk-... 格式无误 |
402 | 该模型上游渠道余额不足 | 改用国内模型(GLM / Qwen / DeepSeek 等),或等待对应渠道充值恢复 |
403 | 无权访问该模型 | 确认令牌的分组包含该模型,或联系管理员开通权限 |
429 | 触发限流或额度用尽 | 降低请求频率;检查令牌配额与账户余额 |
500 | 上游渠道异常 | 稍后重试;网关会自动切换渠道 |
503 | 所有渠道暂不可用 | 等待恢复,持续失败请反馈 |
error.message 文字说明(会直接指出原因),再对照本表;Python SDK 中错误信息在 openai.APIStatusError 异常里。常见问题
和直接调用官方 API 有什么区别?
协议与字段完全一致,区别在于:一个 Key 可用全部模型、多渠道自动容灾、统一计费与用量报表,无需逐家注册维护。
调用返回 402 "insufficient balance" 怎么回事?
这不是你的账户没余额,而是该模型对应的上游渠道临时余额不足(主要是部分海外旗舰模型)。两种解决方式:① 换用国内模型,如 zai-org/GLM-5.3、Qwen/Qwen3.5-35B-A3B,稳定可用;② 等待对应渠道充值后自动恢复,无需改代码。
报错 "model not found" / 模型不存在?
九成是模型名没带厂商前缀或大小写不对。正确示例:zai-org/GLM-5.3、Qwen/Qwen3.5-35B-A3B;先用 GET /v1/models 拿到精确名称,原样复制。
如何查看用量与消费明细?
登录控制台:总览看余额与趋势,「日志」页可查询每次调用的模型、Token 数与耗时,支持导出。
密钥泄露了怎么办?
立即在「令牌」页面删除该 Key 并新建;旧 Key 删除即刻失效,已泄露额度无法追回,请妥善保管。
SDK / 第三方工具怎么接入?
见「常用客户端接入」章节:API 地址填 https://cloudapis.cloud/v1,Key 填 StarAPI 令牌,模型名带厂商前缀,三步完成。Cherry Studio、ChatBox、LobeChat、Dify、LangChain 均验证可用。
为什么推荐使用 HTTPS 访问?
站点已启用受信任的 HTTPS 证书(Let's Encrypt),无需手动信任任何证书。统一使用 https://cloudapis.cloud/v1 即可,SDK 与第三方工具直接填入即可调用。