Skip to content

API_USAGE.md

Latest commit

 

History

History
255 lines (193 loc) · 9.02 KB

API_USAGE.md

File metadata and controls

255 lines (193 loc) · 9.02 KB
Raw

AI Zero Token API Usage

This guide is for Vibe Coding tools, OpenAI-compatible SDKs, local frontends, and scripts that need to call AI Zero Token through HTTP.

Base URL

Start the local gateway:

azt start

Default API base URL:

http://127.0.0.1:8787/v1

For another device on the same network, replace 127.0.0.1 with the gateway machine IP.

Auth

The local gateway does not require an API key by default.

Most OpenAI-compatible clients still require a non-empty key value. Use a placeholder:

local

Enable an optional access key in Models & Services → Serve API → Overview. Once enabled, every /v1/* and /codex/v1/* model endpoint requires Authorization: Bearer <access-key>, including model discovery. Replace local in the examples below with this key. Missing or invalid keys return 401. Rotating a key invalidates the old key immediately; update other clients after rotation. All management endpoints are local-only, even when API authentication is disabled. An API key grants model access only.

Vibe Coding Settings

Use these values in an OpenAI-compatible provider setup:

API Base URL: http://127.0.0.1:8787/v1
API Key: local
Text model: gpt-6-luna
Image model: gpt-image-2

Use GET /v1/models to see the models available through the current local Codex cache.

OpenClaw Settings

Use the OpenAI-compatible provider mode in OpenClaw:

Provider: OpenAI compatible
Base URL: http://127.0.0.1:8787/v1
API Key: local
Model: gpt-6-luna
Chat endpoint: /chat/completions
Streaming: enabled
Tools / function calling: enabled

The gateway accepts OpenClaw-style chat.completions requests with tools, tool_choice, parallel_tool_calls, reasoning_effort, assistant tool_calls, and tool-role result messages. It translates those fields to the upstream Codex Responses shape and returns OpenAI-style chat responses.

OpenClaw requests are visible in the management console request log when the client sends an OpenClaw user agent. The log keeps safe summaries only; it does not store full access tokens.

Codex Custom Provider

Use Models & Services → Serve API → Overview → Local Codex to connect Codex to this machine's account pool. Account management, models, default API model, and rotation policies are under Serve API. Use Connect External API → Remote AI Zero Token for another machine's gateway, including its access key when enabled.

For external OpenAI-compatible providers, add a service under Connect External API, discover or manually enter models, optionally inspect capabilities, then choose models to expose in Codex. Discovery, inspection, and activation are separate actions. Every listed model remains selectable; capability statuses are advisory. Only one provider is active in the local Codex configuration, while the account-pool API continues serving other clients.

When the local gateway key is enabled, the app writes a keyed azt_gateway provider and keeps the native Codex model catalog. Enabling, rotating, or disabling the key updates an active local gateway connection; restart Codex afterwards. API keys for external services and remote gateways are separate. Without gateway authentication, advanced compatibility settings retain the native openai or legacy ai-zero-token modes.

Default history-preserving mode:

model = "gpt-6-luna"
model_provider = "openai"
openai_base_url = "http://127.0.0.1:8787/codex/v1"

Codex sends POST /codex/v1/responses with Accept: text/event-stream; the gateway forwards that request to the active Codex OAuth account and streams upstream Responses SSE events back to Codex. Current Codex clients perform remote context compaction through this same route using a compaction_trigger input item. For older clients, POST /codex/v1/responses/compact adapts the request to that protocol and returns a JSON response.compaction object. Reuse its complete output array in the next request; encrypted compaction items are preserved unchanged. The regular /v1/* routes remain OpenAI-compatible API routes for non-Codex clients.

For Codex image_generation tool requests, Plus, Team, Pro, and other paid plans use the Codex Responses image tool. If Free account image generation is enabled under Serve API → Models, Free plans use the ChatGPT web image path and receive a synthetic Codex-compatible Responses SSE stream, because Free accounts may have ChatGPT image quota while the Codex image_generation tool is unavailable upstream.

Separate AI Zero Token provider mode:

model = "gpt-6-luna"
model_provider = "ai-zero-token"

[model_providers.ai-zero-token]
name = "AI Zero Token"
base_url = "http://127.0.0.1:8787/codex/v1"
wire_api = "responses"
supports_websockets = false

Models

curl http://127.0.0.1:8787/v1/models

Local Usage Statistics

The management console reads persisted local usage statistics from:

~/.ai-zero-token/.state/usage

Fetch the same summary through the admin endpoint:

curl http://127.0.0.1:8787/_gateway/admin/usage

The summary includes today, current-process, lifetime, daily trend, account, model, endpoint, error, image-route, and source breakdowns. Token totals are counted only when the upstream response returns usage; requests without upstream usage are counted separately as requests with missing usage. Usage files keep metadata only and do not store prompts, messages, access tokens, or base64 image payloads.

Sync the Codex model list from the Codex backend into the local cache:

azt models --refresh

Responses API

curl http://127.0.0.1:8787/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "input": "Reply with OK only."
  }'

Chat Completions API

curl http://127.0.0.1:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "messages": [
      { "role": "user", "content": "Reply with OK only." }
    ]
}'

Streaming chat completions:

curl http://127.0.0.1:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "stream": true,
    "messages": [
      { "role": "user", "content": "Reply with OK only." }
    ]
  }'

Tool-call compatible request:

curl http://127.0.0.1:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "messages": [
      { "role": "user", "content": "What is the weather tool argument for Shanghai?" }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get weather for a city.",
          "parameters": {
            "type": "object",
            "properties": {
              "city": { "type": "string" }
            },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

Images API

Image requests are also routed by account plan. Plus, Team, Pro, and other paid plans use the Codex Responses image_generation tool. Free accounts use the ChatGPT web image path only when Free account image generation is enabled under Serve API → Models; otherwise they keep the original Codex image-tool path.

curl http://127.0.0.1:8787/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean product poster on a white desk with a laptop and glass cup.",
    "size": "1024x1024",
    "quality": "low",
    "response_format": "b64_json"
  }'

JSON image edit with a reference image URL or base64 data URL:

curl http://127.0.0.1:8787/v1/images/edits \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Use this reference image and make it look like a clean product advertisement.",
    "images": [
      {
        "image_url": "data:image/png;base64,REPLACE_WITH_IMAGE_BASE64"
      }
    ],
    "size": "1024x1024",
    "quality": "low",
    "response_format": "b64_json"
  }'

JavaScript SDK Example

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "local",
  baseURL: "http://127.0.0.1:8787/v1",
});

const response = await client.chat.completions.create({
  model: "gpt-6-luna",
  messages: [
    { role: "user", content: "Reply with OK only." },
  ],
});

console.log(response.choices[0]?.message?.content);

Notes

  • Login first through the management page or azt login.
  • A model appearing in /v1/models means the local Codex cache lists it. Final availability still depends on the active account.
  • stream=true is supported for /v1/chat/completions through OpenAI-style SSE chunks. Codex passthrough streaming is isolated under /codex/v1/responses.
  • n > 1 is not supported for /v1/chat/completions.
  • Tool/function calling is supported for common OpenAI-compatible clients, including OpenClaw, but exact upstream behavior still depends on the active Codex model and account.
  • The default listener is 0.0.0.0:8787, so local-network clients can call the gateway by using the machine IP.