快速开始

3 步完成接入

OpenStarry 完全兼容 OpenAI / Anthropic API 格式，无需改变工具链，只需替换 Base URL 和 API Key 即可。

1

订阅套餐

注册 OpenStarry 账号，选择适合的套餐。新用户注册即送体验额度，无需绑卡。

查看套餐 →

2

获取 API Key 与 Base URL

进入控制台创建 API Key，并根据所用工具选择对应端点：

OpenAI 兼容

https://api.openstarry.com/v1

Anthropic 兼容

https://api.openstarry.com

API Key 格式为 sk- 开头（例：sk-xxxxxxxxxxxxxxxx），在控制台 → API Keys 中创建。

3

接入 AI 工具

选择你使用的工具，按文档配置即可立即开始使用 OpenStarry 提供的全部模型。

模型列表

可用模型

在请求的 model 参数中填入以下模型 ID 即可调用。

⚠️ 本站禁止中国大陆地区用户调用 Claude、ChatGPT、Gemini 等境外 AI 模型。如用户违反用户协议私自调用，平台发现后将封禁对应 API Key，充值余额不退还。

💱

人民币定价 · 汇率按 1 USD = 7.0 CNY · 与官方定价完全一致，0 加价

模型名称	提供商	输入价格 /1M tokens	输出价格 /1M tokens
Anthropic
glm-5.1 / glm-5.1-turbo	Anthropic	¥35.0	¥175.0
claude-sonnet-4-6	Anthropic	¥21.0	¥105.0
OpenAI
gpt-5.5-pro / gpt-5.4-pro	OpenAI	¥210.0	¥1260.0
gpt-5.5	OpenAI	¥35.0	¥210.0
gpt-5.4	OpenAI	¥17.5	¥105.0
Google
gemini-3.1-pro	Google	¥14.0	¥84.0
gemini-3-flash	Google	¥3.5	¥21.0
DeepSeek
deepseek-v4-pro	DeepSeek	¥3.0	¥6.0
deepseek-v4-flash	DeepSeek	¥1.0	¥2.0
deepseek-v3.2	DeepSeek	¥1.4	¥5.6
Moonshot (Kimi)
kimi-k2.6	Moonshot	¥6.5	¥27.0
kimi-k2.5	Moonshot	¥4.0	¥21.0
智谱 AI (GLM)
glm-5.1	智谱 AI	¥9.8	¥30.8
glm-5	智谱 AI	¥7.0	¥22.4
glm-5-turbo	智谱 AI	¥8.4	¥28.0
MiniMax
minimax-m2.7 / minimax-m2.5	MiniMax	¥2.1	¥8.4
minimax-m2.7-highspeed / minimax-m2.5-highspeed	MiniMax	¥4.2	¥16.8
Alibaba (Qwen)
qwen3.6-plus	Alibaba	¥2.31	¥13.65
Xiaomi (MiMo)
mimo-v2.5-pro / mimo-v2-pro	Xiaomi	¥1.4	¥21.0
mimo-v2.5	Xiaomi	¥0.56	¥2.80

语言 SDK

Python 接入

推荐使用官方 OpenAI Python SDK，完全兼容。

bash

pip install openai

同步调用

Python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.openstarry.com/v1",
    api_key=os.environ.get("OPENSTARRY_API_KEY"),
)

# 普通对话
resp = client.chat.completions.create(
    model="glm-5.1",
    messages=[{"role": "user", "content": "用 Python 写一个快速排序"}],
    temperature=0.7,
    max_tokens=2048,
)
print(resp.choices[0].message.content)

流式输出

Python · Streaming
with client.chat.completions.stream(
    model="glm-5.1",
    messages=[{"role": "user", "content": "讲一个故事"}],
) as stream:
    for chunk in stream:
        delta = chunk.choices[0].delta
        if delta.content:
            print(delta.content, end="", flush=True)

Node.js 接入

bash

npm install openai

TypeScript / JavaScript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.openstarry.com/v1',
  apiKey: process.env.OPENSTARRY_API_KEY,
});

const response = await client.chat.completions.create({
  model: 'glm-5.1',
  messages: [{ role: 'user', content: 'Hello!' }],
});

console.log(response.choices[0].message.content);

cURL 直接调用

Shell
curl https://api.openstarry.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.1",
    "messages": [
      {"role": "user", "content": "你好"}
    ],
    "max_tokens": 1024
  }'

Go 接入

Go
import (
    "github.com/sashabaranov/go-openai"
)

config := openai.DefaultConfig("sk-your-key-here")
config.BaseURL = "https://api.openstarry.com/v1"
client := openai.NewClientWithConfig(config)

resp, err := client.CreateChatCompletion(ctx,
    openai.ChatCompletionRequest{
        Model: "glm-5.1",
        Messages: []openai.ChatCompletionMessage{
            {Role: openai.ChatMessageRoleUser, Content: "你好"},
        },
    },
)

高级功能

流式输出（Streaming）

通过 SSE（Server-Sent Events）实现实时流式响应，支持所有模型。

Python · Stream
for chunk in client.chat.completions.create(
    model="glm-5.1",
    messages=[{"role": "user", "content": "写一篇文章"}],
    stream=True,
):
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

错误码说明

HTTP 状态码	错误码	说明	处理建议
`400`	invalid_request	请求参数格式错误	检查 model、messages 格式
`401`	invalid_api_key	API Key 无效或过期	检查 Key 是否正确，是否已过期
`402`	insufficient_quota	余额不足或超出额度	前往控制台充值或升级套餐
`429`	rate_limit_exceeded	请求频率超出限制	实现指数退避重试，或升级套餐
`500`	internal_error	服务器内部错误	稍后重试；持续出现请联系支持
`503`	model_unavailable	指定模型暂时不可用	系统会自动 Failover，或手动切换模型

客户端 / 开发工具

接入客户端与开发工具

OpenStarry 兼容 OpenAI API 协议，任何支持自定义 API 端点的 AI 客户端或编程工具均可直接接入。所有工具的配置只需三个参数：

参数	值	说明
API Base URL	`https://api.openstarry.com/v1`	所有工具统一使用此地址
API Key	你的 OpenStarry API Key	在 Dashboard → API Keys 获取
模型名称	如 `glm-5.1`	参见快速开始中的完整模型列表

💡

按次计费套餐（星序版 / 星衍版 / 星途版，即 Coding Plan）适合 IDE 编程工具（Cursor、Cline、Claude Code 等）；按量计费（Token Plan）适合对话客户端（Chatbox、Cherry Studio）和工作流平台（Dify）。

Cursor

Cursor 是目前最流行的 AI 编程 IDE，基于 VS Code 深度定制，内置 Tab 补全、Composer 多文件编辑、Chat 问答等功能。通过配置自定义模型端点，可将 OpenStarry 接入 Cursor 的所有 AI 功能。

配置步骤

打开 Cursor，进入 Settings（⌘,）→ Models
在 OpenAI API Key 字段填入你的 OpenStarry API Key
展开 Override OpenAI Base URL，填入：https://api.openstarry.com/v1
点击 Verify 验证连接成功
在模型列表中点击 + Add model，输入模型 ID（如 glm-5.1）
在 Chat / Composer 中选择你添加的模型即可使用

ℹ️

Cursor 免费版用户通过此方式配置后，使用 OpenStarry 的模型不会消耗 Cursor 自身的配额，按 OpenStarry 计费规则扣费。

Claude Code

Claude Code 是 Anthropic 官方发布的终端 AI 编程工具，支持读写项目文件、执行 Shell 命令、调用 MCP 工具，适合复杂的端到端开发任务。通过 OpenStarry 接入后，可使用 Claude 系列及其他多家模型。

配置步骤

安装 Claude Code：npm install -g @anthropic-ai/claude-code
设置环境变量（推荐写入 ~/.zshrc 或 ~/.bashrc）：

bash

# OpenStarry 接入配置
export ANTHROPIC_API_KEY="sk-your-key-here"
export ANTHROPIC_BASE_URL="https://api.openstarry.com"

重新加载配置后运行 claude 启动，默认使用 GLM-5.1
可通过 claude --model claude-sonnet-4-6 指定模型

⚡

推荐按次计费配合 Claude Code 使用，适合每日深度开发场景，成本可控且无需关注 Token 用量。

Cline（VS Code 插件）

Cline 是 VS Code 中最受欢迎的开源 AI 编程插件，支持自动读写文件、执行终端命令、调用浏览器，可完成完整的功能开发流程。同类插件还有 Kilo Code、Roo Code，配置方式完全相同。

配置步骤

在 VS Code 扩展市场搜索并安装 Cline
点击侧边栏 Cline 图标，进入 Settings（齿轮图标）
API Provider 选择 OpenAI Compatible
Base URL 填入：https://api.openstarry.com/v1
API Key 填入你的 OpenStarry API Key
Model ID 填入模型名，如 glm-5.1
点击 Save，在聊天框输入任务即可开始

TRAE

TRAE 是字节跳动推出的 AI IDE（trae.ai），支持自定义模型服务商，可接入 OpenStarry 使用全部模型。

TRAE IDE 配置

打开 TRAE IDE → Settings → AI → Custom Provider
Base URL 填入：https://api.openstarry.com/v1
API Key 填入你的 OpenStarry API Key
选择或输入模型 ID（如 glm-5.1）

Trae Agent（CLI）配置

yaml · ~/.trae-agent/config.yaml

llm:
  model: glm-5.1
  api_base: https://api.openstarry.com/v1
  api_key: your-openstarry-key

ℹ️

TRAE IDE 目前提供免费 Claude/GPT 配额；配置自定义端点后可使用你自己的 OpenStarry 模型，不受官方免费额度限制。

OpenCode

OpenCode 是开源的终端 AI 编程工具，通过 JSON 配置文件接入 OpenAI 兼容端点。

配置步骤

安装：npm install -g opencode-ai 或从 opencode.ai 下载
在项目根目录创建 opencode.json：

json · opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openstarry": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OpenStarry",
      "options": {
        "baseURL": "https://api.openstarry.com/v1",
        "apiKey": "${OPENSTARRY_API_KEY}"
      },
      "models": {
        "glm-5.1": { "name": "GLM-5.1" },
        "gpt-4o": { "name": "GPT-4o" },
        "deepseek-v4-flash": { "name": "DeepSeek V4 Flash" }
      }
    }
  }
}

设置环境变量：export OPENSTARRY_API_KEY=your-key
在项目目录运行 opencode 启动

Codex

OpenAI Codex CLI 是命令行 AI 编程助手，通过配置文件可接入任何 OpenAI 兼容端点。

配置步骤

安装（需要 Node 22+）：npm install -g @openai/codex
创建配置文件 ~/.codex/config.toml：

toml · ~/.codex/config.toml

model = "glm-5.1"
[provider]
base_url = "https://api.openstarry.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"

设置环境变量：export OPENAI_API_KEY=your-openstarry-key
在项目目录运行 codex，支持 --model 参数切换模型

Kilo CLI

Kilo CLI 是 Kilo Code 的终端版本，支持 OpenAI 兼容端点配置。

配置步骤

安装：npm install -g kilocode
创建配置文件 ~/.kilo/config.json：

json · ~/.kilo/config.json

{
  "apiProvider": "openai-compatible",
  "baseUrl": "https://api.openstarry.com/v1",
  "apiKey": "your-openstarry-key",
  "model": "glm-5.1"
}

在终端运行 kilo 或 kilocode 启动

ArkClaw

ArkClaw 是字节跳动 Ark 平台的 AI 编程 Agent，基于 OpenClaw 架构，支持自定义 OpenAI 兼容端点。

配置步骤

安装：从 Ark 平台下载，或 pip install arkclaw
创建配置文件 ~/.arkclaw/config.json：

json · ~/.arkclaw/config.json

{
  "provider": {
    "type": "openai-compatible",
    "base_url": "https://api.openstarry.com/v1",
    "api_key": "your-openstarry-key"
  },
  "model": "glm-5.1"
}

Kilo Code

Kilo Code 是 VS Code 的 AI 编程插件，配置方式与 Cline 完全相同。

配置步骤

在 VS Code 扩展市场搜索并安装 Kilo Code
Activity Bar → Kilo Code → 点击设置（齿轮图标）
API Provider 选择 OpenAI Compatible
Base URL 填入：https://api.openstarry.com/v1
API Key 填入你的 OpenStarry API Key
Model ID 填入 glm-5.1 或其他模型
保存后即可使用

Qwen Code

Qwen Code 是阿里云推出的 VS Code AI 编程插件，支持代码补全、Chat 和 Agent 任务，可配置自定义 API 端点。

配置步骤

在 VS Code 扩展市场搜索 Qwen Code 并安装，或从阿里云扩展市场安装
打开插件设置，将 API Endpoint 设置为 https://api.openstarry.com/v1
API Key 填入你的 OpenStarry API Key
从列表选择模型或手动输入模型 ID
支持代码补全、对话问答和 Agent 任务，对中文内容友好

通义灵码

通义灵码（TONGYI Lingma）是阿里云推出的 AI 编程助手，支持 VS Code 和 JetBrains 系列 IDE，可配置自定义 API 端点。

配置步骤

在 VS Code 扩展市场搜索 TONGYI Lingma 并安装
使用阿里云账号登录以获得完整功能
设置 → Lingma → API Configuration → Custom Endpoint
Base URL 填入：https://api.openstarry.com/v1
API Key 填入你的 OpenStarry API Key

💡

通义灵码与 Qwen 系列模型配合效果最佳。建议代码场景使用 qwen3.6-plus 或 qwen-coder-turbo。

Qoder

Qoder 是 VS Code 的 AI 编程插件，支持 OpenAI 兼容的自定义端点配置。

配置步骤

在 VS Code 扩展市场搜索并安装 Qoder
点击侧边栏齿轮图标进入设置
Provider 选择 OpenAI Compatible
Base URL 填入：https://api.openstarry.com/v1
API Key 填入你的 OpenStarry API Key
Model 填入 glm-5.1 或 gpt-4o

Cherry Studio

Cherry Studio 是开源的桌面 AI 对话客户端，支持多服务商、多模型管理，可同时开启多个对话窗口进行对比，适合日常问答、写作、翻译等场景。

配置步骤

从 cherry-ai.com 下载并安装
打开 设置 → 模型服务，点击 + 添加
供应商类型选择 OpenAI，名称填写 OpenStarry
API 地址 填入：https://api.openstarry.com/v1
API Key 填入你的 OpenStarry API Key
点击 管理模型，手动添加模型 ID（如 glm-5.1、gpt-4o、deepseek-v4-flash）
返回首页选择该服务商下的模型开始对话

Chatbox

Chatbox 是轻量级的跨平台 AI 对话桌面客户端（Windows / macOS / Linux / iOS / Android），界面简洁，配置简单，适合快速上手。

配置步骤

从 chatboxai.app 下载安装对应平台版本
进入 设置 → AI 模型
AI 提供商 选择 OpenAI API
API 域名 填入：https://api.openstarry.com（不含 /v1，Chatbox 会自动拼接）
API Key 填入你的 OpenStarry API Key
模型填入模型 ID，如 glm-5.1
保存后在主界面选择模型开始对话

ℹ️

Chatbox 的 API 域名字段不含路径，填写时去掉末尾的 /v1，Chatbox 会自动拼接。

OpenClaw

OpenClaw 是支持自定义 LLM 后端的 AI 编程 Agent，支持文件编辑、终端命令、Web 搜索等能力。

配置步骤

安装：npm install -g openclaw 或从 openclaw.ai 下载
配置 ~/.openclaw/openclaw.json 或运行 openclaw dashboard 进行图形配置：

json · ~/.openclaw/openclaw.json

{
  "agents": {
    "default": {
      "provider": "openstarry",
      "model": "glm-5.1"
    }
  },
  "providers": {
    "openstarry": {
      "type": "openai-compatible",
      "baseUrl": "https://api.openstarry.com/v1",
      "apiKey": "your-openstarry-key"
    }
  }
}

运行 openclaw 启动 Agent

Hermes Agent

Hermes 是基于 OpenAI 兼容 API 的 AI Agent 框架，通过修改 base_url 即可接入 OpenStarry，无需改动业务代码。

Python 接入

python

from hermes import Agent

agent = Agent(
    base_url="https://api.openstarry.com/v1",
    api_key="your-openstarry-key",
    model="glm-5.1"
)

环境变量方式

bash

export OPENAI_BASE_URL=https://api.openstarry.com/v1
export OPENAI_API_KEY=your-openstarry-key

Coze（扣子）

Coze 是字节跳动推出的 AI Bot 搭建与工作流编排平台，支持对话 Bot、工作流、知识库、插件等功能，适合快速构建 AI 应用。通过配置自定义模型端点，可在 Coze 中使用 OpenStarry 全部模型。

配置步骤（自定义模型 API）

进入 coze.cn，登录后进入 工作空间 → 设置 → 模型
点击 添加自定义模型
API 协议 选择 OpenAI
Base URL 填入：https://api.openstarry.com/v1
API Key 填入你的 OpenStarry API Key
模型名称 填入模型 ID，如 glm-5.1 或 gpt-4o
保存后，在 Bot 编排页面的模型下拉框中选择该自定义模型即可

💡

Coze 国际版（coze.com）同样支持自定义模型配置，流程与国内版相同。建议中国用户使用 coze.cn 以获得更稳定的访问速度。

ℹ️

若需在 Coze 工作流中批量调用模型，建议使用 按量计费 套餐，避免按次计费的并发限制。

OpenViking

OpenViking 是轻量级开源 AI 编程助手，通过环境变量配置接入任何 OpenAI 兼容端点。

配置步骤

bash

export OPENAI_API_KEY=your-openstarry-key
export OPENAI_BASE_URL=https://api.openstarry.com/v1

在项目目录运行 openviking 启动

Dify

Dify 是开源的 AI 工作流与应用构建平台，支持 RAG、Agent、工作流编排等场景，适合将 AI 能力嵌入业务系统。通过 OpenStarry 接入，可在 Dify 中使用 Claude、GPT-4o、DeepSeek 等全部模型。

配置步骤（云端版 / 自托管均适用）

进入 Dify → 设置（右上角）→ 模型供应商
找到 OpenAI-API-compatible，点击配置
API Key 填入你的 OpenStarry API Key
API Endpoint 填入：https://api.openstarry.com/v1
点击保存，在模型列表中添加需要的模型 ID
在 App 或 Workflow 中选择该供应商下的模型作为推理引擎

💡

可将 Claude、GPT-4o、DeepSeek 等全部模型添加到同一个 OpenStarry 供应商下，统一计费，无需分别配置。

Postman

Postman 是最常用的 API 调试工具，适合测试提示词效果、验证接口返回格式、调试工具调用（Function Calling）等。

配置步骤

新建 HTTP Request，方法选 POST
URL 填入：https://api.openstarry.com/v1/chat/completions
Headers 添加：Authorization: Bearer your-openstarry-key 和 Content-Type: application/json
Body → raw → JSON 填入：

json

{
  "model": "glm-5.1",
  "messages": [{"role": "user", "content": "你好"}],
  "stream": false
}

点击 Send，响应中的 choices[0].message.content 即为模型回复
流式模式：将 "stream": true 后读取 SSE 事件

FAQ

常见问题

本文档页汇总开发者在接入 OpenStarry 过程中最高频遇到的问题。本页内容与首页 FAQ 同步更新，按主题分为 4 类：热门问题 · 计费套餐 · 技术接入 · 安全合规。点击问题可展开答案。

计费套餐

模型费用是官方价吗？有最低消费吗？

模型调用费完全透传官方价，0 加价，无最低消费。账单页面展示每笔明细含原始汇率换算（1 USD ≈ 7 CNY）。

Coding Plan（按次计费）和 Token Plan（按量计费）怎么选？

探索期或低频使用推荐 Coding Plan（按次计费，¥9.9/周起）；月请求量超过 50 万次或需要旗舰大模型，推荐 Token Plan（按量计费），成本更可控。详见计费说明。

充值后余额会过期吗？

按量计费充值余额永久有效，不会过期。赠送的免费额度永久有效，无使用期限限制。

有没有团队版或企业版套餐？可以开发票吗？

支持团队版与企业服务，可开具国内增值税专用发票或普通发票。联系商务邮箱 service@openstarry.com 获取报价与定制方案。

技术接入

支持哪些编程语言和 SDK？

完全兼容 OpenAI SDK 格式（业界标准），Python、Node.js、Go、Java、curl 等均可直接使用，只需替换 base_url 为 https://api.openstarry.com/v1，无需任何适配工作。完整示例见 SDK 文档。

API 端点是什么？怎么调用不同大模型？

统一端点 https://api.openstarry.com/v1，通过请求体中的 model 参数切换不同大模型（如 glm-5-1、deepseek-v4、kimi-k2.6、MiniMax-m3、qwen3.6-plus），不用换 base_url。详细参数见模型列表。

怎么从其他 AI 平台迁移到 OpenStarry？

只需把 base_url 改为 https://api.openstarry.com/v1，API Key 换为 OpenStarry Key（sk- 开头），零代码改动。所有现有的代码（Python、Node.js、Go、Java、curl 等）继续运行，只是请求会被路由到 OpenStarry 后端。

支持流式输出（Streaming）/ Function Calling / Vision 吗？

全部支持。流式输出通过 stream=true 启用；Function Calling / Tools 与 OpenAI 规范完全一致；Vision 通过 image_url content type 上传。详见流式输出文档。

单次调用真的只要一分钱吗？哪些模型这么便宜？

是的。GLM 5.1 / Kimi K2.6 / DeepSeek V4 / MiniMax M3 等国产旗舰大模型在 Coding Plan 下，单次调用价格低至 1 分钱，是国内性价比最高的大模型聚合方案。同档位的国际旗舰模型价格通常高出 10-100 倍，OpenStarry 国产方案成本可降低 90% 以上。完整模型定价见模型列表与价格。

可以自选套餐吗？比如指定模型、调用次数？

支持。除星序 / 星衍 / 星途三个标准 Coding Plan 套餐外，还可根据需求自选套餐：自由指定模型范围（如仅 GLM 5.1 + DeepSeek V4）与调用次数（1 万 / 10 万 / 50 万等）。有效期统一为 1 个月（计算器中的"周 / 月 / 季"仅用于估算次数，不影响有效期）。100 次起定制，企业团队享专属折扣。联系 service@openstarry.com 获取报价。

安全合规

我的对话内容会被存储吗？数据安全吗？

默认不存储任何请求/响应内容，仅记录计费元数据（时间、模型、Token 数量、状态码），所有日志 30 天后自动清除。TLS 1.3 全链路加密，ICP 备案，可开具增值税专用发票。详见数据安全说明。

API Key 泄露了怎么办？怎么撤销或重置？

立刻在 Dashboard → API Keys 页面点击对应 Key 右侧的「撤销」按钮，旧 Key 立即失效。然后创建新 Key 并在应用中替换。OpenStarry 提供完整的 Key 使用审计日志（最近调用 IP、时间、模型、Token 数），可在 Dashboard 一键识别异常调用。如怀疑已造成损失，请立即联系 support@openstarry.com 协助处理，必要时可申请异常扣费返还。详见数据安全说明。

服务稳定吗？SLA 多大？

99.99% SLA。3 国内 + 3 海外节点自动 Failover，单节点故障 5 秒内自动切换。状态页：status.openstarry.com。

遇到问题怎么联系你们？

发邮件至 support@openstarry.com，或在控制台提交工单，企业客户可加专属微信群。工单响应时间 < 2 小时（工作日）。

最佳实践

延迟优化与性能调优

AI API 的响应延迟分两段：首 Token 延迟（TTFT）——从请求到首个 Token 返回；以及总生成时间——直到所有 Token 输出完毕。对话类应用通常更关注 TTFT，批处理场景更关注吞吐量。以下策略均经过线上验证。

⚡

OpenStarry 在全球部署了 3 个国内直连节点（北京、上海、广州）+ 3 个海外节点（新加坡、硅谷、英国），SDK 会自动选择延迟最低的节点。如需手动指定，可在 base_url 中添加区域前缀，详见接入指南。

一、开启流式输出（Streaming）

流式输出是改善体验的最高优先级优化。设置 stream: true 后，模型生成第一个 Token 时即可开始显示，用户感知的等待时间大幅缩短。

对话界面：必须开启流式，否则用户需等待模型生成完整回复才能看到内容
批量处理、后台分析等场景：可关闭流式以简化代码逻辑
Python openai SDK 支持 stream=True 并返回异步迭代器，可直接 async for chunk in response
Node.js SDK 同样支持 stream: true，通过 for await...of 消费

二、模型选择策略

并非所有任务都需要最强模型。根据任务复杂度选择模型，是降低延迟与成本最直接的手段。

任务类型	推荐模型	理由
简单问答、分类、摘要	DeepSeek V4 Flash、Gemini 3 Flash	延迟低、成本极低，适合高并发
代码生成、复杂推理	GLM-5.1、GPT-4o	准确率高，适合对质量要求严格的场景
长文档处理（>64K tokens）	Kimi K2.6、Gemini 3 Flash	超长上下文，价格合理
中文内容创作	GLM-5.1、Kimi K2.6	中文语料充分，理解更准确
实时语音 / 工具调用	GPT-4o、Claude Sonnet 4.6	工具调用延迟低，JSON 格式输出稳定

💡

对于不确定复杂度的请求，可先用快速模型（如 DeepSeek Flash）判断，复杂问题再路由到旗舰模型，称为「级联路由」策略，可将平均成本降低 60% 以上。

三、提示词优化

提示词的长度和结构直接影响 TTFT 与 Token 消耗。以下原则经过多轮线上验证：

系统提示词精简化：移除冗余说明，保留关键指令。系统提示词每减少 1000 tokens，TTFT 通常可降低 30–80ms
复用高频系统提示词：对固定的系统提示词，Anthropic Claude 系列支持 cache_control 参数缓存前缀，可节省 90% 以上的首次处理时间
Few-shot 示例放置位置：将示例放在系统提示词末尾（而非用户消息中），有助于缓存命中
避免过长的 user 消息：若需传入大量上下文（如文档），考虑在后端预处理，仅传入关键段落，或改用支持文件上传的 API
max_tokens 合理设置：设置符合实际需求的 max_tokens，过大的预留会影响某些模型的调度优先级

四、重试与故障转移

网络抖动和上游限流是生产环境的常态。健壮的重试机制可显著提升服务可用性。

常见错误码处理

HTTP 状态码	含义	建议处理
`429`	触发速率限制	读取 `Retry-After` 响应头，按指定时间等待后重试；若无该头则指数退避（1s → 2s → 4s → 8s）
`502 / 503`	上游服务暂时不可用	立即重试 1 次，若仍失败则退避 5s 后再试，最多 3 次
`504`	网关超时	可能是单次请求过大；拆分请求或降低 max_tokens 后重试
`400`	请求格式错误	不可重试，检查参数格式（模型名、消息结构等）
`401`	API Key 无效	不可重试，检查 Key 是否正确、是否过期

🔄

建议为所有生产请求设置合理的 timeout：连接超时 5s，读取超时 120s（长文本生成可适当延长）。捕获 TimeoutError 后，对无状态请求可安全重试；对有状态操作需幂等性保证。

五、网络连接优化

合理的网络配置可将实际可观测延迟降低 10–30%：

保持长连接（Keep-Alive）：HTTP/1.1 默认开启 Keep-Alive，HTTP/2 更进一步支持多路复用。避免每次请求重新建立 TCP 连接（冷启动 TLS 握手通常需要 100–300ms）
使用国内直连节点：将 base_url 设置为 https://api.openstarry.com/v1，国内服务器会自动路由至北京接入点
DNS 预热：在应用启动时提前解析 API 域名，避免首次请求的 DNS 查询延迟
并发批量请求：对于独立的多个请求，使用 asyncio.gather()（Python）或 Promise.all()（Node.js）并发发送，而非串行等待
避免高峰时段集中请求：如有批处理任务，可安排在非高峰时段（UTC+8 00:00–06:00）以获得更低延迟和更高限额

✅

以上优化按优先级排序：开启流式 > 选对模型 > 精简提示词 > 正确重试 > 网络调优。建议按顺序逐步实施并通过 Dashboard 的延迟监控验证效果。

故障排查

常见错误码详解

接入 OpenStarry 时可能遇到的所有错误码按 HTTP 状态码分类，每个错误码给出含义、常见原因、示例响应和处理建议。对照本节排查大多数接入问题；如未列出，参见数据安全说明或联系 support@openstarry.com。

💡

OpenStarry API 100% 兼容 OpenAI 错误格式，错误响应体结构为 {"error": {"message": "...", "type": "...", "code": "..."}}。可用 response.json()["error"]["code"] 精准识别错误类型。

400 — invalid_request_error

含义：请求参数格式错误（HTTP 400）。不可重试。

常见原因：

model 字段拼写错误（如 glm-5 写成 glm5）
messages 数组为空，或首条消息不是 user / system
必填参数缺失（如 stream 模式下未设置 stream_options）
JSON 语法错误（缺逗号、缺引号、UTF-8 编码异常）

示例响应：

JSON
{
  "error": {
    "message": "model 'glm-5' not found, available models: glm-5.1, deepseek-v4, kimi-k2.6",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

处理建议：先检查请求体 JSON 格式；用模型列表对照正确的 model 名；用 Postman / curl 单独测试最小请求体。

401 — invalid_api_key / authentication_error

含义：API Key 无效、过期或缺失。不可重试。

常见原因：

Key 拼写错误（区分大小写）
使用了已撤销的 Key
Key 已过期（年付到期）
Authorization 头格式错误（应为 Bearer sk-xxx）
误把 sk-xxx 写到了 URL query 而非 Header

处理建议：到 Dashboard → API Keys 重新复制完整 Key（注意末尾无空格）；检查 Authorization 头格式。

402 — insufficient_quota / insufficient_balance

含义：账户余额不足或 Coding Plan 套餐已用完。不可重试（需先充值或续费）。

常见原因：

Token Plan 余额为 0 或负数
Coding Plan 当周/当月次数已用完
套餐到期未续费

处理建议：前往 Dashboard → 套餐账单充值或升级套餐；计费说明。

403 — permission_denied

含义：当前 Key 无权访问指定资源或模型。不可重试。

常见原因：

Key 绑定套餐仅含国产模型，调用了国际模型（Claude / GPT）
Key 已禁用（违规使用被封禁）
企业子账号无权限访问父账号资源

处理建议：检查套餐是否包含目标模型；联系 service@openstarry.com 处理账号权限问题。

404 — model_not_found / not_found

含义：请求的模型不存在或已下线。不可重试（需更换模型）。

常见原因：

模型名拼写错误（如 Claude-4-sonnet 写成 claude-4-sonnet 实际不存在的版本）
模型临时下线（厂商弃用）
端点错误（误用 /anthropic 调 OpenAI 模型）

处理建议：参考模型列表获取正确 model 字符串；用 GET /v1/models 端点获取当前可用模型列表。

408 — request_timeout

含义：请求处理超时。可重试（建议 1-2 次）。

常见原因：

单次请求 max_tokens 设置过大（如 32000）
输入上下文过长 + 输出过长组合
上游模型厂商端拥塞

处理建议：降低 max_tokens；拆分为多次短请求；指数退避后重试。

413 — context_length_exceeded

含义：输入超出模型上下文窗口。不可重试（需精简输入）。

常见原因：

messages 数组总 tokens 超过模型上限（如 GLM 5.1 限 128K，Kimi K2.6 限 256K）
上传了多张大图片（Vision 模式下）
长文档未做分块直接送入 RAG

处理建议：用 tiktoken 提前估算 tokens；超过上限时启用提示词优化中的分块策略；或切换到 Kimi K2.6 等长上下文模型。

429 — rate_limit_exceeded / tokens_rate_limit_exceeded

含义：请求频率或 Token 速率超出当前套餐限制。可重试（按 Retry-After 头）。

常见原因：

QPS（每秒请求数）超过套餐限制（如 Coding Plan 限 10 QPS）
TPM（每分钟 Token 数）超限（GLM 5.1 限 200K TPM）
同一 IP 在短时间内高频调用

示例响应：

HTTP
HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Limit-Requests: 10
X-RateLimit-Remaining-Requests: 0
X-RateLimit-Reset-Requests: 1s

{ "error": { "message": "Rate limit reached", "type": "rate_limit_error", "code": "rate_limit_exceeded" } }

处理建议：读取 Retry-After 响应头；实现指数退避（1s → 2s → 4s → 8s）；批量任务用令牌桶限流控制并发。

500 — internal_server_error

含义：OpenStarry 网关或上游模型厂商内部错误。可重试（1-3 次）。

处理建议：立即重试 1 次；若仍失败退避 5s 后再试；持续出现请联系 support@openstarry.com 并附上 request_id（错误响应中包含）。

502 / 503 — bad_gateway / service_unavailable

含义：上游模型服务暂时不可用。可重试（建议 3 次内）。

常见原因：上游厂商维护、机房故障、网络抖动。OpenStarry 节点级 Failover 通常 5 秒内自动切换。

处理建议：客户端实现 3 次重试（间隔 2s / 5s / 10s）；若持续超过 1 分钟，访问 status.openstarry.com 查看状态。

504 — gateway_timeout

含义：OpenStarry 网关到上游模型的连接超时。可重试。

处理建议：单次请求 max_tokens 过大导致生成时间超过 120s；建议拆分或降低；也可能是上游模型响应慢，OpenStarry 会自动 Failover 到备用节点。

流式（SSE）连接中断

含义：启用 stream=true 时连接中途断开。可重试。

常见原因：

客户端网络波动（最常见，VPN/代理/防火墙中断）
代理服务器缓冲过大，主动关闭空闲连接
CDN 边缘节点故障
客户端超时设置过短

处理建议：客户端实现「断点续传」——记录已收到的 last_chunk 偏移，下次重试时附上（OpenAI 暂不支持完整 resume，可重新发起整次请求）；调整反向代理（如 Nginx）的 proxy_read_timeout 至 300s+。

快速对照表

HTTP	错误码	含义	可重试
`400`	invalid_request_error	请求参数错误	否
`401`	invalid_api_key	API Key 无效	否
`402`	insufficient_quota	余额不足	否
`403`	permission_denied	无访问权限	否
`404`	model_not_found	模型不存在	否
`408`	request_timeout	请求超时	✅
`413`	context_length_exceeded	上下文超限	否
`429`	rate_limit_exceeded	速率限制	✅（按 Retry-After）
`500`	internal_server_error	服务器错误	✅
`502 / 503`	service_unavailable	上游不可用	✅
`504`	gateway_timeout	网关超时	✅

故障排查

工具调用失败调试指南

Function Calling / Tools 是 AI 编程最常用的能力，但调试时最容易踩坑。本节列出 7 种最常见的失败模式，每种给出症状、原因、调试方法和修复代码示例。

🛠️

OpenStarry 完全兼容 OpenAI Tools API（tools / tool_choice / tool_calls）和 Anthropic Tool Use（tools / tool_use / tool_result）。下方示例以 OpenAI 格式为主，Anthropic 格式差异会单独标注。

失败 1：工具名拼写错误（model 调了不存在的 tool）

症状：模型返回 finish_reason="tool_calls"，但 tool_calls[0].function.name 不在你声明的 tools 列表中。

原因：模型产生幻觉（hallucination），调了一个没声明的工具名；或工具名大小写不一致。

示例：

JSON
{
  "tool_calls": [
    {
      "function": {
        "name": "get_whether",   // 幻觉：应该是 get_weather
        "arguments": "{ \"city\": \"北京\" }"
      }
    }
  ]
}

修复：

Python
复制
for tool_call in response.choices[0].message.tool_calls:
    name = tool_call.function.name
    if name not in [t["function"]["name"] for t in tools]:
        raise ValueError(f"Model hallucinated tool: {name}")
    args = json.loads(tool_call.function.arguments)

失败 2：参数 JSON 解析失败（model 输出非合法 JSON）

症状：json.loads(tool_call.function.arguments) 抛 JSONDecodeError。

原因：

model 在 JSON 里夹了 markdown 代码块（```json ... ```）
model 输出截断（context 不够，被强制截断）
中文/特殊字符未正确转义
model 输出了 Python 风格的 'single quotes' 或 Python None

修复：

Python
复制
import json
import re

raw = tool_call.function.arguments

# 1. 去掉 markdown 包裹
raw = re.sub(r"^\s*```(?:json)?\s*", "", raw)
raw = re.sub(r"\s*```\s*$", "", raw).strip()

# 2. 替换 Python 风格
raw = raw.replace("None", "null").replace("True", "true").replace("False", "false")
raw = raw.replace("'", '\"')

try:
    args = json.loads(raw)
except json.JSONDecodeError as e:
    # 记录原始字符串便于排查
    logger.error(f"Bad JSON: {raw!r}")
    raise

失败 3：必填参数缺失（model 没给必填字段）

症状：TypeError: get_weather() missing 1 required positional argument: 'city'。

原因：工具 schema 描述不够清晰，model 误以为某字段是可选；或 max_tokens 不够导致 arguments 截断。

修复：

用 Pydantic 或 Zod 等 schema 库定义参数，自动生成 OpenAI Tools 格式，附带清晰描述
在工具 description 中明确标注必填：「必填：北京的城市名，例如 'beijing'」
设置 additionalProperties=False，强制 model 填齐
客户端兜底：缺必填字段时，自动追问 model「参数 city 是必填的，请重新提供」

失败 4：参数类型不匹配（string vs number）

症状：int("beijing") 抛 ValueError；或 datetime.strptime("hello", "%Y-%m-%d") 抛 TypeError。

原因：model 把 limit: 100（number）填成了 "100"（string）；把 date 填成了 "2025/01/01"（格式错误）。

修复：

Python
复制
import pydantic

class SearchArgs(pydantic.BaseModel):
    query: str
    limit: int = pydantic.Field(..., ge=1, le=100)
    date: pydantic.datetime

# Pydantic 自动校验 + 报错信息明确
args = SearchArgs.model_validate_json(raw_arguments)
# 失败抛 ValidationError，明确指出 limit 应该是 int、date 格式错误

失败 5：工具执行超时（HTTP / DB 查询卡住）

症状：整个对话被卡住 30s+；用户体验卡死；后续轮次延迟陡增。

原因：工具调用的 HTTP/DB/API 慢；未设置超时；model 看不到进度就反复调用。

修复：

所有工具调用必须设超时（建议 10-30s）
超时后返回错误字符串而非抛异常（让 model 看到结果自己决策）
对慢操作改用异步：立刻返回 task_id，后续轮次再查询

Python
复制
import httpx

def fetch_url(url: str) -> str:
    try:
        with httpx.Client(timeout=10.0) as client:
            r = client.get(url)
            r.raise_for_status()
            return r.text[:5000]   # 截断防止 context 爆炸
    except (httpx.TimeoutException, httpx.HTTPError) as e:
        # 返回错误字符串而非 raise，让 model 自己决定下一步
        return f"Error fetching {url}: {type(e).__name__}: {e}"

失败 6：工具返回内容太大（context 爆炸）

症状：单次工具返回 100K 字符；后续轮次费用暴涨；最后几轮报 413 context_length_exceeded。

原因：未对工具返回做截断/摘要。

修复：

硬截断：return result[:5000]（简单粗暴）
智能截断：保留前 2K + 中间关键段 + 后 2K（适合长文档）
摘要：再调一次便宜的模型把工具输出总结成 200 字
结构化：用 re.findall 只提取 model 需要的字段

失败 7：无限循环（tool 输出又触发了同一次调用）

症状：账单异常增长；日志显示同一个 tool 被连续调用 50+ 次；状态码开始 429。

原因：model 没拿到预期结果 → 重新调 → 还是没拿到 → 再调...；或工具输出包含「请再次调用」类文本诱导。

修复：

设置最大循环次数（如 8 轮），强制结束
检测相同 (tool_name, args_hash) 连续出现 ≥3 次，主动中断并改问 model「卡住了，请换个思路」
在 system prompt 明确：「同一工具最多调用 5 次，超过请直接给最终答案」

Python
复制
def run_agent(messages, tools, max_iter=8):
    last_call_key = None
    repeat_count = 0

    for i in range(max_iter):
        resp = client.chat.completions.create(model="glm-5.1", messages=messages, tools=tools)
        msg = resp.choices[0].message

        if not msg.tool_calls:
            return msg.content

        # 检测重复调用
        for tc in msg.tool_calls:
            key = (tc.function.name, tc.function.arguments)
            if key == last_call_key:
                repeat_count += 1
                if repeat_count >= 3:
                    return "检测到重复调用，已自动终止。请换个思路。"
            else:
                repeat_count = 0
                last_call_key = key

        messages.append(msg)
        for tc in msg.tool_calls:
            result = execute_tool(tc)
            messages.append({"role": "tool", "tool_call_id": tc.id, "content": result})

调试技巧

1. 开启 --debug 日志：打印每一轮的完整 messages 数组（含 tool_calls 和 tool 返回），便于还原执行流。

2. 用 stream=true + 实时打印：流式模式下能看到 model 思考过程，比非流式更容易发现问题。

3. 用 LangChain / LlamaIndex 的 trace：可视化每一步的工具调用和参数。

4. 单元测试 tool 函数：脱离 model，单独跑 tool 函数的 happy path 和异常 path，确保逻辑正确。

5. 准备 fallback 工具：当 model 调的工具不可用时，提供一个通用的 web_search / code_exec 兜底。

✅

工具调用失败 90% 集中在参数解析和无限循环两类。建议优先做：(1) 用 Pydantic/Zod 严格校验入参；(2) 设置最大循环 8 轮；(3) 所有外部调用 10s 超时；(4) 工具返回 5K 截断。这 4 条做好，基本能消灭 80% 的工具调用事故。

OpenStarry API 接入文档

3 步完成接入

可用模型

Python 接入

同步调用

流式输出

Node.js 接入

cURL 直接调用

Go 接入

流式输出（Streaming）

错误码说明

接入客户端与开发工具

Cursor

配置步骤

Claude Code

配置步骤

Cline（VS Code 插件）

配置步骤

TRAE

TRAE IDE 配置

Trae Agent（CLI）配置

OpenCode

配置步骤

Codex

配置步骤

Kilo CLI

配置步骤

ArkClaw

配置步骤

Kilo Code

配置步骤

Qwen Code

配置步骤

通义灵码

配置步骤

Qoder

配置步骤

Cherry Studio

配置步骤

Chatbox

配置步骤

OpenClaw

配置步骤

Hermes Agent

Python 接入

环境变量方式

Coze（扣子）

配置步骤（自定义模型 API）

OpenViking

配置步骤

Dify

配置步骤（云端版 / 自托管均适用）

Postman

配置步骤

常见问题

热门问题

计费套餐

技术接入

安全合规

延迟优化与性能调优

一、开启流式输出（Streaming）

二、模型选择策略

三、提示词优化

四、重试与故障转移

常见错误码处理

五、网络连接优化

常见错误码详解

400 — invalid_request_error

401 — invalid_api_key / authentication_error

402 — insufficient_quota / insufficient_balance

403 — permission_denied

404 — model_not_found / not_found

408 — request_timeout

413 — context_length_exceeded

429 — rate_limit_exceeded / tokens_rate_limit_exceeded

500 — internal_server_error

502 / 503 — bad_gateway / service_unavailable

504 — gateway_timeout

流式（SSE）连接中断

快速对照表