Skip to content

Setting up a custom integration

Follow the shared order on Client setup. For Anthropic Messages, send anthropic-version: 2023-06-01 and set max_tokens greater than zero. Nexus rejects the call when that header is missing.

Compatibility boundary

A custom integration is compatible with Nexus when it can set:

  • https://api.nexus-hub.tech/v1 for OpenAI Chat or Responses;
  • https://api.nexus-hub.tech for Anthropic Messages;
  • https://api.nexus-hub.tech/v1beta for Gemini-compatible routes;
  • Bearer or another supported API-key header;
  • a model from GET /v1/models;
  • JSON and, when needed, SSE streaming.

OpenAI Python SDK

The official SDK accepts base_url and api_key:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEXUS_API_KEY"],
    base_url="https://api.nexus-hub.tech/v1",
)
response = client.responses.create(
    model=os.environ["NEXUS_MODEL"],
    input="Reply exactly OK.",
    max_output_tokens=16,
)
print(response.output_text)

Set NEXUS_MODEL to a value from GET /v1/models. For Chat Completions, use client.chat.completions.create and its matching output limit.

Anthropic Python SDK

For Messages, set base_url without /v1. The SDK sends anthropic-version: 2023-06-01. max_tokens must be greater than zero:

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["NEXUS_API_KEY"],
    base_url="https://api.nexus-hub.tech",
)
message = client.messages.create(
    model=os.environ["NEXUS_MODEL"],
    max_tokens=16,
    messages=[{"role": "user", "content": "Reply exactly OK."}],
)
print(message.content)

Retries, timeouts, and streaming

Set timeouts explicitly and handle network interruptions using idempotency:

  • For safe retries on network drops or timeouts, pass the Idempotency-Key header (in official Python SDKs, use extra_headers={"Idempotency-Key": key}). Replays with the same key and request body return the cached response with Idempotency-Replayed: true and zero additional balance charges.
  • Do not reuse the same x-request-id for different logical requests: it is an attempt-level tracing identifier.
  • On 429 or 503 errors, inspect and respect the Retry-After header.
  • For streaming, consume SSE until the terminal event and close connections cleanly on error; do not write bodies to logs.
  • The complete retry matrix and lifecycle rules are detailed in Retries and idempotency.

Key hygiene and operations

  • Keep the key in an environment variable or secret manager.
  • Do not commit it or include it in exceptions, traces, screenshots, or prompts.
  • Revoke a compromised key and create a new one.
  • Send support only the method, route, error code, SDK version, and x-request-id.

Official SDKs: openai-python and anthropic-sdk-python. Route fields are documented in the Nexus API reference.