wehub-resource-sync
144 lines
5.3 KiB
Markdown
144 lines
5.3 KiB
Markdown
---
|
|
summary: "z.ai provider data sources: API token in config/env and quota API response parsing."
|
|
read_when:
|
|
- Debugging z.ai token storage or quota parsing
|
|
- Updating z.ai API endpoints
|
|
---
|
|
|
|
# z.ai provider
|
|
|
|
z.ai is API-token based. No browser cookies.
|
|
|
|
## Token sources (fallback order)
|
|
1) Config token (`~/.config/codexbar/config.json` or legacy `~/.codexbar/config.json` → `providers[].apiKey`).
|
|
2) Environment variable `Z_AI_API_KEY`.
|
|
|
|
### Config location
|
|
- New installs: `~/.config/codexbar/config.json`
|
|
- Legacy installs: `~/.codexbar/config.json`
|
|
- Override for scripts/tests: `CODEXBAR_CONFIG=/path/to/config.json`
|
|
|
|
## Setup
|
|
|
|
Set **API region** to **Global (api.z.ai)** or **BigModel CN (open.bigmodel.cn)**.
|
|
|
|
- UI: Settings → Providers → z.ai. For team usage, add a token account, turn on **Team mode**, then enter the API key,
|
|
Organization ID, and Project ID.
|
|
- CLI personal:
|
|
|
|
```bash
|
|
printf '%s' "$Z_AI_API_KEY" | codexbar config set-api-key --provider zai --stdin
|
|
```
|
|
|
|
- CLI team:
|
|
|
|
```bash
|
|
printf '%s' "$Z_AI_API_KEY" | codexbar config set-api-key --provider zai --stdin \
|
|
--label Team \
|
|
--usage-scope team \
|
|
--organization-id org_... \
|
|
--workspace-id proj_...
|
|
```
|
|
|
|
- Check:
|
|
|
|
```bash
|
|
codexbar config validate
|
|
codexbar usage --provider zai --account Team
|
|
```
|
|
|
|
Personal config can use `providers[].apiKey`. Team config uses `tokenAccounts`:
|
|
|
|
```json
|
|
{
|
|
"id": "zai",
|
|
"enabled": true,
|
|
"region": "bigmodel-cn",
|
|
"tokenAccounts": {
|
|
"version": 1,
|
|
"activeIndex": 0,
|
|
"accounts": [
|
|
{
|
|
"id": "00000000-0000-0000-0000-000000000001",
|
|
"label": "Team",
|
|
"token": "<z.ai API key>",
|
|
"addedAt": 0,
|
|
"lastUsed": null,
|
|
"usageScope": "team",
|
|
"organizationId": "org_...",
|
|
"workspaceID": "proj_..."
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
Keep `organizationId` and `workspaceID` single-line. Do not paste display names, URLs, or multiple IDs.
|
|
|
|
## Finding the BigModel team IDs
|
|
For BigModel China team usage, CodexBar needs the `Bigmodel-Organization` and `Bigmodel-Project` request headers:
|
|
|
|
1. Open the BigModel API-key page and create/copy the API key:
|
|
- `https://bigmodel.cn/usercenter/proj-mgmt/apikeys`
|
|
- Some accounts still redirect through `https://open.bigmodel.cn/usercenter/apikeys`.
|
|
2. Open the team usage dashboard:
|
|
- `https://bigmodel.cn/coding-plan/team/usage-stats`
|
|
3. Select the organization/team and project to track.
|
|
4. Open browser DevTools → Network, refresh the team usage page, and inspect the
|
|
request to `api/monitor/usage/quota/limit` or `api/monitor/usage/model-usage`. Copy these request headers:
|
|
- `Bigmodel-Organization` → `organizationId`
|
|
- `Bigmodel-Project` → `workspaceID`
|
|
|
|
Copy each value once, on one line. Multi-line or duplicated IDs can make the API return `data: {}`, leaving MCP,
|
|
5-hour, and hourly usage empty.
|
|
|
|
## API endpoint
|
|
- `GET https://api.z.ai/api/monitor/usage/quota/limit`
|
|
- BigModel (China mainland) host: `https://open.bigmodel.cn`
|
|
- Override host via Providers → z.ai → *API region* or `Z_AI_API_HOST=open.bigmodel.cn`.
|
|
- Override the full quota URL (e.g. coding plan endpoint) via `Z_AI_QUOTA_URL=https://open.bigmodel.cn/api/coding/paas/v4`.
|
|
- Endpoint overrides must be explicit HTTPS URLs or bare hosts/paths that CodexBar normalizes to HTTPS. Explicit
|
|
`http://` overrides fail closed before the bearer token is attached to a request. If both z.ai overrides are set,
|
|
`Z_AI_QUOTA_URL` has priority for quota requests; a stale lower-priority `Z_AI_API_HOST` is ignored for that quota
|
|
path, but direct model-usage requests still validate `Z_AI_API_HOST` before sending bearer auth.
|
|
- Headers:
|
|
- `authorization: Bearer <token>`
|
|
- `accept: application/json`
|
|
|
|
### BigModel team usage
|
|
- The default usage scope is **personal**. Only a token account with `usageScope: team` is queried as team usage.
|
|
- Each z.ai token account can enable **Team mode** via UI, CLI, or config. Team accounts store:
|
|
- `usageScope`: `team`
|
|
- `organizationId`: BigModel organization id
|
|
- `workspaceID`: BigModel project id
|
|
- Team quota scope appends `type=2`; team hourly model usage appends `type=3`. Both send the BigModel selectors:
|
|
- `Bigmodel-Organization: <org id>`
|
|
- `Bigmodel-Project: <project id>`
|
|
- Live API checks return success with empty limits when one of the selectors is missing, so CodexBar treats both
|
|
Organization ID and Project ID as required for team usage.
|
|
|
|
## Usage dashboard
|
|
- Global: `https://z.ai/manage-apikey/coding-plan/personal/my-plan`
|
|
- BigModel China: `https://bigmodel.cn/coding-plan/personal/usage`
|
|
- BigModel China team: `https://bigmodel.cn/coding-plan/team/usage-stats`
|
|
- CodexBar's Usage Dashboard action follows the configured API region.
|
|
|
|
## Parsing + mapping
|
|
- Response fields:
|
|
- `data.limits[]` → each limit entry.
|
|
- `data.planName` (or `plan`, `plan_type`, `packageName`) → plan label.
|
|
- Limit types:
|
|
- `TOKENS_LIMIT` → primary (tokens window).
|
|
- `TIME_LIMIT` → secondary (MCP/time window) if tokens also present.
|
|
- Window duration:
|
|
- Unit + number → minutes/hours/days.
|
|
- Reset:
|
|
- `nextResetTime` (epoch ms) → date.
|
|
- Usage details:
|
|
- `usageDetails[]` per model (MCP usage list).
|
|
|
|
## Key files
|
|
- `Sources/CodexBarCore/Providers/Zai/ZaiUsageStats.swift`
|
|
- `Sources/CodexBarCore/Providers/Zai/ZaiSettingsReader.swift`
|
|
- `Sources/CodexBar/ZaiTokenStore.swift` (legacy migration helper)
|