志前大模型 API 接入

只想了解价格和充值？

本页是给写程序调用的开发者看的。如果你只是在 ZQAgent 里使用大模型，不需要申请 Key、也不需要看本页，直接看志前大模型（价格与充值）。

志前大模型 API 是一个 OpenAI 兼容的大模型网关。用一个 Key、一个地址，就能调用 DeepSeek、千问、小米 MiMo 等多个上游模型，不需要为每家供应商单独对接、单独充值。

已经用过 OpenAI SDK 的项目，通常只需要改两个地方：base_url 和 api_key。

适合谁

自己的应用需要一个稳定的模型出口，不想被单家供应商的限额、故障绑住
团队共用额度，希望按实际用量结算，而不是给每人发一堆 Key
需要查询余额、消费明细、充值记录，做成本核算或对外计费

快速开始

1. 获取 API Key

注册用户中心后会自动开通志前大模型 API，并赠送 5 元额度，不用单独申请。在用户中心的「志前大模型 API」页可以：

查看 Key：页面默认打码，需要时再显示完整值
重置 Key：旧 Key 立即失效；节点侧配置约 5 秒后刷新，重置后稍等再测
自助充值：支持微信支付与支付宝

如果该页提示需要申请，按提示填写用途与联系方式，开通后再查看 Key。

Key 是 sk- 开头的字符串，请存进密钥管理系统，不要写进代码仓库或前端页面。

2. 发一次请求

bash

curl https://zqai-api.cd-zq.com/v1/chat/completions \
  -H "Authorization: Bearer $ZQAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zq-standard",
    "messages": [{"role": "user", "content": "你好"}],
    "max_tokens": 128
  }'

3. 用 OpenAI SDK

PythonNode.js

python

from openai import OpenAI

client = OpenAI(
    base_url="https://zqai-api.cd-zq.com/v1",
    api_key="sk-你的Key",
)

resp = client.chat.completions.create(
    model="zq-standard",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

javascript

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://zqai-api.cd-zq.com/v1',
  apiKey: process.env.ZQAI_API_KEY,
});

const resp = await client.chat.completions.create({
  model: 'zq-standard',
  messages: [{ role: 'user', content: '你好' }],
});
console.log(resp.choices[0].message.content);

接入信息

项	值
Base URL	`https://zqai-api.cd-zq.com/v1`
鉴权	`Authorization: Bearer <API Key>`
协议	HTTPS，流式返回 `text/event-stream`
OpenAPI 规范	openapi.yaml
请求体上限	32 MB（图片、音频以 base64 内联时用得到）

OpenAPI 规范可以直接导入 Apifox、Postman 或 Swagger Editor，也可以用来生成客户端 SDK。

接口

分两组，用同一个 Key、同一个余额：

分组	用途	路径前缀
模型调用	对话补全，OpenAI 兼容	`/v1/chat/completions`、`/v1/models`
通用 API	OCR、工商查询等非模型接口，按次计费	`/v1/proxy/{slug}/...`

账户查询与资金流水两组通用。

模型列表

http

GET /v1/models

只返回当前 Key 有权使用的模型别名。

json

{
  "object": "list",
  "data": [
    { "id": "zq-standard", "object": "model", "created": 0, "owned_by": "zqai" }
  ]
}

对话补全

http

POST /v1/chat/completions

与 OpenAI 的 chat/completions 兼容，常用字段都支持：messages、stream、 max_tokens、temperature、top_p、stop、tools、tool_choice、 response_format。model 填本服务的别名，网关会自动路由到对应上游。

流式调用：

bash

curl -N https://zqai-api.cd-zq.com/v1/chat/completions \
  -H "Authorization: Bearer $ZQAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zq-standard",
    "messages": [{"role": "user", "content": "写一段 50 字的自我介绍"}],
    "stream": true
  }'

流式响应与 OpenAI 一致，以 data: [DONE] 结束。

账户查询

用同一个 Key 查询自己租户的数据，不需要额外参数，也查不到别人的。

接口	用途
`GET /v1/account/balance`	实时可用余额、在途冻结、账本余额
`GET /v1/account/usage`	消费汇总，可按天或按模型聚合
`GET /v1/account/usage/records`	请求级消费明细
`GET /v1/account/recharges`	充值次数、累计充值额、充值记录

资金流水

bash

curl "https://zqai-api.cd-zq.com/v1/account/transactions?kind=refund" \
  -H "Authorization: Bearer $ZQAI_API_KEY"

返回充值、消费、退款、调账的完整流水，amount 带符号（入账为正、出账为负），以及区间汇总。对账、开票时用它比 recharges 更完整。

bash

# 余额
curl https://zqai-api.cd-zq.com/v1/account/balance \
  -H "Authorization: Bearer $ZQAI_API_KEY"

# 最近 7 天消费，按模型汇总
curl "https://zqai-api.cd-zq.com/v1/account/usage?group_by=model" \
  -H "Authorization: Bearer $ZQAI_API_KEY"

# 最近 20 条消费明细
curl "https://zqai-api.cd-zq.com/v1/account/usage/records?limit=20" \
  -H "Authorization: Bearer $ZQAI_API_KEY"

余额响应示例：

json

{
  "object": "account.balance",
  "tenant_id": 1,
  "currency": "CNY",
  "available_micros": 12345678,
  "available": 12.345678,
  "reserved_micros": 0,
  "reserved": 0.0,
  "ledger_balance_micros": 12345678,
  "ledger_balance": 12.345678,
  "source": "redis",
  "as_of": "2026-10-20T12:00:00Z"
}

两个余额口径的区别：

字段	含义	什么时候看
`available`	Redis 热账本，已扣在途冻结	判断「还能不能发请求」
`ledger_balance`	PG 流水口径，不含在途冻结	对账、开票

消费按窗口汇总入账，ledger_balance 可能比实时余额晚 1–5 分钟，属于正常结算延迟。

金额单位

响应同时给出 *_micros 与元。程序内记账请用微元整数（1 元 = 1,000,000 微元），元字段只用于展示，不要用来累加，否则会有浮点误差。

通用 API 转发

除了对话模型，网关还能转发非模型类的上游接口 —— OCR、工商信息查询、语音识别等。用的是同一把 Key、同一个余额，账单也在一处。

参数格式取决于服务本身

网关只做转发，不转换协议。某个服务收什么参数、返回什么结构，取决于它背后接的是哪家上游。以运营给你的接口说明为准 —— 下面所有示例里的 {slug} 与请求体，都请替换成实际服务的。

先看有哪些服务

bash

curl https://zqai-api.cd-zq.com/v1/api-services \
  -H "Authorization: Bearer $ZQAI_API_KEY"

json

{
  "object": "list",
  "data": [
    {
      "slug": "ocr",
      "name": "通用 OCR",
      "billing_mode": "per_call",
      "unit_price": 0.01,
      "allowed_methods": ["POST", "GET"]
    }
  ]
}

只返回你有权使用的服务。slug 就是调用地址里的那一段， unit_price 是每次调用的价格（元），billing_mode 见下面的计费规则。

怎么调

把 /v1/proxy/{slug}/ 后面的部分原样接到上游路径上：

text

你请求：  POST /v1/proxy/ocr/general?lang=zh
上游收到：POST {上游地址}/{运营配置的路径}/general?lang=zh

bash

curl -X POST "https://zqai-api.cd-zq.com/v1/proxy/ocr/general" \
  -H "Authorization: Bearer $ZQAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": "iVBORw0KGgo..."}'

二进制响应直接落盘，不用先转 base64：

bash

curl -X POST "https://zqai-api.cd-zq.com/v1/proxy/ocr/image" \
  -H "Authorization: Bearer $ZQAI_API_KEY" \
  -d '{"url": "https://example.com/a.jpg"}' \
  -o result.png

上传文件用 multipart 也可以，网关按原始字节转发：

bash

curl -X POST "https://zqai-api.cd-zq.com/v1/proxy/ocr/file" \
  -H "Authorization: Bearer $ZQAI_API_KEY" \
  -F "file=@invoice.pdf"

和模型接口的差别

项	对话模型	通用 API 转发
路径	`/v1/chat/completions`	`/v1/proxy/{slug}/...`
请求体	固定 OpenAI 格式	任意（JSON / 二进制 / multipart）
响应	固定 OpenAI 格式	原样返回，由上游决定
计费	按 token	按次
流式	SSE 逐帧	直接透传（不做帧解析）

共同点：同一把 Key、同一个余额、同一套限流与审计。

计费规则

模式	含义	什么时候扣
`per_call`	每次固定价	调用成功（2xx）扣 `unit_price`
`cost_markup`	按上游成本加价	调用成功扣「成本 × (1 + 加价比例)」
`free`	不扣费	只记录用量，余额不变

只对成功（2xx）计费。上游报错、网络失败都不扣钱。
调用前会先冻结一次额度，失败会全额退回。
余额不足直接返回 402，不会先调上游再失败。

注意事项

你的 Key 不会发给上游。 网关会把 Authorization、x-api-key、 Cookie 这些头剔除，换成运营配置的上游凭据。所以上游看到的是平台的账号，不是你。

方法必须匹配。 服务配了哪些方法就只能用哪些，用错返回 400，错误信息里会列出允许的方法。

错误码是网关的，不是上游的。 上游返回 4xx/5xx 时，网关统一返回 502 （code: upstream_error），原始状态码不会透传 —— 避免把上游的账号状态、配额细节暴露给你。

出问题时报请求 ID。 每个响应的响应头里都有 x-request-id，成功和失败都有。把它发给运营，可以直接定位到这一次调用在上游发生了什么：

bash

curl -i -X POST "https://zqai-api.cd-zq.com/v1/proxy/ocr/general" \
  -H "Authorization: Bearer $ZQAI_API_KEY" -d '{}' | grep -i x-request-id

响应头会被过滤。 逐跳头（connection、transfer-encoding 等）不会转发，其余原样保留。网关自己会额外加两个头：

响应头	含义
`x-request-id`	本次调用的请求 ID，成功失败都有，排查时提供给运营
`x-charge-micros`	本次扣费（微元，1 元 = 1,000,000），`free` 模式为 0

计费

预付费：先充值，余额不足时请求直接返回 402。两类接口的计费单位不同：

接口类型	计费单位	说明
对话模型	按 token	价格按模型区分，详见定价
通用 API	按次	每个服务一个单价，见 `/v1/api-services` 的 `unit_price`

共同规则：

上游故障、请求参数错误不计费；客户端中途断开按已产生内容计费
余额不足不排队、不赊账，需要先充值
模型调用：流式与非流式计费口径一致

在用户中心「志前大模型 API」页自助充值（微信支付 / 支付宝），到账后立即可用。

错误码

所有错误都是 OpenAI 兼容格式：

json

{
  "error": {
    "message": "余额不足",
    "type": "invalid_request_error",
    "param": null,
    "code": "insufficient_balance"
  }
}

HTTP	code	含义	怎么办
400	`invalid_request`	参数不合法	修正请求
401	`invalid_api_key`	Key 缺失、无效、过期或已停用	检查 Key
402	`insufficient_balance`	余额不足	充值，重试无用
403	`forbidden`	租户停用，或 Key 无该模型权限	联系运营
404	`not_found`	模型或路径不存在	检查模型别名
429	—	触发限流	退避后重试
500	`internal_error`	服务内部错误	稍后重试，持续出现请联系我们
502	`upstream_error`	上游故障	退避后重试
503	`capacity_exhausted`	全部渠道满载或熔断	按 `Retry-After` 退避

503 会带 Retry-After 响应头，建议按它给的时间退避，不要立刻重试。

常见问题

Key 丢了怎么办？ 在用户中心「志前大模型 API」页点「重置 Key」即可，旧 Key 立即失效。Key 在服务端只存哈希，无法找回原值。

可以开多个 Key 吗？ 目前一个账号对应一个 Key，共用同一份余额。需要更换时用「重置 Key」，旧 Key 随即失效。

要不要自己处理供应商故障？ 不需要。网关内置主备降级与熔断：主渠道失败会自动切备用渠道，全部渠道不可用才返回 503。客户端只需处理 503 的退避重试。

支持图片和工具调用吗？ 取决于所选模型的能力。请求里带 tools 或图片内容时，网关只会路由到支持这些能力的渠道；没有可用渠道会返回 400，不会悄悄降级成纯文本。

并发和频率限制是多少？ 按 Key 配置，默认按租户共享。有明确的高并发需求请在开通时说明，我们会按场景配置配额。

志前大模型 API 接入 ​

适合谁 ​

快速开始 ​

1. 获取 API Key ​

2. 发一次请求 ​

3. 用 OpenAI SDK ​

接入信息 ​

接口 ​

模型列表 ​

对话补全 ​

账户查询 ​

资金流水 ​

通用 API 转发 ​

先看有哪些服务 ​

怎么调 ​

和模型接口的差别 ​

计费规则 ​

注意事项 ​

计费 ​

错误码 ​

常见问题 ​

相关链接 ​

志前大模型 API 接入

适合谁

快速开始

1. 获取 API Key

2. 发一次请求

3. 用 OpenAI SDK

接入信息

接口

模型列表

对话补全

账户查询

资金流水

通用 API 转发

先看有哪些服务

怎么调

和模型接口的差别

计费规则

注意事项

计费

错误码

常见问题

相关链接