ContextQMD
Back to Codexbar

z.ai provider

docs/zai.md

0.38.05.1 KB
Original Source

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)