接入文档

TokenFactory 提供与 OpenAI 完全兼容的 API 接口。任何支持 OpenAI SDK 的语言或框架，只需要把 base_url 和 api_key 换成我们提供的值，即可无缝接入。

一、快速开始

1. 注册账号

访问注册页面，填写账号、密码、邮箱，通过邮箱验证码完成注册。新用户注册即赠送 ¥10 体验金。

2. 创建 API Key

登录后进入控制台，点击「创建 API Key」，生成一把以 sk-zx- 开头的密钥。该密钥仅在创建时显示一次，请务必立即保存。

3. 发起第一次请求

curl http://api.tokenfactory.hazelchip.com:8081/v1/chat/completions \
  -H "Authorization: Bearer sk-zx-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "__MODEL__",
    "messages": [
      {"role": "user", "content": "你好，请介绍一下你自己"}
    ]
  }'

二、认证方式

所有请求必须在 HTTP Header 中携带 API Key：

Authorization: Bearer sk-zx-你的密钥

请勿将 API Key 硬编码到客户端（浏览器、App）中，避免泄露。建议在自己的业务后端做转发。

三、支持的模型

当前可调用的模型如下（模型 ID 必须一字不差）：

模型 ID	类型	上下文	输入价格（/1M Tokens）	缓存命中价格	输出价格
`DeepSeek-V4-Flash-Vision-Ex`	视觉 / 多模态	128K	¥0.70	¥0.07	¥2.80
`GLM-5.3-Flash`	通用对话	128K	¥0.35	¥0.035	¥1.40
`qwen3.8-27b`	通用对话	16K	¥0.35	¥0.035	¥1.40

更多模型即将上线，请关注控制台「模型列表」页面。

四、接口列表

1. 对话接口

POST /v1/chat/completions

与 OpenAI 完全兼容，支持以下参数：

参数	类型	必填	说明
`model`	string	是	模型 ID，见上表
`messages`	array	是	对话历史，格式与 OpenAI 一致
`stream`	boolean	否	是否流式返回，默认 false
`max_tokens`	integer	否	最大输出 Token 数
`temperature`	number	否	采样温度，0 ~ 2，默认 1
`tools`	array	否	工具定义，用于 Function Calling
`tool_choice`	string / object	否	工具选择策略

非流式请求示例：

curl http://api.tokenfactory.hazelchip.com:8081/v1/chat/completions \
  -H "Authorization: Bearer sk-zx-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "__MODEL__",
    "messages": [{"role": "user", "content": "你好"}]
  }'

流式请求示例（SSE）：

curl http://api.tokenfactory.hazelchip.com:8081/v1/chat/completions \
  -H "Authorization: Bearer sk-zx-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "__MODEL__",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

工具调用示例（Function Calling）：

curl http://api.tokenfactory.hazelchip.com:8081/v1/chat/completions \
  -H "Authorization: Bearer sk-zx-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "__MODEL__",
    "messages": [{"role": "user", "content": "现在几点了？"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_time",
        "description": "获取当前系统时间",
        "parameters": {"type": "object", "properties": {}}
      }
    }]
  }'

2. 模型列表接口

GET /v1/models

curl http://api.tokenfactory.hazelchip.com:8081/v1/models \
  -H "Authorization: Bearer sk-zx-你的密钥"

返回格式与 OpenAI 标准一致：

{
  "object": "list",
  "data": [
    {"id": "__MODEL__", "object": "model", "created": 1677610602, "owned_by": "tokenfactory"}
  ]
}

五、Python SDK 接入示例

直接使用官方 openai 包即可：

from openai import OpenAI

client = OpenAI(
    base_url="http://api.tokenfactory.hazelchip.com:8081/v1",
    api_key="sk-zx-你的密钥",
)

# 非流式
resp = client.chat.completions.create(
    model="__MODEL__",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

# 流式
stream = client.chat.completions.create(
    model="__MODEL__",
    messages=[{"role": "user", "content": "你好"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

六、接入 Agent 框架

因为接口完全兼容 OpenAI，可以直接接入 OpenClaw、CrewAI、AutoGen 等主流 Agent 框架，只需把 base_url 和 api_key 替换为上面的值即可。

七、错误处理

所有错误返回遵循 OpenAI 标准格式：

{
  "error": {
    "message": "错误描述",
    "type": "错误类型",
    "code": "错误码",
    "param": null
  }
}

常见错误码：

HTTP 状态码	code	含义
401	`missing_api_key` / `invalid_api_key`	API Key 缺失或无效
402	`insufficient_balance`	余额不足，请充值
403	`model_offline`	模型已下架或维护中
404	`model_not_found`	模型 ID 不存在
429	`rate_limit_error`	请求过于频繁
500	`internal_server_error`	服务端异常，请稍后重试

八、计费说明

计费分为三个维度：

输入 Token：按每百万 Token 计费，单价见「支持的模型」表格。
缓存命中 Token：如果请求的前缀与历史请求一致，这部分 Token 会命中缓存，按超低价计费（一般为输入价的 1/10）。
输出 Token：按每百万 Token 计费。

如何用好缓存： 如果你的业务会在短时间内重复发送相同的前缀（比如同一份长文档 + 不同的追问），可以把文档放在 messages 最前面，确保每次请求前缀完全一致，这样第二遍起就能享受缓存低价。

九、常见问题

Q1：为什么调用返回 `model_not_found`？

请检查请求中的 model 字段是否与「支持的模型」表格完全一致（大小写敏感）。

Q2：为什么返回 `model_offline`？

该模型当前处于维护中或已下架状态，请调用 /v1/models 查看当前可用模型列表。

Q3：如何充值？

登录控制台，进入「钱包充值」页面，选择或输入金额后点击「立即充值」即可。

Q4：如何查看用量和消费明细？

登录控制台，进入「用量统计」页面，可以查看每一次调用的模型、输入/输出 Token、缓存命中的 Token、费用和节省金额。

十、技术支持

如有问题，请联系平台运营人员。