Token Harbor

https://tokenharbor.ai/docs
Admin
Token Harbor is a unified AI model gateway that provides a single API key and balance to access...
Tokens:7,238
Snippets:112
Trust Score:5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Token Harbor CLI

Source: https://tokenharbor.ai/docs/connect

Commands to install the CLI tool on different operating systems. The tool automatically provisions a private Node.js environment if needed.

```bash
curl -fsSL https://tokenharbor.ai/connect.sh | sh
```

```powershell
irm https://tokenharbor.ai/connect.ps1 | iex
```

--------------------------------

### GET /v1/models

Source: https://tokenharbor.ai/docs/api/models

Retrieves the catalog of available models including live pricing, release dates, and knowledge cutoffs.

```APIDOC
## GET /v1/models

### Description
Returns the model catalog data as JSON for SDKs that pre-fetch model information.

### Method
GET

### Endpoint
/v1/models
```

--------------------------------

### Configure Aider with Environment Variables

Source: https://tokenharbor.ai/docs/integrations/aider

Set the OpenAI base URL and API key in your shell to point Aider to Token Harbor.

```bash
export OPENAI_API_BASE="https://tokenharbor.ai/v1"
export OPENAI_API_KEY="YOUR_thk_KEY"
aider --model openai/th-orchestra
```

--------------------------------

### Configure Continue with Token Harbor

Source: https://tokenharbor.ai/docs/integrations/continue

Add this configuration block to your ~/.continue/config.json file to enable Token Harbor models.

```json
{
  "models": [
    {
      "title": "Token Harbor",
      "provider": "openai",
      "apiBase": "https://tokenharbor.ai/v1",
      "apiKey": "YOUR_thk_KEY",
      "model": "gpt-5.5"
    }
  ]
}
```

--------------------------------

### Configure opencode provider

Source: https://tokenharbor.ai/docs/integrations/opencode

Add the Token Harbor provider to the opencode configuration file located at ~/.config/opencode/opencode.json.

```json
{
  "provider": {
    "tokenharbor": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "https://tokenharbor.ai/v1", "apiKey": "{env:TOKENHARBOR_API_KEY}" },
      "models": { "th-orchestra": { "name": "Token Harbor" } }
    }
  }
}
```

--------------------------------

### Configure OpenClaw for Token Harbor

Source: https://tokenharbor.ai/docs/integrations/openclaw

Add this configuration to ~/.openclaw/openclaw.json to register Token Harbor as a provider and enable the TH Orchestra model.

```json
{
  "models": {
    "providers": {
      "tokenharbor": {
        "baseUrl": "https://tokenharbor.ai/v1",
        "apiKey": { "source": "env", "provider": "default", "id": "TOKENHARBOR_API_KEY" },
        "api": "openai-completions",
        "models": [{
          "id": "th-orchestra", "name": "TH Orchestra",
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
          "contextWindow": 200000, "maxTokens": 8192
        }]
      }
    }
  },
  "agents": { "defaults": { "models": {
    "tokenharbor/th-orchestra": { "alias": "TH Orchestra" }
  } } }
}
```

--------------------------------

### Configure Zed settings.json for Token Harbor

Source: https://tokenharbor.ai/docs/integrations/zed

Add the Token Harbor provider to the language_models configuration in Zed's settings.json file.

```json
{
  "language_models": {
    "openai_compatible": {
      "Token Harbor": {
        "api_url": "https://tokenharbor.ai/v1",
        "available_models": [{
          "name": "th-orchestra",
          "display_name": "TH Orchestra",
          "max_tokens": 200000,
          "max_output_tokens": 8192
        }]
      }
    }
  }
}
```

--------------------------------

### Configure Coding Agents via CLI

Source: https://tokenharbor.ai/docs/compare/openrouter

Use the Token Harbor CLI to automatically configure supported coding agents to use the gateway.

```bash
curl -fsSL https://tokenharbor.ai/connect.sh | sh
```

--------------------------------

### Configure Claude Code settings

Source: https://tokenharbor.ai/docs/integrations/claude-code

Add the Token Harbor base URL and your API key to the Claude Code configuration file located at ~/.claude/settings.json.

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://tokenharbor.ai",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_thk_KEY"
  }
}
```

--------------------------------

### Configure pi models.json for Token Harbor

Source: https://tokenharbor.ai/docs/integrations/pi

Add the Token Harbor provider to the pi configuration file. The apiKey field uses a command to resolve the secret from the environment variable.

```json
{
  "providers": {
    "tokenharbor": {
      "name": "Token Harbor",
      "baseUrl": "https://tokenharbor.ai/v1",
      "api": "openai-completions",
      "apiKey": "!node -e \"const k=process.env.TOKENHARBOR_API_KEY;if(!k)process.exit(1);process.stdout.write(k)\"",
      "models": [{
        "id": "th-orchestra", "name": "TH Orchestra",
        "reasoning": true, "input": ["text", "image"],
        "contextWindow": 200000, "maxTokens": 8192,
        "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
      }]
    }
  }
}
```

--------------------------------

### Configure OpenAI Codex for Token Harbor

Source: https://tokenharbor.ai/docs/integrations/codex

Add this provider configuration to your ~/.codex/config.toml file to route requests through Token Harbor.

```toml
model = "gpt-5.5"
model_provider = "tokenharbor"

[model_providers.tokenharbor]
name = "Token Harbor"
base_url = "https://tokenharbor.ai/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"
```

--------------------------------

### Migrate API Configuration

Source: https://tokenharbor.ai/docs/compare/openrouter

Update your application's base URL and API key to switch from OpenRouter to Token Harbor.

```text
- base_url = "https://openrouter.ai/api/v1"
- api_key  = "sk-or-..."
+ base_url = "https://tokenharbor.ai/v1"
+ api_key  = "thk_..."
```

--------------------------------

### Execute a plain chat request with th-orchestra

Source: https://tokenharbor.ai/docs/api/models

Demonstrates a standard chat request without tools, which routes to the inexpensive chat pool.

```bash
curl https://tokenharbor.ai/v1/chat/completions \
  -H "Authorization: Bearer $TH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"th-orchestra","messages":[{"role":"user","content":"fix the off-by-one in parser.ts"}]}'
```

--------------------------------

### Uninstall Token Harbor CLI

Source: https://tokenharbor.ai/docs/connect

Removes all agents, shell hooks, PATH entries, and the local configuration directory.

```bash
tokenharbor uninstall
```

--------------------------------

### POST /v1/chat/completions

Source: https://tokenharbor.ai/docs/api/curl

OpenAI-compatible endpoint for chat completions. Supports both non-streaming and streaming responses.

```APIDOC
## POST /v1/chat/completions

### Description
Drop-in compatible with the OpenAI Chat Completions schema. Use this for standard chat interactions.

### Method
POST

### Endpoint
https://tokenharbor.ai/v1/chat/completions

### Parameters
#### Request Body
- **model** (string) - Required - The model ID to use (e.g., tokenharbor/qwen3-max)
- **messages** (array) - Required - List of message objects with role and content
- **stream** (boolean) - Optional - If true, enables Server-Sent Events for streaming responses
```

--------------------------------

### Universal Key Format

Source: https://tokenharbor.ai/docs/getting-started/universal-key

The standard format for the Universal Key, featuring a prefix for identification and a random base64url string.

```text
thk_live_{64-char base64url random}
```

--------------------------------

### Configure Cline/Roo Code API Settings

Source: https://tokenharbor.ai/docs/integrations/cline

Required settings to route Cline or Roo Code through the Token Harbor API.

```text
Base URL : https://tokenharbor.ai/v1
API Key : your thk_… key
Model ID : e.g. claude-sonnet-5
```

--------------------------------

### Streaming OpenAI-compatible chat completion

Source: https://tokenharbor.ai/docs/api/curl

Streams tokens from the /v1/chat/completions endpoint by setting stream to true and processing the response line by line.

```python
import requests

with requests.post(
    url="https://tokenharbor.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer thk_live_PASTE_YOURS_HERE",
        "Content-Type": "application/json",
    },
    json={
        "model": "tokenharbor/qwen3-max",
        "messages": [{"role": "user", "content": "Write a haiku about the sea."}],
        "stream": True,
    },
    stream=True,
) as r:
    for line in r.iter_lines():
        if line:
            print(line.decode("utf-8"))
```

--------------------------------

### Securely passing the API key

Source: https://tokenharbor.ai/docs/connect

Use environment variables or interactive prompts to avoid exposing the API key in shell history or process lists.

```bash
# good — read from the environment
export TOKENHARBOR_API_KEY="$(cat ~/.th-key)"
tokenharbor connect --yes

# also good — interactive prompt, nothing is echoed or recorded
tokenharbor connect
```

--------------------------------

### Non-streaming OpenAI-compatible chat completion

Source: https://tokenharbor.ai/docs/api/curl

Performs a synchronous request to the /v1/chat/completions endpoint using the requests library.

```python
import requests

response = requests.post(
    url="https://tokenharbor.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer thk_live_PASTE_YOURS_HERE",
        "Content-Type": "application/json",
    },
    json={
        "model": "tokenharbor/qwen3-max",
        "messages": [{"role": "user", "content": "Hi"}],
    },
)
print(response.json()["choices"][0]["message"]["content"])
```

--------------------------------

### Cache Control Headers

Source: https://tokenharbor.ai/docs/api/models

Headers used to manage cache lookup and write behavior for API requests.

```APIDOC
## Cache Control Headers

### Description
Control how the system handles request caching using the X-TH-Cache-Control header.

### Parameters
#### Request Headers
- **X-TH-Cache-Control** (string) - Optional - Values: 'bypass' (skip lookup, write to cache) or 'force-refresh' (skip lookup, skip write).

### Response Headers
- **X-TH-Cache-Layer** (string) - Indicates if the response was served from cache (values: 'exact' or 'semantic').
```

--------------------------------

### Calculate Token Billing Cost

Source: https://tokenharbor.ai/docs/api/models

Formula used to determine the final cost of an API call based on input/output tokens, upstream pricing, markup, and volume discounts.

```text
cost = (input_tokens × upstream_in_per_1m + output_tokens × upstream_out_per_1m)
       / 1,000,000
       × (1 + markup_pct / 100)
       × (1 − volume_discount)
```

--------------------------------

### POST /v1/messages

Source: https://tokenharbor.ai/docs/api/curl

Anthropic-compatible endpoint for messages. Supports both non-streaming and streaming responses.

```APIDOC
## POST /v1/messages

### Description
Anthropic Messages API shape. Compatible with official Anthropic SDKs by setting the base_url.

### Method
POST

### Endpoint
https://tokenharbor.ai/v1/messages

### Parameters
#### Request Body
- **model** (string) - Required - The model ID to use
- **max_tokens** (integer) - Required - The maximum number of tokens to generate
- **messages** (array) - Required - List of message objects with role and content
```

--------------------------------

### Streaming Anthropic-compatible message

Source: https://tokenharbor.ai/docs/api/curl

Streams text responses from the /v1/messages endpoint using the Anthropic SDK's stream method.

```python
from anthropic import Anthropic

client = Anthropic(
    api_key="thk_live_PASTE_YOURS_HERE",
    base_url="https://tokenharbor.ai",
)

with client.messages.stream(
    model="tokenharbor/qwen3-max",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a haiku about the sea."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
```

--------------------------------

### Non-streaming Anthropic-compatible message

Source: https://tokenharbor.ai/docs/api/curl

Sends a request to the /v1/messages endpoint using the official Anthropic Python client.

```python
from anthropic import Anthropic

client = Anthropic(
    api_key="thk_live_PASTE_YOURS_HERE",
    base_url="https://tokenharbor.ai",
)

message = client.messages.create(
    model="tokenharbor/qwen3-max",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hi"}],
)
print(message.content[0].text)
```
Tokens:
Raw