Use my Nexus access

Make a first request with the Gateway Base URL and Inference Key your application supplied.

Goal

保留你已有的 OpenAI-compatible SDK 或 OpenCode，只替换 Base URL 和 API Key，完成首次 Nexus Gateway 请求。

Outcome

请求使用应用分配给你的 Access 和 Quota，并由明确的 providerConnectionId UUID 选择 Workspace 内的一条 ProviderConnection；模型名和 Provider Payload 保持原样。

Who this is for

已经从应用安全收到 Nexus 访问信息的最终用户、用户 Agent 或集成工程师。

Prerequisites

你需要三项值：

NEXUS_BASE_URL：形如 https://gateway.nexus.microvoid.io/providers/<providerConnectionId>。
NEXUS_API_KEY：Nexus Inference Key，不是 Provider Key 或 Management Key。
NEXUS_MODEL：该 ProviderConnection 上游接受的原始模型名。

平台方应通过私密渠道交付 Key。不要把 Key 写入源码、URL、浏览器持久化存储、Analytics 或日志。

1. Replace Base URL and Key

E2E Fixture 固定了唯一需要变化的客户端字段：

OpenAI JavaScript clientdiff

 const client = new OpenAI({
-  baseURL: "https://openrouter.ai/api/v1",
-  apiKey: process.env.PROVIDER_API_KEY,
+  baseURL: "https://gateway.nexus.microvoid.io/providers/00000000-0000-0000-0000-000000000141",
+  apiKey: process.env.NEXUS_API_KEY,
 });

OpenAI Python clientdiff

 client = OpenAI(
-    base_url="https://openrouter.ai/api/v1",
-    api_key=os.environ["PROVIDER_API_KEY"],
+    base_url="https://gateway.nexus.microvoid.io/providers/00000000-0000-0000-0000-000000000141",
+    api_key=os.environ["NEXUS_API_KEY"],
 )

2. Choose a client

Terminalsh

npm install openai@6.48.0

openai-javascript.mjsjs

import OpenAI from 'openai';

function requiredEnvironment(name) {
  const value = process.env[name]?.trim();
  if (!value) throw new Error(`${name} is required`);
  return value;
}

const client = new OpenAI({
  baseURL: requiredEnvironment('NEXUS_BASE_URL'),
  apiKey: requiredEnvironment('NEXUS_API_KEY'),
  maxRetries: 0,
});

const completion = await client.chat.completions.create({
  model: requiredEnvironment('NEXUS_MODEL'),
  messages: [{ role: 'user', content: 'Keep this request unchanged.' }],
  temperature: 0.37,
});

console.log(
  JSON.stringify({
    model: completion.model,
    content: completion.choices[0]?.message.content,
  }),
);

Terminalsh

node openai-javascript.mjs

Terminalsh

python3 -m venv .venv
. .venv/bin/activate
pip install openai==2.46.0

openai-python.pypython

"""Public OpenAI Python SDK quickstart executed by the Nexus compatibility E2E suite."""

import json
import os

import openai
from openai import OpenAI


def required_environment(name: str) -> str:
    value = os.environ.get(name, "").strip()
    if not value:
        raise RuntimeError(f"{name} is required")
    return value


client = OpenAI(
    base_url=required_environment("NEXUS_BASE_URL"),
    api_key=required_environment("NEXUS_API_KEY"),
    max_retries=0,
    timeout=10.0,
)
model = required_environment("NEXUS_MODEL")
messages = [{"role": "user", "content": "Keep this Python request unchanged."}]

completion = client.chat.completions.create(model=model, messages=messages)
stream = client.chat.completions.create(
    model=model,
    messages=messages,
    stream=True,
    stream_options={"include_usage": True},
)
stream_text = ""
stream_usage = None
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        stream_text += chunk.choices[0].delta.content
    if chunk.usage is not None:
        stream_usage = chunk.usage.total_tokens

print(
    json.dumps(
        {
            "sdk_version": openai.__version__,
            "model": completion.model,
            "content": completion.choices[0].message.content,
            "stream_text": stream_text,
            "stream_usage": stream_usage,
        }
    )
)

Terminalsh

python openai-python.py

把下面的受测 Fixture 保存为项目根目录的 opencode.json：

opencode.jsonjson

{
  "$schema": "https://opencode.ai/config.json",
  "model": "nexus-openrouter/provider/opaque-model-v9",
  "provider": {
    "nexus-openrouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Nexus OpenRouter",
      "options": {
        "baseURL": "https://gateway.nexus.microvoid.io/providers/00000000-0000-0000-0000-000000000141",
        "apiKey": "{env:NEXUS_API_KEY}"
      },
      "models": {
        "provider/opaque-model-v9": {
          "name": "Provider opaque model"
        }
      }
    }
  }
}

Terminalsh

export NEXUS_API_KEY="<NEXUS_INFERENCE_KEY>"
opencode

启动后，配置中的 nexus-openrouter/provider/opaque-model-v9 会选择该 OpenCode Provider 配置及其原始模型 ID。OpenCode 的自定义 Provider 格式可参阅其官方 Provider 文档。

JavaScript/Python 使用这些环境变量；示例 UUID 和模型名是无 Secret 的兼容性 Fixture，请替换为应用交付的值：

Terminalsh

export NEXUS_BASE_URL="https://gateway.nexus.microvoid.io/providers/00000000-0000-0000-0000-000000000141"
export NEXUS_API_KEY="<NEXUS_INFERENCE_KEY>"
export NEXUS_MODEL="provider/opaque-model-v9"

3. Check the response

成功响应应保留上游响应格式和原始模型名。记录 x-nexus-request-id，并检查 x-nexus-metering-status、x-nexus-quota-remaining 与 x-nexus-quota-reset。

Python 示例同时执行普通与 Streaming 请求，并读取末尾 Usage；JavaScript 和 OpenCode Fixture 也由同一套 Node/Cloudflare E2E Gateway 行为验证。

Check your work

代码只改了 Base URL 和 Key；没有增加 Nexus 专用请求字段。
Gateway Base URL 包含完整 UUID，后面由 SDK 添加 Provider path。
model 是所选上游 Provider 接受的原始值。
应用方能用 Request ID 在 Usage/Activity 中找到你的请求。

What Nexus stored

请求归因、Quota Reservation/Settlement、Usage 与 Audit 元数据。Nexus MVP 默认不把 Prompt/Response 正文作为授权事实保存。

What the user received

你只需要 Gateway Base URL、Inference Key 和原始模型名。Provider Key 留在平台方的加密 ProviderConnection 中。

Troubleshooting

401：确认环境变量使用 Inference Key，且 Key 未撤销或到期。
404：确认 Base URL 的 UUID 完整并属于该 Key 解析出的 Workspace。
429：联系应用方检查 Access 的当前 QuotaPeriod。
Streaming 无 Usage：确认上游协议支持受测的 Usage Inspector 路径，并保留 Request ID。

Next steps

查看独立的 OpenAI JavaScript、OpenAI Python 或 OpenCode 页面以复制单一客户端版本。