志前大模型 API 接入

只想瞭解價格和儲值？

本頁是給寫程式呼叫的開發者看的。如果你只是在志前AI助手裡使用大模型，不需要申請 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

計費

按實際 token 用量扣費，預付費：先儲值，餘額不足時請求直接返回 402。

價格按模型區分，詳見定價
流式與非流式計費口徑一致
上游故障、請求引數錯誤不計費；客戶端中途斷開按已產生內容計費
餘額不足不排隊、不賒賬，需要先儲值

在使用者中心「志前大模型 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 轉發

先看有哪些服務

怎麼呼叫

和模型介面的差別

計費規則

注意事項

計費

錯誤碼

常見問題

相關連結