Skip to content

Supported Endpoints

Summary

Nexus supports nineteen public endpoints:

  • GET /v1/models
  • GET /v1/models/{model}
  • GET /v1/balance
  • GET /v1/realtime
  • POST /v1/chat/completions
  • POST /v1/completions
  • POST /v1/messages
  • POST /v1/messages/count_tokens
  • POST /v1/responses
  • POST /v1/responses/compact
  • POST /v1/embeddings
  • POST /v1/rerank
  • POST /v1/moderations
  • POST /v1/images/generations
  • POST /v1/images/edits
  • POST /v1/images/variations
  • POST /v1/audio/speech
  • POST /v1/audio/transcriptions
  • POST /v1/audio/translations

GET /v1/models

Returns the models available to your key.

Use this endpoint before configuring a client or when switching models.

GET /v1/models/{model}

Returns one specific model if it is available to your key.

Use this endpoint for a targeted model check, not to bypass the list: if the model is not visible to your key, Nexus returns a safe 404.

GET /v1/balance

Returns the current balance of the Nexus profile that owns the API key used for the request.

GET /v1/realtime

WebSocket endpoint for Realtime-compatible clients.

Pass the model in the query string, for example GET /v1/realtime?model=gpt-5.5.

This route checks the key, endpoint access, model access, and starting balance before the WebSocket upgrade. For supported text-only sessions, Nexus attempts to reserve balance before the first billable response.create and charges automatically only when it receives reliable final usage. If usage cannot be priced safely, the session is sent for manual review.

POST /v1/messages

Primary endpoint for Claude Code and Claude-compatible clients.

Supports streaming.

Claude models are available through this endpoint when they appear for your key in GET /v1/models.

POST /v1/messages/count_tokens

Endpoint for pre-counting tokens in Claude-compatible clients.

It does not charge balance and does not start a generation request.

POST /v1/chat/completions

Endpoint for OpenAI-compatible clients that use the chat.completions format.

Supports streaming.

Claude models with openai support can also use this endpoint.

POST /v1/completions

Endpoint for OpenAI-compatible clients that use the completions format.

Use the regular JSON response mode for this endpoint. prompt must be a string; batch prompts and token-id prompts return unsupported_prompt_shape.

POST /v1/responses

Primary endpoint for Codex and response-compatible clients.

Supports streaming.

POST /v1/responses/compact

Endpoint for compact response workflows.

Supports streaming.

POST /v1/embeddings

Endpoint for OpenAI-compatible embeddings requests.

It uses the regular JSON response mode.

POST /v1/rerank

Endpoint for rerank requests.

It uses the regular JSON response mode.

POST /v1/moderations

Endpoint for moderation requests.

It uses the regular JSON response mode.

POST /v1/images/generations

Endpoint for JSON image generation requests.

It expects application/json and a body no larger than 1 MiB.

POST /v1/images/edits

Endpoint for image edit requests with uploads.

It expects multipart/form-data and a body no larger than 25 MiB.

POST /v1/images/variations

Endpoint for image variation requests with uploads.

It expects multipart/form-data and a body no larger than 25 MiB.

POST /v1/audio/speech

Endpoint for text-to-speech JSON requests.

It expects application/json and a body no larger than 1 MiB.

Successful responses may return a binary audio body, so use raw response handling.

POST /v1/audio/transcriptions

Endpoint for uploaded audio transcription requests.

It expects multipart/form-data and a body no larger than 25 MiB.

POST /v1/audio/translations

Endpoint for uploaded audio translation requests.

It expects multipart/form-data and a body no larger than 25 MiB.

Media Preview

Media routes currently run as a preview surface.

Nexus still enforces the starting balance check before proxying them, but the final balance change for those routes may not appear immediately.

Output Token Limit

It is better to pass the response limit explicitly:

  • max_tokens for messages;
  • max_completion_tokens or max_tokens for chat.completions;
  • max_tokens for completions;
  • max_output_tokens for responses and responses/compact.

If the limit is not provided, Nexus applies a safe default automatically.

Which Endpoint to Choose

  • use POST /v1/messages for Claude Code;
  • use POST /v1/responses for Codex;
  • use GET /v1/realtime for Realtime-compatible WebSocket clients;
  • use POST /v1/chat/completions for OpenAI-compatible clients;
  • use POST /v1/images/generations for image generation;
  • use POST /v1/images/edits and POST /v1/images/variations for uploaded image edit or variation flows;
  • use POST /v1/audio/speech for text-to-speech;
  • use POST /v1/audio/transcriptions and POST /v1/audio/translations for uploaded speech-to-text flows;
  • use POST /v1/completions only for clients that still depend on the legacy completions API.