Costr Integration Docs

Route requests to Costr through OpenAI-compatible / Anthropic-compatible APIs or Agent configuration, and use model="auto" for automatic model selection.

First API Call

Supported Interface Types

Costr is compatible with both OpenAI API and Anthropic API formats, so you can keep using your existing SDKs.

Interface	Base URL	Recommended for
OpenAI-compatible	https://costr.gopluslabs.io/v1	OpenAI SDK, LangChain, AI SDK, custom backend services
Anthropic-compatible	https://costr.gopluslabs.io	Anthropic SDK, Claude Code, Anthropic Messages API calls

Before You Call

Finish the following setup before running the SDK or Curl examples below.

Open the Costr dashboard

After entering the dashboard, you can review credits, create an API Key, and confirm in call history whether requests reached Costr.

Open dashboard

Create and safeguard your API Key

API Keys usually start with cr-. Keep the key safe and avoid exposing it to prevent unauthorized credit usage.

Create API Key

Configure a local environment variable

Set the API Key in a local environment variable first so the Python, JavaScript, and Curl examples below can all reuse it directly.

bash

export COSTR_API_KEY="cr-YOUR-API-KEY"

Python SDK Examples

OpenAI API Format

Install the OpenAI Python SDK:

bash

pip install -U openai

Call the API:

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("COSTR_API_KEY"),
    base_url="https://costr.gopluslabs.io/v1",
)

completion = client.chat.completions.create(
    model="auto",
    messages=[
        {"role": "user", "content": "Reply exactly: ok"}
    ],
    max_tokens=32,
)

print(completion.choices[0].message.content)
print(completion.x_routing)

Anthropic API Format

Install the Anthropic Python SDK:

bash

pip install -U anthropic

Call the API:

python

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ.get("COSTR_API_KEY"),
    base_url="https://costr.gopluslabs.io",
)

message = client.messages.create(
    model="auto",
    max_tokens=32,
    messages=[
        {"role": "user", "content": "Reply exactly: ok"}
    ],
)

print(message.content[0].text)

JavaScript / TypeScript SDK Examples

Install the OpenAI SDK:

bash

npm install openai

Call the API:

typescript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.COSTR_API_KEY,
  baseURL: "https://costr.gopluslabs.io/v1",
});

const completion = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Reply exactly: ok" }],
  max_tokens: 32,
});

console.log(completion.choices[0].message.content);
console.log(completion.x_routing);

Curl Examples

OpenAI API Format

bash

curl --location --request POST "https://costr.gopluslabs.io/v1/chat/completions" \
  --header "Authorization: Bearer $COSTR_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "model": "auto",
    "messages": [
      {"role": "user", "content": "Reply exactly: ok"}
    ],
    "max_tokens": 32
  }'

Anthropic API Format

bash

curl --location --request POST "https://costr.gopluslabs.io/v1/messages" \
  --header "x-api-key: $COSTR_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "model": "auto",
    "max_tokens": 32,
    "messages": [
      {"role": "user", "content": "Reply exactly: ok"}
    ]
  }'

Check Usage

In the Costr dashboard you can inspect call records and usage information, including:

Request status
Actual routed model
Model layer
Complexity decision result
Token usage
Per-request cost
Savings ratio

You can also query usage through the API:

Endpoint	Description
GET /v1/credits	Get balance and plan information
GET /v1/usage	Get daily usage
GET /v1/router/stats	Get routing stats, cost, and cache performance

Agents

Configure Costr in OpenClaw, Hermes, Claude Code, or any other Agent that supports a custom model service.

Agent Auto Setup

Paste the following prompt into the Agent you are currently using. If it can run commands, read pages, or edit config files, it can usually complete the setup automatically.

⚠️ Critical step: replace your API key

Before using the prompt below, replace cr-YOUR-API-KEYwith your real Costr API key so the Agent can authenticate correctly.

Prompt templateZero-config auto setup

Please read the Costr Agent integration spec: https://costr.gopluslabs.io/en/docs/agent-integration-spec Please switch the current Agent's model requests to Costr. My Costr API Key is: cr-YOUR-API-KEY. After configuration, run one minimal verification and tell me whether the integration succeeded.

Use the button below to copy the full prompt.

Agent Manual Setup

Configure Costr directly inside each tool. Installation is only needed if the Agent is not already installed.

OpenClaw

OpenClaw integrates with Costr through a custom OpenAI-compatible provider.

OpenAI-compatible

Prerequisites

Get a Costr API Key
Use https://costr.gopluslabs.io/v1 as the Base URL
Use auto as the model

Install OpenClaw

Skip this step if OpenClaw is already installed.

bash

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw --version

Configure with the onboarding wizard

bash

openclaw onboard --install-daemon

When the model provider prompt appears, choose a custom OpenAI-compatible provider and fill in:

Field	Value
Provider name	costrouter
Base URL	https://costr.gopluslabs.io/v1
API Key	cr-YOUR-API-KEY
Model	auto

Configure from CLI

bash

openclaw config set models.providers.costrouter '{
  "baseUrl": "https://costr.gopluslabs.io/v1",
  "apiKey": "cr-YOUR-API-KEY",
  "api": "openai-completions",
  "models": [
    {
      "id": "auto",
      "name": "CostRouter Auto",
      "reasoning": true,
      "input": ["text"],
      "cost": { "input": 3, "output": 3, "cacheRead": 0, "cacheWrite": 0 },
      "contextWindow": 256000,
      "maxTokens": 8192
    }
  ]
}' --strict-json --merge

openclaw config set agents.defaults.model '{"primary":"costrouter/auto"}' --strict-json --merge
openclaw config set agents.defaults.models '{"costrouter/auto":{}}' --strict-json --merge
openclaw models set costrouter/auto

Verify

bash

openclaw models status
openclaw tui

Start one test request in OpenClaw. Because OpenClaw prefixes the provider name, use the following value when the model is shown or switched:

text

costrouter/auto

Hermes Agent

Hermes Agent connects to Costr through the OpenAI-compatible API. In the model wizard, choose `Custom endpoint (self-hosted / VLLM / etc.)`.

OpenAI-compatible

Prerequisites

Get a Costr API Key
Use OpenAI-compatible / Custom endpoint mode
Use https://costr.gopluslabs.io/v1 as the Base URL
Use auto as the model

Install Hermes Agent

Skip this step if Hermes Agent is already installed.

bash

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc   # or source ~/.zshrc
hermes --version

Configure with the model wizard

bash

hermes model

Choose:

text

Custom endpoint (self-hosted / VLLM / etc.)

Fill in:

Field	Value
API type	OpenAI-compatible / Custom endpoint
API base URL	https://costr.gopluslabs.io/v1
API Key	cr-YOUR-API-KEY
Model	auto

Configure from CLI

bash

hermes config set model.provider custom
hermes config set model.base_url https://costr.gopluslabs.io/v1
hermes config set model.api_key cr-YOUR-API-KEY
hermes config set model.default auto

Verify

bash

hermes config show
hermes doctor

Use Hermes Agent

bash

hermes
hermes --tui

Claude Code

Claude Code uses the Anthropic-compatible gateway to connect to Costr.

Anthropic-compatible

Prerequisites

Get a Costr API Key
Use https://costr.gopluslabs.io as the Base URL
Use auto as the model

Install Claude Code

Skip this step if Claude Code is already installed.

bash

npm install -g @anthropic-ai/claude-code
claude --version

Temporary configuration

bash

export ANTHROPIC_BASE_URL="https://costr.gopluslabs.io"
export ANTHROPIC_AUTH_TOKEN="cr-YOUR-API-KEY"
export ANTHROPIC_MODEL="auto"
export ANTHROPIC_CUSTOM_MODEL_OPTION="auto"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Costr Auto"

claude --setting-sources local

ANTHROPIC_AUTH_TOKEN sends a Bearer token. Costr also supports x-api-key, so you may use ANTHROPIC_API_KEY instead. Do not set both at once.

If another Claude Code gateway is already configured on the machine, user-level settings may override the current shell. Use --setting-sources local while testing Costr.

Launch with --settings

bash

claude --setting-sources local --settings '{
  "model": "auto",
  "env": {
    "ANTHROPIC_BASE_URL": "https://costr.gopluslabs.io",
    "ANTHROPIC_AUTH_TOKEN": "cr-YOUR-API-KEY",
    "ANTHROPIC_MODEL": "auto",
    "ANTHROPIC_CUSTOM_MODEL_OPTION": "auto",
    "ANTHROPIC_CUSTOM_MODEL_OPTION_NAME": "Costr Auto"
  }
}'

Verify

bash

claude --setting-sources local -p "Reply exactly: ok"

The minimal Claude Code dialogue can already go through Costr. The official Claude Code gateway also requires /v1/messages/count_tokens; if that endpoint returns 404, some token-counting-related features may remain unavailable.

Other Agents

If the Agent supports an OpenAI-compatible provider, use that first. Only switch to Anthropic-compatible when OpenAI-compatible is unavailable.

If OpenAI-compatible is supported

Field	Value
Base URL	https://costr.gopluslabs.io/v1
API Key	cr-YOUR-API-KEY
Model	auto
Auth header	Authorization: Bearer <COSTR_API_KEY>

If only Anthropic-compatible is supported

Field	Value
Base URL	https://costr.gopluslabs.io
API Key	cr-YOUR-API-KEY
Model	auto
Auth header	x-api-key: <COSTR_API_KEY>
Messages endpoint	/v1/messages

Config Parameters

Parameter	Description
base_url / baseURL	API endpoint. OpenAI-compatible uses `/v1`; Anthropic-compatible does not append `/v1`.
api_key	Costr API Key, usually starting with `cr-`.
model	Use `auto` so Costr can pick the model automatically.
Authorization	Recommended Bearer auth header for OpenAI-compatible calls.
x-api-key	Common auth header for Anthropic-compatible calls.

`auto` vs `costrouter/auto`

Use model="auto" when calling Costr APIs directly.
In provider-based Agents such as OpenClaw, costrouter is the provider name, so the displayed model becomes costrouter/auto.

Test Calls

OpenAI-compatible

curl -s https://costr.gopluslabs.io/v1/chat/completions \
  -H "Authorization: Bearer $COSTR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Reply exactly: ok"}],
    "max_tokens": 32
  }'

Anthropic-compatible

curl -s https://costr.gopluslabs.io/v1/messages \
  -H "x-api-key: $COSTR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "max_tokens": 32,
    "messages": [{"role": "user", "content": "Reply exactly: ok"}]
  }'

Claude Code token counting

curl https://costr.gopluslabs.io/v1/messages/count_tokens \
  -H "x-api-key: $COSTR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

If this returns 404, the token-counting compatibility endpoint is not available yet. That does not mean /v1/messages itself is unavailable.

Routing Results

Successful responses may include `x_routing`, which explains the selected underlying model, tier, and savings.

json

{
  "x_routing": {
    "requested_model": "auto",
    "routed_model": "gemini-2.5-flash-lite",
    "routed_provider": "Economy",
    "tier": "budget",
    "confidence": 0.85,
    "savings_percent": 91.0
  }
}

Field	Description
requested_model	The requested model, usually `auto`
routed_model	The underlying model selected by Costr
routed_provider	The provider or tier actually used
tier	The routing tier
confidence	Confidence score for the routing decision
savings_percent	Savings versus the baseline model

Model Layer

Use `model="auto"` in production. Costr decides the model from request complexity, and the underlying pool can change over time.

Call GET /v1/models to see currently available models. The automatic routing entry model ID is auto.

Model ID	Description
auto	Automatic routing entry, recommended for production use

Routing Strategy

Optional request headers:

Header	Allowed values	Effect
x-cost-priority	low / balanced / quality	Tune the cost-versus-quality preference
x-no-cache	true	Bypass cache
x-cache-ttl	Seconds, for example 3600	Set cache lifetime

Example:

bash

curl https://costr.gopluslabs.io/v1/chat/completions \
  -H "Authorization: Bearer $COSTR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-cost-priority: quality" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Review this code."}]
  }'

Credits & Usage

In the Costr dashboard

API Key
Call logs
Request status
Token usage
Per-request cost
Savings ratio
Current balance

API queries

Endpoint	Description
GET /v1/credits	Get balance and plan info
GET /v1/usage	Get daily usage
GET /v1/router/stats	Get routing stats, cost, and cache performance

FAQ

Which one is correct: `auto` or `costrouter/auto`?

Use model="auto" when calling the Costr API directly. In provider-based tools such as OpenClaw, costrouter is the provider name, so the model is shown as costrouter/auto.

Does Costr support the OpenAI SDK?

Yes. Use https://costr.gopluslabs.io/v1 as the base URL and set model="auto".

Does Costr support the Anthropic SDK?

Yes. Use https://costr.gopluslabs.io as the base URL and call /v1/messages.

Why does Claude Code need `--setting-sources local`?

If user-level settings already contain another gateway, Claude Code may prefer that old configuration. --setting-sources local avoids that override during testing.

Is Claude Code fully compatible?

A minimal dialogue already works, but the Claude Code gateway also requires /v1/messages/count_tokens. If that endpoint returns 404, some features may remain unavailable.

How can I confirm the request really went through Costr?

Check x_routing in the response, or inspect the routed model in Costr dashboard call logs.

Troubleshooting

401 Invalid API Key

Make sure the key starts with cr-.
Make sure no extra spaces were copied.
Use curl to call Costr directly and separate key issues from tool-config issues.
For Claude Code, confirm old settings are not overriding the current session.

404 endpoint not found

OpenAI-compatible uses https://costr.gopluslabs.io/v1.
Anthropic-compatible uses https://costr.gopluslabs.io.
/v1/messages/count_tokens may currently return 404 for Claude Code token counting. That does not mean /v1/messages itself is unavailable.

model not found

Direct API calls use auto.
OpenClaw uses costrouter/auto.
Do not hardcode an underlying model ID from the internal model pool.

Agent config did not take effect

1Confirm the configuration was written to the source the current Agent actually reads.
2Confirm you did not overwrite existing providers.
3Use --merge for OpenClaw.
4Use --setting-sources local for Claude Code to avoid user-level overrides.
5Send one real request and then inspect Costr call logs.

API Reference

Endpoint	Method	Description
`/v1/chat/completions`	POST	OpenAI-compatible Chat Completions
`/v1/messages`	POST	Anthropic Messages API
`/v1/embeddings`	POST	OpenAI-compatible embeddings
`/v1/models`	GET	List available models and the `auto` router
`/v1/credits`	GET	Get balance and plan information
`/v1/usage`	GET	Get daily usage
`/v1/router/stats`	GET	Get router statistics
`/v1/router/health`	GET	Router health check
`/v1/router/feedback`	POST	Submit feedback
`/v1/router/dry-run`	POST	Preview routing results