Getting Started

Nexa AI Gateway API

Nexa is a unified, high-reliability AI API gateway designed for modern developer tooling, agents, and production applications. It provides standard OpenAI and Anthropic protocol compatibility, so you can point your existing libraries, IDEs, and CLI tools with zero code rewrites.

verified

Reseller White-label Integrity: Responses are sanitized to ensure zero upstream identity leaks. All upstream hostnames and identifiers are mapped to nexabase.xyz with headers set to Server: Nexa/1.0.

Base URLs

Connect to the following base URLs depending on whether you are using OpenAI-compatible or Anthropic-compatible clients:

OpenAI Compatible ClientsOpenAI Spec

For OpenAI SDKs, Codex, OpenCode, and HTTP clients calling /v1/chat/completions or /v1/responses:

https://api.nexabase.xyz/v1

Anthropic Compatible ClientsClaude Spec

For Claude Code, Anthropic SDKs, and clients calling /v1/messages:

https://api.nexabase.xyz

Authentication

Authenticate requests by passing your API key in the headers. You can generate and manage API keys in the Nexa Dashboard → API keys. All keys are prefixed with sk-nexa_.

Header	Format	Used For
`Authorization`	`Bearer sk-nexa_...`	OpenAI SDK, standard REST requests, Responses & Chat endpoints
`x-api-key`	`sk-nexa_...`	Anthropic Claude clients, Claude Code, Anthropic SDKs
`anthropic-version`	`2023-06-01`	Required when making calls to the Anthropic Messages endpoint

Quick Start

Make your first request using cURL, Node.js, or Python in less than 30 seconds:

curl https://api.nexabase.xyz/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEXA_API_KEY" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      { "role": "user", "content": "Hello Nexa!" }
    ],
    "temperature": 0.7
  }'

Architecture & Resilience

Smart Normalization & Cross-Compatibility

Nexa features an intelligent request normalization engine that bridges differences between client SDKs, IDE extensions, and legacy CLI tools. Requests never fail over minor syntax or parameter mismatches.

Cross-Payload AdaptationAutomatic

If an agent calls /v1/chat/completions with "input" or "prompt" instead of "messages", Nexa seamlessly adapts it to standard message roles. Similarly, /v1/responses accepts "messages", and /v1/messages injects a safe default max_tokens: 4096 if omitted.

Dual Authentication & RoutingInterchangeable

Both Authorization: Bearer sk-nexa_... and x-api-key: sk-nexa_... work across all endpoints. Furthermore, both standard prefixes (/v1/chat/completions) and root routes (/chat/completions) are routed identically.

POST/v1/chat/completions

Creates a model response for the given chat conversation. Supports standard OpenAI schema, streaming SSE (Server-Sent Events), function calling/tools, and multi-turn message history.

Request Headers

Header	Required	Description
`Authorization`	Yes	`Bearer sk-nexa_...`
`Content-Type`	Yes	`application/json`

Request Body

Parameter	Type	Required	Default	Description
`model`	`string`	Yes	`gpt-5.6-terra`	Model ID or alias (e.g. `gpt-5.6-terra`, `claude-sonnet-5`, `deep-pro`).
`messages`	`array`	Yes	—	Array of message objects: `[{ "role": "system"\|"user"\|"assistant", "content": "..." }]`.
`stream`	`boolean`	No	`false`	If true, returns partial message deltas as Server-Sent Events (SSE).
`temperature`	`number`	No	`1.0`	Sampling temperature between 0 and 2. Higher values mean more creative responses.
`max_tokens`	`integer`	No	`null`	Maximum number of tokens to generate in the completion.

Response Example (200 OK)

application/json

{
  "id": "chatcmpl-9abc123",
  "object": "chat.completion",
  "created": 1718000000,
  "model": "gpt-5.6-terra",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Make something worth building."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 6,
    "total_tokens": 18
  }
}

POST/v1/responses

The OpenAI Responses API format. Accepts input (or automatically normalizes messages or prompt). Ideal for agents, automated workflows, and tools that interact with the OpenAI Responses specification.

Request Body

Parameter	Type	Required	Description
`model`	`string`	Yes	Canonical model ID or alias (default: `gpt-5.6-terra`).
`input`	`string \| array`	Yes	Input prompt or messages array.
`instructions`	`string`	No	Optional system instructions for the model.
`stream`	`boolean`	No	Whether to stream partial results.

Example Request

curl https://api.nexabase.xyz/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEXA_API_KEY" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": "Make something worth building."
  }'

Response Example (200 OK)

application/json

{
  "id": "resp_9abc12345xyz",
  "object": "response",
  "created": 1718000000,
  "model": "gpt-5.6-terra",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Make something worth building."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6,
    "total_tokens": 18
  }
}

POST/v1/messages

Directly compatible with Anthropic's Claude Messages API. Supports Claude Code CLI, Anthropic Python and TypeScript SDKs, Claude Desktop, and raw HTTP calls.

Request Headers

Header	Required	Description
`x-api-key`	Yes	`sk-nexa_...` (or `Authorization: Bearer sk-nexa_...`)
`anthropic-version`	Yes	`2023-06-01`
`Content-Type`	Yes	`application/json`

Request Body

Parameter	Type	Required	Description
`model`	`string`	Yes	E.g. `claude-sonnet-5`, `claude-opus-5`, or alias `claude-3-5-sonnet`.
`messages`	`array`	Yes	Array of message objects: `[{ "role": "user", "content": "..." }]`.
`max_tokens`	`integer`	Yes	Maximum output tokens (e.g. `1024` or `4096`).
`system`	`string`	No	System prompt context.
`stream`	`boolean`	No	Stream event chunks (`content_block_delta`).

Example Request

curl https://api.nexabase.xyz/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $NEXA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "Write a fibonacci function in Go." }
    ]
  }'

Response Example (200 OK)

application/json

{
  "id": "msg_01XyZ987AbC123",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5",
  "content": [
    {
      "type": "text",
      "text": "func fib(n int) int {\n    if n <= 1 {\n        return n\n    }\n    return fib(n-1) + fib(n-2)\n}"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 18,
    "output_tokens": 42
  }
}

GET/v1/models

Returns a list of all models currently accessible to your authenticated API key, including metadata such as context window and model owners.

cURL

curl https://api.nexabase.xyz/v1/models \
  -H "Authorization: Bearer $NEXA_API_KEY"

Single Model Lookup

GET/v1/models/:modelId

Retrieve metadata for a specific model ID (e.g. /v1/models/gpt-5.6-terra).

Response Example (200 OK)

application/json

{
  "object": "list",
  "data": [
    {
      "id": "gpt-6-astra",
      "object": "model",
      "created": 1718000000,
      "owned_by": "nexa"
    },
    {
      "id": "claude-sonnet-5",
      "object": "model",
      "created": 1718000000,
      "owned_by": "nexa"
    },
    {
      "id": "gpt-5.6-terra",
      "object": "model",
      "created": 1718000000,
      "owned_by": "nexa"
    },
    {
      "id": "deepseek-v4-pro",
      "object": "model",
      "created": 1718000000,
      "owned_by": "nexa"
    }
  ]
}

GET/v1/usage

Retrieve token consumption and usage telemetry for the authenticated API key. You can also query specific requests with GET /v1/usage/:id.

cURL

curl https://api.nexabase.xyz/v1/usage \
  -H "Authorization: Bearer $NEXA_API_KEY"

Response Example (200 OK)

application/json

{
  "object": "usage",
  "total_tokens": 452100,
  "prompt_tokens": 312000,
  "completion_tokens": 140100,
  "total_requests": 142
}

GET/health

Public health check endpoint. Requires no authentication. Useful for load balancers and uptime monitors.

cURL

curl https://api.nexabase.xyz/health

Response Example

{
  "status": "ok",
  "service": "nexa-api",
  "timestamp": "2026-10-17T11:45:00.000Z"
}

GET/downloads/:filename

Direct high-speed CDN download endpoint for Nexa CLI installer archives, releases, and version manifests. Publicly accessible without authentication.

File	Content-Type	Description
`nexa-setup-latest.tgz`	`application/x-gtar-compressed`	Self-contained CLI installer tarball (executed by `npx`).
`nexa-setup-latest.json`	`application/json`	Version update manifest with SHA256 checksum.
`nexa-setup-1.0.0.tgz`	`application/x-gtar-compressed`	Pinned release archive.

cURL

curl -O https://api.nexabase.xyz/downloads/nexa-setup-latest.tgz

Supported Models

Nexa provides access to top reasoning, general, and fast models from multiple frontier providers with transparent multipliers and context limits:

Model ID	Display Name	Family	Type	Multiplier	Context Window
`gpt-6-astra`	GPT-6 Astra	GPT	Reasoning	`8x`	1.05M
`claude-opus-5`	Claude Opus 5	Claude	Reasoning	`5x`	1M
`claude-opus-4.8`	Claude Opus 4.8	Claude	Reasoning	`4x`	1M
`claude-opus-4.7`	Claude Opus 4.7	Claude	Reasoning	`4x`	1M
`claude-opus-4.6`	Claude Opus 4.6	Claude	Reasoning	`4x`	1M
`claude-sonnet-5`	Claude Sonnet 5	Claude	General	`2.5x`	1M
`claude-sonnet-4.6`	Claude Sonnet 4.6	Claude	General	`2x`	1M
`gpt-5.6-sol`	GPT-5.6 Sol	GPT	General	`4x`	1.05M
`gpt-5.5`	GPT-5.5	GPT	General	`4x`	1.05M
`gpt-5.6-terra`	GPT-5.6 Terra	GPT	General	`3x`	1.05M
`gpt-5.6-luna`	GPT-5.6 Luna	GPT	General	`1.7x`	1.05M
`deep-pro`	DeepSeek V4 Pro	DeepSeek	General	`2x`	1M
`deep-flash`	DeepSeek V4 Flash	DeepSeek	Fast	`0.8x`	1M

Automatic Model Aliases

To prevent breaking existing tool configs and workflows, Nexa's payload normalizer automatically resolves common model aliases to the canonical model IDs:

Passed Model Name (Alias)	Resolved Canonical ID	Family	Description
`gpt-4o, gpt-4, o3-mini`	`gpt-5.6-terra`	GPT	General high-capacity model (default)
`gpt-4o-mini, gpt-3.5-turbo`	`gpt-5.6-luna`	GPT	Fast, low-latency completions
`o1`	`gpt-6-astra`	GPT	Deep reasoning and logic
`claude-sonnet, claude-3-5-sonnet, claude-3-7-sonnet`	`claude-sonnet-5`	Claude	Balanced coding & reasoning
`claude-opus, claude-3-opus`	`claude-opus-5`	Claude	Flagship intelligence & reasoning
`deep-pro, deepseek-chat, deepseek-reasoner, deepseek-v4`	`deepseek-v4-pro`	DeepSeek	Flagship open weights model
`deep-flash, deepseek-flash`	`deepseek-v4-flash`	DeepSeek	Ultra-fast inference & streaming

Note: Context variant brackets (e.g. [128k], [1m]) appended by some tools are automatically stripped during normalization.

Codex CLI & App Setup

Connect Codex CLI or Codex App to Nexa by pointing OpenAI environment variables to our gateway:

# In your ~/.zshrc or ~/.bashrc:
export OPENAI_BASE_URL="https://api.nexabase.xyz/v1"
export OPENAI_API_KEY="sk-nexa_your_api_key_here"

Claude Code Setup

Connect Claude Code to Nexa by setting the Anthropic base URL environment variable:

# In your terminal before running claude:
export ANTHROPIC_BASE_URL="https://api.nexabase.xyz"
export ANTHROPIC_API_KEY="sk-nexa_your_api_key_here"

# Run Claude Code:
claude

OpenCode Setup

Configure OpenCode's configuration file (~/.config/opencode/config.json):

{
  "provider": "openai-compatible",
  "baseURL": "https://api.nexabase.xyz/v1",
  "apiKey": "sk-nexa_your_api_key_here"
}

Automated Setup

Nexa Setup CLI

Connect Codex CLI, Codex App, Claude Code, Claude Desktop, and OpenCode with a single interactive command. Detects running clients, performs atomic backups of config files, and automatically configures providers.

Run without installing

macOS / Linux / WSL

npx --yes https://api.nexabase.xyz/downloads/nexa-setup-latest.tgz

Windows PowerShell

npx.cmd --yes https://api.nexabase.xyz/downloads/nexa-setup-latest.tgz

After first run, the nexa command is available in any new terminal. Use nexa set to manage default tools, API keys, or automation toggles.

View full Installer CLI manual & options arrow_forward

Errors & Status Codes

Nexa returns standard HTTP status codes and structured error payloads for seamless debugging:

Status	Error Code	Reason & Remediation
`400`	`invalid_request_error`	Missing required fields (e.g. empty model, malformed JSON body).
`401`	`authentication_error`	Invalid or revoked API key, or missing Authorization / x-api-key header.
`403`	`authentication_error`	Account is disabled or suspended. Contact support.
`404`	`not_found`	Endpoint or resource not found.
`429`	`insufficient_quota`	Token balance is 0 or depleted. Top up balance in the Dashboard to resume.
`500`	`upstream_error`	Upstream model provider temporarily unavailable or encountered a service error.

Error Format Examples

OpenAI Format (/v1/chat, /v1/responses)

{
  "error": {
    "message": "You have exceeded your token balance (0 tokens remaining)...",
    "type": "insufficient_quota",
    "code": "insufficient_quota",
    "param": null
  }
}

Anthropic Format (/v1/messages)

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "code": "insufficient_quota",
    "message": "You have exceeded your token balance..."
  }
}