API 概览

Star API 提供完全兼容 OpenAI 的 RESTful API。本文档提供 API 的总体概览和通用信息。

Base URL

所有 API 请求的 Base URL 为：

https://star.zhxyclaw.cn/v1

认证方式

所有 API 请求必须在 HTTP 请求头中携带 Authorization 字段，使用 Bearer Token 方式认证：

Authorization: Bearer sk-your-api-key

将 sk-your-api-key 替换为您在 Star API 控制台创建的 API Key。

注意

请妥善保管您的 API Key，不要将其暴露在客户端代码、公开仓库或任何不安全的地方。

OpenAI 兼容性

Star API 完全兼容 OpenAI API 格式。这意味着：

• 您可以直接使用 OpenAI 官方 SDK（Python、Node.js 等）
• 只需修改 base_url 和 api_key，无需更改其他代码
• 所有 OpenAI 兼容的第三方客户端也可以直接接入
• 请求参数、响应格式均与 OpenAI 保持一致

可用端点

端点	方法	说明	文档
/v1/chat/completions	POST	聊天补全	查看详情
/v1/models	GET	获取模型列表	查看详情
/v1/images/generations	POST	图像生成	查看详情
/v1/audio/transcriptions	POST	语音转文字	查看详情
/v1/audio/speech	POST	文字转语音	查看详情
/v1/embeddings	POST	文本嵌入	查看详情

请求格式

• 请求体使用 JSON 格式
• 必须设置 Content-Type: application/json 请求头
• 所有端点均使用 POST 方法（模型列表使用 GET）

响应格式

所有 API 响应均为 JSON 格式。成功响应包含请求的结果数据，错误响应包含错误信息。

成功响应示例

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1720000000,
  "model": "gpt-5.4",
  "choices": [...],
  "usage": {...}
}

错误响应格式

{
  "error": {
    "message": "错误信息",
    "type": "错误类型",
    "param": null,
    "code": "错误代码"
  }
}

错误码说明

HTTP 状态码	错误类型	说明
200	OK	请求成功
400	Bad Request	请求参数错误
401	Unauthorized	API Key 无效或缺失
403	Forbidden	无权限访问该资源
404	Not Found	请求的资源不存在
429	Too Many Requests	请求频率超出限制
500	Internal Server Error	服务端内部错误
502	Bad Gateway	上游服务异常
503	Service Unavailable	服务暂时不可用

频率限制

Star API 对 API 请求进行频率限制，以确保服务稳定性。具体限制取决于您的账户等级：

等级	并发请求数	每分钟请求数
免费用户	2	10
普通用户	5	60
会员用户	10	120

当请求超出限制时，API 将返回 429 Too Many Requests 状态码。建议在代码中实现重试机制：

import time
import openai

client = openai.OpenAI(
    api_key="sk-your-api-key",
    base_url="https://star.zhxyclaw.cn/v1"
)

max_retries = 3
for attempt in range(max_retries):
    try:
        response = client.chat.completions.create(
            model="gpt-5.4",
            messages=[{"role": "user", "content": "你好"}]
        )
        print(response.choices[0].message.content)
        break
    except openai.RateLimitError:
        wait_time = 2 ** attempt
        print(f"请求频率限制，{wait_time}秒后重试...")
        time.sleep(wait_time)

流式输出

Star API 支持流式输出（Streaming），适用于需要实时展示生成内容的场景。在请求中设置 "stream": true 即可开启。

详见 聊天补全 API 文档中的流式输出示例。

下一步

• 聊天补全 API — 最常用的对话接口
• 模型列表 — 查看可用模型
• 模型与定价 — 查看模型价格