Zhiqian LLM API Integration

Just want to know about pricing and top-up?

This page is for developers who write code to call the API. If you only use LLMs in ZQAgent, you do not need to apply for a Key or read this page; see Zhiqian LLM (Pricing and Top-up).

Zhiqian LLM API is an OpenAI-compatible LLM gateway. With one Key and one endpoint, you can call multiple upstream models such as DeepSeek, Qwen, and Xiaomi MiMo, without integrating with or topping up each provider separately.

Projects that already use the OpenAI SDK usually only need to change two things: base_url and api_key.

Who It Is For

Your application needs a stable model egress and does not want to be constrained by a single provider's quotas or outages
Your team shares quota and wants billing based on actual usage instead of issuing a pile of Keys to each person
You need to query balance, usage details, and top-up records for cost accounting or external billing

Quick Start

1. Get an API Key

After registering for the User Center, Zhiqian LLM API is automatically activated and you receive CNY 5 in credit; no separate application is required. On the "Zhiqian LLM API" page in the User Center, you can:

View Key: masked by default; show the full value when needed
Reset Key: the old Key becomes invalid immediately; node-side configuration refreshes in about 5 seconds, so wait a moment before testing after resetting
Self-service top-up: supports WeChat Pay and Alipay

If the page indicates that an application is required, follow the prompts to provide your use case and contact information; view the Key after activation.

The Key is a string starting with sk-. Store it in a secrets management system; do not write it into a code repository or frontend page.

2. Send a Request

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. Use the 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);

Integration Information

Item	Value
Base URL	`https://zqai-api.cd-zq.com/v1`
Authentication	`Authorization: Bearer <API Key>`
Protocol	HTTPS, streaming responses use `text/event-stream`
OpenAPI specification	openapi.yaml
Request body limit	32 MB (used when images and audio are inlined as base64)

The OpenAPI specification can be imported directly into Apifox, Postman, or Swagger Editor, and can also be used to generate client SDKs.

Endpoints

Two groups, sharing one Key and one balance:

Group	Purpose	Path prefix
Model calls	Chat completions, OpenAI compatible	`/v1/chat/completions`, `/v1/models`
Generic API	Non-model endpoints such as OCR and business lookups, billed per call	`/v1/proxy/{slug}/...`

Account queries and fund transactions apply to both.

List Models

http

GET /v1/models

Returns only the model aliases that the current Key is authorized to use.

json

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

Chat Completions

http

POST /v1/chat/completions

Compatible with OpenAI's chat/completions; common fields are supported: messages, stream, max_tokens, temperature, top_p, stop, tools, tool_choice, and response_format. Set model to an alias for this service, and the gateway automatically routes to the corresponding upstream.

Streaming call:

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
  }'

Streaming responses are consistent with OpenAI and end with data: [DONE].

Account Queries

Use the same Key to query data for your own tenant; no extra parameters are required, and you cannot query other tenants' data.

Endpoint	Purpose
`GET /v1/account/balance`	Real-time available balance, in-flight holds, and ledger balance
`GET /v1/account/usage`	Usage summary, aggregated by day or model
`GET /v1/account/usage/records`	Request-level usage details
`GET /v1/account/recharges`	Top-up count, cumulative top-up amount, and top-up records

Fund Transactions

bash

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

Returns the complete transaction history of top-ups, usage, refunds, and adjustments; amount is signed (positive for credits, negative for debits), along with interval summaries. For reconciliation and invoicing, it is more complete than 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"

Example balance response:

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"
}

Difference between the two balance measures:

Field	Meaning	When to use
`available`	Redis hot ledger, with in-flight holds deducted	Determine "can I still send requests?"
`ledger_balance`	PG transaction basis, excluding in-flight holds	Reconciliation, invoicing

Usage is aggregated and posted by window, so ledger_balance may lag the real-time balance by 1–5 minutes; this is normal settlement delay.

Amount units

Responses provide both *_micros and yuan. For in-program accounting, use integer micro-yuan (CNY 1 = 1,000,000 micro-yuan). Yuan fields are for display only; do not use them for accumulation, or floating-point errors will occur.

Generic API Proxy

Besides chat models, the gateway forwards non-model upstream APIs — OCR, business registry lookups, speech recognition, and similar. Same Key, same balance, one bill.

Parameter formats depend on the service

The gateway only forwards; it does not translate protocols. What a service accepts and returns depends on the upstream behind it. Use the interface spec your operator provides — replace {slug} and the request body in every example below with the real service's.

Discover available services

bash

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

json

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

Only services you are authorized to use are returned. slug is the segment in the call path, unit_price is the price per call (CNY), and billing_mode is explained in Billing rules below.

How to call

Whatever follows /v1/proxy/{slug}/ is appended to the upstream path verbatim:

text

You send:      POST /v1/proxy/ocr/general?lang=zh
Upstream sees: POST {upstream}/{configured path}/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..."}'

Binary responses go straight to disk — no base64 round trip:

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

File uploads work too; the gateway forwards raw bytes:

bash

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

Differences from model endpoints

Item	Chat models	Generic API proxy
Path	`/v1/chat/completions`	`/v1/proxy/{slug}/...`
Request body	Fixed OpenAI format	Anything (JSON / binary / multipart)
Response	Fixed OpenAI format	Returned as-is, defined by upstream
Billing	Per token	Per call
Streaming	SSE, frame by frame	Passed through verbatim

Shared: one Key, one balance, one set of rate limits and audit records.

Billing rules

Mode	Meaning	When charged
`per_call`	Fixed price per call	`unit_price` on success (2xx)
`cost_markup`	Upstream cost plus markup	cost × (1 + markup) on success
`free`	No charge	Usage recorded, balance unchanged

Only successes (2xx) are billed. Upstream errors and network failures are free.
A hold is placed before the call and released in full on failure.
Insufficient balance returns 402 before the upstream is touched.

Notes

Your Key is never sent upstream. The gateway strips Authorization, x-api-key, and Cookie, replacing them with the operator's upstream credentials. The upstream sees the platform's account, not yours.

Methods must match. Only the methods configured for the service are allowed; anything else returns 400 and the message lists what is allowed.

Error codes are the gateway's, not the upstream's. When the upstream returns 4xx/5xx, the gateway responds 502 (code: upstream_error) and does not pass the original status through — this avoids leaking upstream account state and quota details.

Report the request ID when something breaks. Every response carries x-request-id, on both success and failure. Give it to your operator to trace exactly what happened upstream on that call:

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

Response headers are filtered. Hop-by-hop headers (connection, transfer-encoding, etc.) are dropped; the rest are preserved. The gateway adds two of its own:

Header	Meaning
`x-request-id`	Request ID for this call, always present; quote it when reporting issues
`x-charge-micros`	Amount charged (micro-yuan, CNY 1 = 1,000,000); `0` in `free` mode

Billing

Prepaid: top up first; when the balance is insufficient, requests return 402 directly. The two endpoint groups bill differently:

Endpoint type	Billing unit	Notes
Chat models	Per token	Price varies by model; see Pricing
Generic API	Per call	One price per service, see `unit_price` from `/v1/api-services`

Common rules:

Pricing varies by model; see Pricing for details
Streaming and non-streaming model requests use the same billing basis
Upstream failures and invalid request parameters are not billed; if the client disconnects midway, billing is based on the content already generated
Insufficient balance does not queue or extend credit; you must top up first

Use self-service top-up on the "Zhiqian LLM API" page in the User Center (WeChat Pay / Alipay); funds are available immediately after they arrive.

Error Codes

All errors use an OpenAI-compatible format:

json

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

HTTP	code	Meaning	What to do
400	`invalid_request`	Invalid parameters	Fix the request
401	`invalid_api_key`	Key missing, invalid, expired, or disabled	Check the Key
402	`insufficient_balance`	Insufficient balance	Top up; retrying will not help
403	`forbidden`	Tenant disabled, or Key has no permission for the model / API service	Contact operations
404	`not_found`	Model or path does not exist, or the API service is disabled	Check the model alias / service slug
429	—	Rate limit triggered	Back off and retry
500	`internal_error`	Internal service error	Retry later; if it persists, contact us
502	`upstream_error`	Upstream failure	Back off and retry
503	`capacity_exhausted`	All channels are at capacity or circuit-broken	Back off according to `Retry-After`

503 includes a Retry-After response header; back off according to the time it specifies rather than retrying immediately.

FAQ

What should I do if I lose the Key? Click "Reset Key" on the "Zhiqian LLM API" page in the User Center; the old Key becomes invalid immediately. The server stores only a hash of the Key, so the original value cannot be recovered.

Can I create multiple Keys? Currently, one account corresponds to one Key, sharing the same balance. To replace it, use "Reset Key"; the old Key then becomes invalid.

Do I need to handle provider failures myself? No. The gateway has built-in active-standby failover and circuit breaking: if the primary channel fails, it automatically switches to a standby channel; only when all channels are unavailable does it return 503. Clients only need to handle backoff retries for 503.

Are images and tool calling supported? This depends on the capabilities of the selected model. When a request contains tools or image content, the gateway routes only to channels that support those capabilities; if no channel is available, it returns 400 and will not silently downgrade to plain text.

What are the concurrency and rate limits? They are configured per Key and shared by tenant by default. If you have a clear high-concurrency requirement, state it during activation and we will configure the quota according to your scenario.

OpenAPI Specification
Pricing
User Center (account, credit, device plans)

Zhiqian LLM API Integration ​

Who It Is For ​

Quick Start ​

1. Get an API Key ​

2. Send a Request ​

3. Use the OpenAI SDK ​

Integration Information ​

Endpoints ​

List Models ​

Chat Completions ​

Account Queries ​

Fund Transactions ​

Generic API Proxy ​

Discover available services ​

How to call ​

Differences from model endpoints ​

Billing rules ​

Notes ​

Billing ​

Error Codes ​

FAQ ​

Related Links ​

Zhiqian LLM API Integration

Who It Is For

Quick Start

1. Get an API Key

2. Send a Request

3. Use the OpenAI SDK

Integration Information

Endpoints

List Models

Chat Completions

Account Queries

Fund Transactions

Generic API Proxy

Discover available services

How to call

Differences from model endpoints

Billing rules

Notes

Billing

Error Codes

FAQ

Related Links