Setting up Direct API and cURL

The shared order is on Client setup. One key works for every protocol below. Messages requires the header anthropic-version: 2023-06-01 and max_tokens greater than zero. Nexus rejects a Messages call that omits that header.

Quick start

1. Get a Nexus API key in the Telegram bot and keep it in a secret manager or environment variable.
2. Query GET /v1/models: the catalog is specific to the key.
3. Choose a protocol that matches your application: OpenAI, Anthropic, or Gemini.
4. Send x-request-id so safe diagnostics can be correlated with support.

export NEXUS_API_KEY='YOUR_NEXUS_API_KEY'
export NEXUS_MODEL='MODEL_FROM_V1_MODELS'

curl --fail-with-body https://api.nexus-hub.tech/v1/models \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H 'x-request-id: docs-models-001'

OpenAI Responses

curl --fail-with-body https://api.nexus-hub.tech/v1/responses \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'x-request-id: docs-responses-001' \
  -d '{"model":"MODEL_FROM_V1_MODELS","input":"Reply exactly OK.","max_output_tokens":16}'

Streaming:

curl -N https://api.nexus-hub.tech/v1/responses \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"MODEL_FROM_V1_MODELS","input":"Reply exactly OK.","max_output_tokens":16,"stream":true}'

Anthropic Messages

curl --fail-with-body https://api.nexus-hub.tech/v1/messages \
  -H "x-api-key: $NEXUS_API_KEY" \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  -H 'x-request-id: docs-messages-001' \
  -d '{"model":"MODEL_FROM_V1_MODELS","max_tokens":16,"messages":[{"role":"user","content":"Reply exactly OK."}]}'

Add "stream":true for SSE. max_tokens must be greater than zero, and the anthropic-version: 2023-06-01 header is required. Use POST /v1/messages/count_tokens for a no-charge preflight count. That route requires the same version header.

Gemini-compatible

curl --fail-with-body 'https://api.nexus-hub.tech/v1beta/models/MODEL_FROM_V1_MODELS:generateContent' \
  -H "x-goog-api-key: $NEXUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contents":[{"role":"user","parts":[{"text":"Reply exactly OK."}]}],"generationConfig":{"maxOutputTokens":16}}'

Use streamGenerateContent for streaming; Gemini names are listed by GET /v1beta/models. If the model is present in both the path and body, the values must match.

Idempotency and safe retries

To prevent duplicate charges on network timeouts or disconnections, send the Idempotency-Key header:

curl --fail-with-body https://api.nexus-hub.tech/v1/chat/completions \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-unique-request-uuid-123' \
  -d '{"model":"MODEL_FROM_V1_MODELS","messages":[{"role":"user","content":"Reply exactly OK."}]}'

• On network failure or timeout, retry with the same Idempotency-Key and identical request body.
• The replay returns the original result with Idempotency-Replayed: true and zero additional balance debits.
• Valid key format: 1 to 256 printable ASCII characters.
• Detailed retry scenarios, errors, and lifecycle rules are documented in Retries and idempotency.

Errors and safe diagnostics

• 401 / invalid_key: check the variable and key lifetime.
• model_not_found or model_not_allowed: the model is not in this key's catalog.
• endpoint_not_allowed: this key cannot use the selected route.
• invalid_request_error: check the protocol, required output limit, and body size.
• streaming_not_supported: disable streaming for that route.

Send support the method, route, error code, and x-request-id. Do not send the key, full prompt, request body, or logs containing headers.

Full contract: API reference, endpoint list, and authentication.