文档

Zither Tech API

API 遵循 OpenAI Chat Completions 格式。官方 OpenAI SDK 和大多数兼容 OpenAI 的工具,只要换掉 base URL 和 API 密钥就能直接使用。

概览

所有请求都发往同一个 base URL,并以 bearer token 的形式携带 API 密钥进行认证。

Base URLhttps://api.zithertech.com/v1
认证Authorization: Bearer YOUR_API_KEY
对话补全POST /v1/chat/completions
模型列表GET /v1/models

在控制台的 API 密钥页面创建密钥。请妥善保管密钥:任何拿到密钥的人都能消耗你的余额。如果密钥泄露,请在控制台删除它并新建一个。

快速开始

下面的示例从环境变量 ZITHER_API_KEY 读取密钥。

curl

Terminal
curl https://api.zithertech.com/v1/chat/completions \
  -H "Authorization: Bearer $ZITHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-27b",
    "messages": [{"role": "user", "content": "写一首关于琴弦的俳句。"}]
  }'

Python

用 pip install openai 安装 SDK。

main.py
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.zithertech.com/v1",
    api_key=os.environ["ZITHER_API_KEY"],
    timeout=180,
)

resp = client.chat.completions.create(
    model="qwen3.8-27b",
    messages=[{"role": "user", "content": "写一首关于琴弦的俳句。"}],
)
print(resp.choices[0].message.content)

Node.js

用 npm install openai 安装 SDK。

main.mjs
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.zithertech.com/v1",
  apiKey: process.env.ZITHER_API_KEY,
  timeout: 180_000,
});

const resp = await client.chat.completions.create({
  model: "qwen3.8-27b",
  messages: [{ role: "user", content: "写一首关于琴弦的俳句。" }],
});
console.log(resp.choices[0].message.content);

流式输出

把 stream 设为 true,生成过程中会以 server-sent events 的形式逐步收到 token。

stream.py
stream = client.chat.completions.create(
    model="qwen3.8-27b",
    messages=[{"role": "user", "content": "用三句话解释向量数据库。"}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        print("\n", chunk.usage)

模型

在 model 字段中传入模型 ID。GET /v1/models 返回你的密钥可以使用的模型。

模型 ID上下文窗口输入 / 百万 token输出 / 百万 token
qwen3.8-27b65,536 tokens$0.35$2.00

上下文窗口同时包含提示词和生成的内容。

参数

支持常用的 Chat Completions 参数:

  • model 和 messages(必填)
  • max_tokens:生成 token 数的上限
  • temperature、top_p:采样控制
  • stop:最多四个停止序列
  • presence_penalty、frequency_penalty
  • seed:尽量保证采样结果可复现
  • stream 和 stream_options

超时与冷启动

模型运行在 Serverless GPU 上,空闲时会自动缩容。如果某个模型一段时间没人用,第一个请求可能需要等待约两分钟,让模型加载。之后的请求会立即开始。

请把客户端超时设为至少 180 秒;交互式应用建议使用流式输出,这样用户能第一时间看到生成的内容。

错误

出错时会返回一个 JSON 响应体,其中的消息说明了问题所在。

状态码含义处理方法
401API 密钥缺失、无效、已过期,或已达到消费上限。检查 Authorization 请求头,以及控制台里这个密钥的设置。
403余额不足,或这个密钥无权使用该模型。充值余额或调整密钥设置。
429请求过于频繁。用指数退避的方式重试。
5xx连接模型时出现临时问题。用指数退避的方式重试。持续出现请联系客服。

计费

用量从预付额度中扣除。额度在控制台的钱包页面用银行卡充值,由 Stripe 处理付款,最低充值 $5。每个响应都包含一个 usage 对象,其中有 prompt_tokens 和 completion_tokens。一次请求的费用为:

prompt_tokens × 输入单价 + completion_tokens × 输出单价

请求完成时从余额中扣除费用。控制台的使用日志会列出每次请求的 token 数和费用。价格、额度有效期和退款规则见服务条款。

支持

发邮件至 support@zithertech.com。如果是某个请求出了问题,请附上时间、模型和错误信息,但千万不要附上你的 API 密钥。