API guide · Private access

Connect your AI client

Use your NesusAITech client key as a Bearer token. Your application never needs an upstream provider credential.

1. Check access and discover models

Replace the placeholder with a client key provisioned for your account. Keep it in an environment variable or your client’s secret store.

export NESUS_API_KEY='nes_live_YOUR_KEY'
export NESUS_BASE_URL='http://127.0.0.1:8000'

curl -sS "$NESUS_BASE_URL/health"
curl -sS "$NESUS_BASE_URL/readiness"
curl -sS "$NESUS_BASE_URL/v1/models" \
  -H "Authorization: Bearer $NESUS_API_KEY"

/health checks the process, /readiness checks dependencies, and authenticated /v1/models returns only models available to that key. An empty data list means no model is currently enabled for inference.

2. OpenAI SDK — Python

For OpenAI-compatible Chat Completions or Responses clients, use the gateway root as the SDK base URL. The SDK adds /chat/completions or /responses below /v1.

export OPENAI_API_KEY="$NESUS_API_KEY"
export OPENAI_BASE_URL="$NESUS_BASE_URL/v1"

python -m pip install openai
python - <<'PY'
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"], base_url=os.environ["OPENAI_BASE_URL"])
print(client.models.list())
# After an exact model is enabled for your key:
# result = client.chat.completions.create(
#     model="EXACT_MODEL_ID_FROM_MODELS",
#     messages=[{"role": "user", "content": "Reply with OK"}],
#     max_tokens=32,
# )
# print(result.choices[0].message.content)
PY

Install the SDK in your own environment; it is not a gateway runtime dependency. The inference example is intentionally commented while the live model catalog is empty.

3. OpenAI SDK — Node.js

export OPENAI_API_KEY="$NESUS_API_KEY"
export OPENAI_BASE_URL="$NESUS_BASE_URL/v1"
npm install openai

node --input-type=module - <<'JS'
import OpenAI from "openai";
const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL,
});
console.log(await client.models.list());
// Once a model is enabled, call chat.completions.create with its exact ID.
JS

4. Anthropic SDK and Messages

Anthropic-compatible clients call POST /v1/messages. Configure the API root as the base URL. Standard Anthropic clients send the NesusAITech key in x-api-key; Bearer authorization is also accepted.

export ANTHROPIC_API_KEY="$NESUS_API_KEY"
export ANTHROPIC_BASE_URL="$NESUS_BASE_URL"

python -m pip install anthropic
python - <<'PY'
import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"], base_url=os.environ["ANTHROPIC_BASE_URL"])
# After an exact model is enabled for your key:
# print(client.messages.create(
#     model="EXACT_MODEL_ID_FROM_MODELS", max_tokens=32,
#     messages=[{"role": "user", "content": "Reply with OK"}],
# ))
PY

The gateway translates supported text, tool-call and streaming formats through the configured route. Provider-specific fields are not universally supported; unsupported request fields are rejected.

5. curl — Chat Completions, Responses, Messages

curl -sS "$NESUS_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $NESUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"EXACT_MODEL_ID_FROM_MODELS","messages":[{"role":"user","content":"Reply with OK"}],"max_tokens":32}'

curl -sS "$NESUS_BASE_URL/v1/responses" \
  -H "Authorization: Bearer $NESUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"EXACT_MODEL_ID_FROM_MODELS","input":"Reply with OK","max_output_tokens":32,"store":false}'

curl -sS "$NESUS_BASE_URL/v1/messages" \
  -H "x-api-key: $NESUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"EXACT_MODEL_ID_FROM_MODELS","max_tokens":32,"messages":[{"role":"user","content":"Reply with OK"}]}'

Do not send prompts to the placeholder model ID. First discover an enabled model with /v1/models. Requests are bounded, authenticated, rate-limited and credit-reserved before provider work; usage is settled from provider token counts. Prompts and completions are not stored by default.

6. OpenCode and Aider

OpenCode can use an OpenAI-compatible custom provider. Add a provider entry to ~/.config/opencode/opencode.json, replacing the model ID only after model discovery:

{
  "provider": {
    "nesusaitech": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "NesusAITech",
      "options": {
        "baseURL": "http://127.0.0.1:8000/v1",
        "apiKey": "{env:NESUS_API_KEY}"
      },
      "models": {
        "EXACT_MODEL_ID_FROM_MODELS": { "name": "NesusAITech model" }
      }
    }
  }
}

Aider accepts an OpenAI-compatible model and API base URL:

export OPENAI_API_BASE="$NESUS_BASE_URL/v1"
export OPENAI_API_KEY="$NESUS_API_KEY"
# After model activation:
# aider --model openai/EXACT_MODEL_ID_FROM_MODELS

Client configuration compatibility does not imply that a model or route is active. Responses, tools, streaming and model-specific fields depend on the documented gateway and upstream capabilities.

Supported endpoints and behavior

• GET /v1/models — authenticated, key-scoped model discovery. GET /models is an authenticated alias with the same response.
• POST /v1/chat/completions — bounded text and client-side function-tool requests; SSE requires route opt-in.
• POST /v1/responses — text/function-call items; storage is disabled; SSE uses Responses event names.
• POST /v1/messages — Anthropic Messages text and client-side function-tool format.

OpenAI-compatible endpoints return errors in an error object; Messages uses the Anthropic error envelope. The gateway returns tool calls to your application and never executes your functions. Send tool results in a follow-up request. Tools require explicit capability on a healthy, authorized route; streaming tools also require streaming opt-in. Image input, stateful conversation fields, and unsupported provider features are rejected. Exact model requests never silently switch to a different public model.

Accounts and key handling

Public signup and account recovery are disabled. An operator provisions accounts; sign in at the dashboard to review usage, manage client keys and change your password. Keys can be limited to specific API scopes and model IDs, and can have daily/monthly credit caps. A child key cannot exceed its parent key's permissions or limits. Treat client keys like passwords: do not commit them, put them in source code, or send them to support. Revoke a key immediately if it may have been exposed. Existing unrestricted keys keep their current access unless their owner replaces them with a restricted key.