开发文档 · API Reference 首页 控制台 关于 安全 注册

StarAPI 接入文档

OpenAI 兼容协议,一个 Key 调用 50+ 模型。沿用你熟悉的 SDK,只改 base_url 与 api_key,即可完成迁移。

01 — QUICK START

快速开始

三步完成第一次调用,所有示例均可直接复制,替换自己的 Key 即可运行:

  1. 注册并登录后,进入控制台「令牌」页面,点击「添加令牌」创建 API Key(以 sk- 开头),复制保存
  2. 确认账户有可用额度(新用户注册即送体验额度,「总览」页可查余额)
  3. 从下方 curl 或 Python 示例中选一个,把 sk-xxxx 替换成自己的 Key,直接运行

方式一:curl(任何终端可用,最快验证)

终端直接执行(macOS / Linux / Windows PowerShell 均可)
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)

quickstart.py — 完整可运行
# 先安装 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,复制时请保留前缀和大小写,这是最常见的填错点。
02 — AUTH

鉴权与地址

所有请求通过 HTTP Header 携带密钥:

Authorization Header
Authorization: Bearer sk-starapi-xxxxxxxx
Content-Type: application/json
接入方式Base URL说明
HTTPS(推荐)https://cloudapis.cloud/v1经 Nginx 反代,支持 SSE,即开即用
推荐 HTTPS: 统一使用 https://cloudapis.cloud/v1,支持 SSE;SDK 与第三方工具直接填入即可调用。
03 — ENDPOINTS

接口一览

接口方法用途
/v1/chat/completionsPOST对话补全(核心,已验证可用)
/v1/modelsGET查询可用模型列表(已验证可用)
/v1/embeddingsPOST文本向量化(待向量模型上架)
/v1/images/generationsPOST图像生成(待图像模型上架)
/v1/audio/speechPOST语音合成(待语音模型上架)
兼容性: 以上接口与 OpenAI 官方协议字段一致,LangChain / LlamaIndex / Dify / Cherry Studio 等工具可直接接入;对话与模型列表接口当前即可用。
04 — CHAT

对话补全

chat.py — 完整可运行
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:模型之前的回复——想多轮对话,就把历史按顺序传回来

多轮对话完整示例

multi_turn.py
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})
推理模型说明: GLM-5.3、Qwen3.5 系列等推理模型会先输出思维链再回答,响应中的 message.reasoning_content 是思考过程,message.content 才是最终答案;思维链 Token 同样计入用量,统计成本时请留意。
05 — STREAMING

流式输出(SSE)

加一个 stream=True,模型就会像打字机一样逐字返回,体感等待时间大幅缩短。StarAPI 已关闭 Nginx 缓冲,首字延迟极低:

stream.py — 完整可运行
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,自己拼接成完整文本即可。
06 — CLIENTS

常用客户端接入

任何支持「自定义 OpenAI 接口地址」的 AI 客户端都能直接用 StarAPI,只需填 3 个参数:

参数填什么从哪获取
API 地址 / Base URLhttps://cloudapis.cloud/v1固定值,直接复制
API Keysk-你的密钥控制台「令牌」页创建
模型名如 zai-org/GLM-5.3下方「可用模型」或控制台「模型广场」

常见客户端配置位置

客户端配置入口
Cherry Studio设置 → 模型服务 → 添加 → 供应商选「OpenAI」→ 填入上表三项
ChatBox设置 → 模型 → AI 模型提供方选「自定义添加」→ 填入上表三项
LobeChat / NextChat设置 → 语言模型 → OpenAI → 打开「自定义 Base URL」→ 填入上表三项
Dify / LangChain模型供应商 → OpenAI-API-compatible → 填入上表三项
路径里的 /v1 不要漏: 客户端会自动在地址后拼接 /chat/completions,所以 Base URL 必须带 /v1 结尾;这是客户端接入最常见的填错点。
07 — MODELS

可用模型(节选)

以下为各厂商代表模型,名称区分大小写、必须带厂商前缀,请整行完整复制:

模型名(完整复制)厂商适用场景
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-astraOpenAI旗舰通用对话
anthropic/claude-opus-5.5Anthropic长文写作、复杂代码
google/gemini-3.1-pro-previewGoogle超长上下文、多模态
bytedance/doubao-seed-2-1-pro字节豆包中文创作、营销文案
x-ai/grok-4.7xAI实时信息、推理
完整实时列表: 调用 GET /v1/models 或在控制台「模型广场」查看全部 50+ 模型的价格与实时状态。部分海外旗舰模型依赖对应上游渠道余额,若调用返回 402 请先在控制台充值或改用国内模型。
向量 / 图像模型: 当前平台上架的是对话类模型;文本向量(/v1/embeddings)与图像生成(/v1/images/generations)接口协议已就绪,待相应模型上架后即可按同样方式调用,可用性以「模型广场」为准。
08 — ERRORS

错误码说明

状态码含义处理建议
401密钥无效或已删除检查 Key 是否正确、是否被禁用;确认 Authorization: Bearer sk-... 格式无误
402该模型上游渠道余额不足改用国内模型(GLM / Qwen / DeepSeek 等),或等待对应渠道充值恢复
403无权访问该模型确认令牌的分组包含该模型,或联系管理员开通权限
429触发限流或额度用尽降低请求频率;检查令牌配额与账户余额
500上游渠道异常稍后重试;网关会自动切换渠道
503所有渠道暂不可用等待恢复,持续失败请反馈
排查顺序: 先看返回的 error.message 文字说明(会直接指出原因),再对照本表;Python SDK 中错误信息在 openai.APIStatusError 异常里。
09 — FAQ

常见问题

和直接调用官方 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 与第三方工具直接填入即可调用。

智谱 GLM-5.3阿里 通义千问 3.5深度求索 DeepSeek-V3.2商汤 SenseNovaOpenAI GPT-6Anthropic ClaudeGoogle Gemini 智谱 GLM-5.3阿里 通义千问 3.5深度求索 DeepSeek-V3.2商汤 SenseNovaOpenAI GPT-6Anthropic ClaudeGoogle Gemini