API Documentation

Welcome to the official NexusAI API documentation. Our API provides fast, scalable, and secure access to our state-of-the-art LLM, audio transcription, and diarization models.

Introduction

The NexusAI API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

The NexusAI API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard.

Authentication to the API is performed via HTTP Bearer Auth. Provide your API key as the bearer token value in the Authorization header.

Authorization: Bearer sk-live-xxxxxxxxxxxxxxxxxxxxxxxx

Base URL

All API requests are made to the OpenAI-compatible base URL. Point any OpenAI SDK or integration at it (with your NexusAI API key) and it works without further changes:

https://api.nexusai.com/v2

OpenAI-Compatible API (v2)

The v2 API mirrors the OpenAI API: endpoints, request parameters, response bodies, streaming events and error envelopes all match what official OpenAI SDKs expect. To migrate an existing OpenAI workflow, change only the base URL and the API key — everything else keeps working.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.nexusai.com/v2",
    api_key="sk-live-xxxxxxxxxxxxxxxx",  # your NexusAI API key
)

completion = client.chat.completions.create(
    model="standard",
    messages=[{"role": "user", "content": "Hello!"}],
)

Endpoints

Endpoint	Description
POST `/v2/chat/completions`	OpenAI Chat Completions. Supports `stream: true` (server-sent events, including the final usage chunk).
POST `/v2/responses`	OpenAI Responses API. Returns the standard OpenAI response object (or event stream with `stream: true`).
POST `/v2/audio/speech`	OpenAI Text to Speech (`model: "standard"`). Returns the raw audio file; set `stream_format` to `"audio"` or `"sse"` to stream chunks while the audio is generated. Output `response_format`: `wav` (default) or `pcm`, with an optional `sample_rate`.
POST `/v2/audio/transcriptions`	OpenAI Transcriptions. Upload an audio file (multipart `file` field, up to 25 MB); real-time when `stream=true`. Models: `standard` (default) and `mini`. `response_format`: `json` (default), `text` or `verbose_json`.
POST `/v2/conversations`	OpenAI Conversations — create a conversation (returns its `id`). Proxied to OpenAI; not billed. See Conversations.
GET `/v2/conversations/{conversation_id}`	Retrieve a conversation by id. Update (`POST`), delete (`DELETE`) and the `/items` sub-resources are also supported.

Example: streamed speech (server-sent events)

curl https://api.nexusai.com/v2/audio/speech \
  -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "standard",
    "input": "Streaming speech, chunk by chunk!",
    "response_format": "wav",
    "sample_rate": 48000,
    "stream_format": "sse"
  }'

Each event carries a base64 audio chunk ({"type": "speech.audio.delta", "audio": "..."}) followed by a final speech.audio.done event with the usage. With "stream_format": "audio" the raw audio bytes are streamed instead. Omit stream_format to receive the finished audio file in one response.

Example: streaming transcription

curl https://api.nexusai.com/v2/audio/transcriptions \
  -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxx" \
  -F file=@audio.wav \
  -F model=standard \
  -F stream=true

Streams OpenAI-style transcript.text.delta events, then a final transcript.text.done. Omit stream to receive the whole transcript in one response: { "text": "This is the transcribed audio..." }

Language Models

Create model response

Creates a model response for the given chat conversation.

POST /v2/responses

Example Request (cURL)

curl https://api.nexusai.com/v2/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxx" \
  -d '{
    "model": "standard",
    "input": [
      {
        "role": "system",
        "content": "You are a helpful coding assistant."
      },
      {
        "role": "user",
        "content": "Write a python function to fetch data."
      }
    ]
  }'

Request Body

Parameter	Type	Required	Description
`model`	string	Yes	ID of the model to use. Available models: `pro` - Highest capability and accuracy. `standard` - Balanced performance and speed. `mini` - Fastest response time for simpler tasks. View Pricing Details
`input`	array	Yes	A list of messages comprising the conversation so far. Each message object should have a `role` (e.g. "user", "system", "assistant") and `content`.

Response Example

{
  "status": "completed",
  "max_output_tokens": 2048,
  "model": "standard",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "text",
          "text": "Here is the python function you requested: ..."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 45,
    "output_tokens": 120,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 165
  }
}

Response Fields

Field	Type	Description
status	string	The overall status of the response generation (e.g. `completed`).
max_output_tokens	integer	The maximum number of tokens allowed to be generated in this request.
model	string	The requested tier name (`mini`, `standard`, `pro`).
output	array	Contains the response message(s). Each message includes its `role`, `status`, and `content` (an array containing the actual `text` response).
usage	object	Contains token usage statistics, including `input_tokens`, `output_tokens`, `total_tokens`, and detailed breakdown like `reasoning_tokens`.

Conversations

Create and manage conversation state that persists across /v2/responses calls. These endpoints are fully OpenAI-compatible and are proxied straight to OpenAI — NexusAI hosts nothing. Because they consume no model tokens, conversation management is not billed; you pay only for the /v2/responses calls that use the conversation.

POST /v2/conversations GET /v2/conversations/{conversation_id}

Example: create a conversation, then retrieve it by id (cURL)

curl https://api.nexusai.com/v2/conversations \
  -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "topic": "demo" } }'
# => { "id": "conv_abc123", "object": "conversation", "created_at": 1730000000, "metadata": { "topic": "demo" } }

curl https://api.nexusai.com/v2/conversations/conv_abc123 \
  -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxx"

Pass the returned id as the conversation field of a /v2/responses request to continue the thread — the server forwards it to OpenAI, which appends each turn to the conversation automatically.

Endpoints

Endpoint	Description
POST `/v2/conversations`	Create a conversation. Optional `metadata` and initial `items`. Returns the conversation object with its `id`.
GET `/v2/conversations/{conversation_id}`	Retrieve a conversation by id.
POST `/v2/conversations/{conversation_id}`	Update a conversation's `metadata`.
DELETE `/v2/conversations/{conversation_id}`	Delete a conversation.
GET `/v2/conversations/{conversation_id}/items`	List the items in a conversation (`limit`, `order`, `after`).
POST `/v2/conversations/{conversation_id}/items`	Add items (messages) to a conversation.
GET `/v2/conversations/{conversation_id}/items/{item_id}`	Retrieve a single item.
DELETE `/v2/conversations/{conversation_id}/items/{item_id}`	Delete a single item.

Text to Speech

Generate natural-sounding speech from text, billed from $0.04 per 1,000 input characters. The voice you choose determines the model automatically. Fully OpenAI-compatible — both client.audio.speech.create(...) and client.audio.speech.with_streaming_response.create(...) work unchanged.

POST /v2/audio/speech

Example Request (cURL)

curl https://api.nexusai.com/v2/audio/speech \
  -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Today is a wonderful day to build something people love!",
    "voice": "um-en_us-thalia",
    "response_format": "wav",
    "sample_rate": 48000
  }' --output speech.wav

Request Body

Parameter	Type	Required	Description
`input`	string	Yes	The text to synthesise. Maximum 4,096 characters. Billed per 1,000 characters.
`response_format`	string	No	Output format: `wav` (default) or `pcm`.
`sample_rate`	integer	No	Output sample rate in Hz. One of `8000`, `16000`, `44000`, `48000`.
`stream_format`	string	No	Stream while generating: `audio` (raw audio chunks over chunked HTTP) or `sse` (`speech.audio.delta` / `speech.audio.done` events). Omit for a single buffered response.
`language`	string	No	Language of the input text as an ISO code (e.g. `en`, `es`).
`voice`	string	Yes	The voice `code` to speak with. The code alone selects the model, so no `model` parameter is required. See the Voices catalogue below for the valid codes.

Response

On success the response body is the raw audio file, with a Content-Type matching response_format (audio/wav or audio/L16) and the X-Tts-Job-Id, X-Tts-Cost and X-Tts-Format headers. With a stream_format set, the audio is streamed as it is generated. Every conversion is saved to your account and listed under Text to Speech in the dashboard.

Voices

Pass one of the following code values in the voice parameter. The chosen code determines the model automatically.

Code	Name	Language	Accent	Gender
`um-en_us-odysseus`	Odysseus	English	American	Masculine
`um-en_us-thalia`	Thalia	English	American	Feminine
`um-fr-agathe`	Agathe	French	—	Feminine
`um-fr-hector`	Hector	French	—	Masculine
`um-ja-fujin`	Fujin	Japanese	—	Masculine
`um-ja-izanami`	Izanami	Japanese	—	Feminine
`um-es_mx-olivia`	Olivia	Spanish	Mexican	Feminine
`um-es_mx-sirio`	Sirio	Spanish	Mexican	Masculine

Speech to Text

Two modes share the /v2/audio/transcriptions resource: real-time transcription of an uploaded file, and asynchronous batch transcription of a remote URL (with optional speaker diarization).

Real-time transcription

POST /v2/audio/transcriptions — multipart upload

Upload an audio file (up to 25 MB). Models: standard (default, $0.45/hour) and mini ($0.36/hour). Set stream=true for a real-time token stream. The standard model requires 16-bit PCM WAV audio; mini accepts compressed formats (mp3, m4a, …).

curl https://api.nexusai.com/v2/audio/transcriptions \
  -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxx" \
  -F file=@audio.wav \
  -F model=standard \
  -F language=es \
  -F stream=true

Parameters (multipart form fields)

Parameter	Type	Description
`file` Required	file	The audio to transcribe (up to 25 MB).
`model`	string	`standard` (default) or `mini`.
`language`	string	ISO 639-1 language code (e.g. `en`, `es`). Auto-detected when omitted.
`response_format`	string	`json` (default), `text` or `verbose_json`. Ignored when streaming.
`stream`	boolean	When `true`, stream results in real time.

With stream=true the response is a text/event-stream of transcript.text.delta events followed by a final transcript.text.done. Otherwise the whole transcript is returned in one response: { "text": "..." } (or a verbose_json object).

Asynchronous transcription

Transcribe a long remote file in the background, with optional speaker diarization (+$0.03/hour). Send a JSON body with audio_url instead of a file; you receive a job id to poll. Billed at $0.22/hour.

POST /v2/audio/transcriptions — JSON body

curl https://api.nexusai.com/v2/audio/transcriptions \
  -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://.../audio.mp3",
    "diarize": true,
    "language": "en"
  }'

Parameters (JSON body)

Parameter	Type	Description
`audio_url` Required	string	Publicly reachable WAV or MP3 URL, up to 200 MB.
`diarize`	boolean	Enable speaker diarization ("who spoke when"). Adds $0.03/hour.
`language`	string	ISO 639-1 language code. Auto-detected when omitted.

The submit returns { "id": "...", "status": "processing" }. The estimated cost is charged upfront and refunded automatically if the job fails.

Poll the job

GET /v2/audio/transcriptions/{id}

curl https://api.nexusai.com/v2/audio/transcriptions/abc123def \
  -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxx"

While the job runs it returns { "id": "...", "status": "processing" }; on failure { "id": "...", "status": "error", "error": { ... } } (fully refunded). When complete:

{
  "id": "abc123def",
  "status": "completed",
  "text": "This is the transcription of the audio.",
  "language": "en",
  "duration": 345,
  "segments": [
    { "id": 0, "start": 0.1, "end": 3.5, "text": "This is the transcription", "speaker": "A", "confidence": 0.95 }
  ]
}

Each segment carries a speaker label when diarize is enabled. Timestamps are in seconds.

NexusAI API Documentation

Introduction

Authentication

Base URL

OpenAI-Compatible API (v2)

Endpoints

Example: streamed speech (server-sent events)

Example: streaming transcription

Language Models

Create model response

Example Request (cURL)

Request Body

Response Example

Response Fields

Conversations

Example: create a conversation, then retrieve it by id (cURL)

Endpoints

Text to Speech

Example Request (cURL)

Request Body

Response

Voices

Speech to Text

Real-time transcription

Parameters (multipart form fields)

Asynchronous transcription

Parameters (JSON body)

Poll the job