发起第一个请求

本指南将帮助您完成第一次 API 调用，了解请求和响应的完整流程。

使用 curl 发起请求

基本请求

curl https://star.zhxyclaw.cn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {
        "role": "system",
        "content": "你是一个有帮助的AI助手。"
      },
      {
        "role": "user",
        "content": "用一句话解释什么是人工智能。"
      }
    ],
    "temperature": 0.7,
    "max_tokens": 200
  }'

将 sk-your-api-key 替换为您在 获取 API Key 中获得的实际密钥。

响应格式

成功请求将返回如下 JSON 响应：

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1720000000,
  "model": "gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "人工智能是让计算机模拟人类智能行为的技术，包括学习、推理和自我修正等能力。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 32,
    "total_tokens": 57
  }
}

响应字段说明

字段	类型	说明
id	string	请求的唯一标识符
object	string	对象类型，固定为 chat.completion
created	integer	响应创建时间（Unix 时间戳）
model	string	实际使用的模型名称
choices	array	模型生成的回复列表
choices[].index	integer	回复的索引
choices[].message.role	string	角色，固定为 assistant
choices[].message.content	string	模型生成的回复内容
choices[].finish_reason	string	停止原因：stop（正常结束）或 length（达到最大长度）
usage.prompt_tokens	integer	输入消耗的 Token 数
usage.completion_tokens	integer	输出消耗的 Token 数
usage.total_tokens	integer	总消耗的 Token 数

使用 OpenAI Python SDK

安装 SDK

pip install openai

基本调用

from openai import OpenAI

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

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "system", "content": "你是一个有帮助的AI助手。"},
        {"role": "user", "content": "用一句话解释什么是人工智能。"}
    ],
    temperature=0.7,
    max_tokens=200
)

print(response.choices[0].message.content)

流式输出

from openai import OpenAI

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

stream = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "user", "content": "写一首关于春天的五言绝句。"}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="", flush=True)

print()  # 换行

使用 OpenAI Node.js SDK

安装 SDK

npm install openai

基本调用

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-your-api-key",
  baseURL: "https://star.zhxyclaw.cn/v1",
});

async function main() {
  const response = await client.chat.completions.create({
    model: "gpt-5.4",
    messages: [
      { role: "system", content: "你是一个有帮助的AI助手。" },
      { role: "user", content: "用一句话解释什么是人工智能。" },
    ],
    temperature: 0.7,
    max_tokens: 200,
  });

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

main();

流式输出

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-your-api-key",
  baseURL: "https://star.zhxyclaw.cn/v1",
});

async function main() {
  const stream = await client.chat.completions.create({
    model: "gpt-5.4",
    messages: [
      { role: "user", content: "写一首关于春天的五言绝句。" },
    ],
    stream: true,
  });

  for await (const chunk of stream) {
    const content = chunk.choices[0]?.delta?.content;
    if (content) {
      process.stdout.write(content);
    }
  }
  console.log();
}

main();

使用环境变量管理 Key

为了避免在代码中硬编码 API Key，推荐使用环境变量：

# 设置环境变量
export STAR_API_KEY="sk-your-api-key"

# Python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("STAR_API_KEY"),
    base_url="https://star.zhxyclaw.cn/v1"
)

// Node.js
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.STAR_API_KEY,
  baseURL: "https://star.zhxyclaw.cn/v1",
});

常见错误

HTTP 状态码	错误信息	说明
401	Invalid API key	API Key 无效或已过期
403	Permission denied	无权限访问该模型
429	Rate limit exceeded	请求频率超出限制
500	Internal server error	服务端错误，请稍后重试

遇到错误时，请检查：

1. API Key 是否正确
2. 模型名称是否正确（查看 模型列表）
3. 请求格式是否正确
4. 账户余额是否充足

下一步

• API 文档 — 查看完整的 API 参考
• 模型与定价 — 了解支持的模型与价格
• SDK 使用指南 — 更多语言的接入示例