Using Nexith with Claude Code
Claude Code only speaks the Anthropic protocol (/v1/messages, x-api-key). The Nexith gateway has
this adapter built in: it translates at the protocol boundary only, while internally running the same
execution pipeline — routing, provider dispatch, billing, and egress scrubbing are all reused.
Configuration#
export ANTHROPIC_BASE_URL="https://api.nexith.ai"
export ANTHROPIC_API_KEY="nx-你的key"Add these two lines to ~/.zshrc or ~/.bashrc to persist them, then use claude as usual inside
your project directory.
About the base URL (the easiest thing to get wrong)#
Do not include /v1. The client appends /v1/messages to the base itself:
| What you write | What the client actually requests | Result |
|---|---|---|
https://api.nexith.ai |
https://api.nexith.ai/v1/messages |
✅ |
https://api.nexith.ai/v1 |
https://api.nexith.ai/v1/v1/messages |
❌ Fails |
This matches the convention of the official Anthropic SDK (the official base is
https://api.anthropic.com, without /v1).
Both hosts work#
api.nexith.ai and gateway.nexith.ai are two entry points to the same backend; either one works.
(Historical note: before 2026-09-20, api.nexith.ai did not forward model endpoints, and using it
returned missing_api_key — an error unrelated to whether your key was correct. This has been
fixed.)
Credentials#
- Claude Code sends
x-api-key(notAuthorization). - The gateway accepts both:
Authorization: Bearer <token>takes priority, withx-api-keyas a fallback. - Keys are created at platform.nexith.ai and look like
nx-followed by 32 characters.
Supported endpoints#
| Endpoint | Description |
|---|---|
POST /v1/messages |
Anthropic Messages, with tool use and streaming support |
POST /v1/messages/count_tokens |
Token counting |
POST /v1/chat/completions |
OpenAI-compatible (same backend) |
POST /v1/responses |
OpenAI Responses (used by Codex) |
GET /v1/models |
Model list |
Tool calling#
Verified working: tool definitions are converted from input_schema verbatim into the upstream's
parameters; responses are framed per the Anthropic spec — content_block_start (type: tool_use)
→ several input_json_deltas (argument slices forwarded verbatim from the upstream, with no JSON
parsing or re-serialization, so long arguments lose no precision in the round trip) →
content_block_stop → message_delta with stop_reason: "tool_use".
tool_choice mapping: auto → auto, any → required, tool → a specific function.
Billing and long tasks#
- Billing is settled from actual tokens, from the same source as the settlement ledger.
- Each request has a 120-second limit (currently). Very long agent loops whose single turn exceeds 120s are truncated — this is being worked on.
nexith-corerequests with more than 32k context are automatically escalated to a stronger upstream and billed at the escalated tier.
Troubleshooting#
401 missing_api_key
The request never reached the gateway. Check whether the base URL has an extra /v1 (see the table
above), or whether the domain is misspelled.
401 invalid_api_key
The request reached the gateway, but the key is wrong: confirm it starts with nx-, has no stray
spaces, and that the account has sufficient balance.
403 / 404
/v1/messages is served only on these two hosts. Other domains (such as platform.nexith.ai) will
not work.
Streaming appears stuck Upstream models do not proactively send data during long reasoning. The gateway currently has no SSE heartbeat, so clients may appear stuck during very long reasoning; this is on the to-do list.