志前 LLM API 連携

料金とチャージだけ知りたい場合

このページはプログラムから呼び出す開発者向けです。ZQAgent 内で大規模モデルを使うだけであれば、 Key の申請もこのページも不要です。志前 LLM（料金とチャージ）をご覧ください。

志前 LLM API は OpenAI 互換の大規模モデルゲートウェイです。1 つの Key、1 つのアドレスで DeepSeek、Qwen、Xiaomi MiMo など複数の上流モデルを呼び出せ、ベンダーごとに個別接続・個別チャージする必要はありません。

OpenAI SDK をすでに使っているプロジェクトは、通常 base_url と api_key の 2 か所を変えるだけです。

向いているケース

自分のアプリに安定したモデルの出口が必要で、単一ベンダーの制限や障害に縛られたくない
チームで枠を共有し、実際の使用量で精算したい（メンバーごとに大量の Key を配りたくない）
残高、消費明細、チャージ履歴を照会してコスト計算や外部課金をしたい

クイックスタート

1. API Key を取得

ユーザーセンターに登録すると志前 LLM API が自動で開通し、5 元分のクレジットが付与されます。個別申請は不要です。ユーザーセンターの「志前 LLM API」ページで次ができます：

Key を表示：ページは既定でマスクされ、必要時に完全な値を表示
Key を再発行：古い Key は即時無効。ノード側の設定は約 5 秒後に更新されるため、再発行後は少し待ってからテスト
セルフチャージ：WeChat Pay と Alipay に対応

ページに申請が必要と表示された場合は、案内に従って用途と連絡先を記入し、開通後に Key を確認してください。

Key は sk- で始まる文字列です。必ずシークレット管理システムに保存し、コードリポジトリやフロントエンドページに書かないでください。

2. リクエストを 1 回送る

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
リクエスト body 上限	32 MB（画像・音声を base64 でインライン化する場合に必要）

OpenAPI 仕様は Apifox、Postman、Swagger Editor に直接インポートでき、クライアント SDK の生成にも使えます。

インターフェース

2 つのグループがあり、同じ 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"
}

2 つの残高口径の違い：

フィールド	意味	参照する場面
`available`	Redis のホット台帳。保留中の凍結を差し引き済み	「まだリクエストを送れるか」の判断
`ledger_balance`	PG の流入口径。保留中の凍結を含まない	照合、請求書発行

消費はウィンドウ単位で集計して入帳されるため、ledger_balance はリアルタイム残高より 1〜5 分遅れることがあります。これは正常な決済遅延です。

金額の単位

レスポンスは *_micros と元の両方を返します。プログラム内の記帳にはマイクロ元の整数を使ってください（1 元 = 1,000,000 マイクロ元）。元のフィールドは表示専用で、合算に使うと浮動小数点誤差が出ます。

汎用 API 転送

チャットモデル以外に、ゲートウェイはモデル以外の上流インターフェースも転送できます —— OCR、企業情報検索、音声認識などです。同じ Key、同じ残高を使い、請求も 1 か所にまとまります。

パラメーターの形式はサービス次第

ゲートウェイは転送のみで、プロトコルは変換しません。あるサービスが受け取るパラメーターや返す構造は、その背後にどの上流がいるかによって決まります。運用担当から受け取ったインターフェース仕様に従ってください —— 以下の例にある {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 は呼び出し URL のその部分、 unit_price は 1 回あたりの価格（元）、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`	1 回ごとの固定価格	呼び出し成功（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 など）は転送されず、それ以外はそのまま保持されます。ゲートウェイ自身が 2 つのヘッダーを追加します：

応答ヘッダー	意味
`x-request-id`	今回の呼び出しのリクエスト ID。成功・失敗とも付与され、調査時に運用担当へ伝える
`x-charge-micros`	今回の課金（マイクロ元、1 元 = 1,000,000）。`free` モードでは 0

課金

実際の token 使用量で課金し、前払いです。先にチャージし、残高不足時はリクエストが直接 402 を返します。

価格はモデルごとに異なります。詳しくは料金
ストリーミングと非ストリーミングの課金口径は同じ
上流障害やリクエストパラメータの誤りは課金なし。クライアントが途中で切断した場合は生成済み内容で課金
残高不足ではキューにも入れずツケもなし。先にチャージが必要

ユーザーセンターの「志前 LLM API」ページでセルフチャージ（WeChat Pay / Alipay）でき、反映後すぐ使えます。

エラーコード

すべてのエラーは 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 を紛失したら？ ユーザーセンターの「志前 LLM API」ページで「Key を再発行」を押せば、古い Key は即時無効になります。Key はサーバー側にハッシュのみ保存され、元の値は復元できません。

複数の Key を発行できますか？ 現在、1 アカウントにつき 1 つの Key で、同じ残高を共有します。変更する場合は「Key を再発行」を使うと古い Key が無効になります。

ベンダーの障害を自分で処理する必要は？ 不要です。ゲートウェイには主系/待機系の降格とサーキットブレーカーが内蔵されており、主チャネルが失敗すると自動で待機系へ切り替え、全チャネルが使えない場合のみ 503 を返します。クライアントは 503 のバックオフ再試行だけを扱えば十分です。

画像とツール呼び出しに対応していますか？ 選択したモデルの能力によります。リクエストに tools や画像内容が含まれる場合、ゲートウェイはそれらに対応するチャネルにのみルーティングします。利用可能なチャネルがなければ 400 を返し、黙ってテキスト専用に降格することはありません。

同時実行とレート制限は？ Key ごとに設定され、既定ではテナントで共有されます。明確な高同時実行の要件があれば開通時に伝えてください。シナリオに応じてクォータを設定します。

志前 LLM API 連携 ​

向いているケース ​

クイックスタート ​

1. API Key を取得 ​

2. リクエストを 1 回送る ​

3. OpenAI SDK を使う ​

接続情報 ​

インターフェース ​

モデル一覧 ​

チャット補完 ​

アカウント照会 ​

資金の流れ ​

汎用 API 転送 ​

利用できるサービスを確認する ​

呼び出し方 ​

モデル向けインターフェースとの違い ​

課金ルール ​

注意点 ​

課金 ​

エラーコード ​

よくある質問 ​

関連リンク ​

志前 LLM API 連携

向いているケース

クイックスタート

1. API Key を取得

2. リクエストを 1 回送る

3. OpenAI SDK を使う

接続情報

インターフェース

モデル一覧

チャット補完

アカウント照会

資金の流れ

汎用 API 転送

利用できるサービスを確認する

呼び出し方

モデル向けインターフェースとの違い

課金ルール

注意点

課金

エラーコード

よくある質問

関連リンク