NexusAI 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

The API is offered in two versions:

• v1 — the original NexusAI API, with asynchronous audio jobs:

https://api.nexusai.com/v1

• v2 — a fully OpenAI-compatible API. Point any OpenAI SDK or integration at this base URL (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

Models

The model parameter accepts our tier names — mini, standard and pro (see pricing). For drop-in compatibility, any other model id sent by an unmodified integration is accepted and billed at the closest tier, so requests never fail on the model name alone. The audio endpoints accept (and ignore) OpenAI audio model names such as tts-1 and whisper-1.

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 '{
    "input": "Streaming speech, chunk by chunk!",
    "voice": "nova",
    "response_format": "mp3",
    "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 token 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: transcription

curl https://api.nexusai.com/v2/audio/transcriptions \
  -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxx" \
  -F file=@audio.mp3 \
  -F model=whisper-1

{ "text": "This is the transcribed audio..." }

Language Models

Create model response

Creates a model response for the given chat conversation.

POST /v1/responses

Example Request (cURL)

curl https://api.nexusai.com/v1/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

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

Text to Speech

Generate natural-sounding speech from text. The v1 flow is a two-step asynchronous process, like transcriptions: submit the generation job, then poll it until the audio is ready. For a synchronous, OpenAI-compatible call (including streaming), use /v2/audio/speech instead — both accept the same parameters.

1. Create speech job

POST /v1/audio/speech

Submit text and a voice; the endpoint charges the estimated cost, starts the generation and returns a job id to poll. The generated audio is also stored in your account and listed under Text to Speech in your dashboard.

Example Request (cURL)

curl https://api.nexusai.com/v1/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": "nova",
    "instructions": "Speak in a cheerful and positive tone.",
    "response_format": "mp3"
  }'

Request Body

Response Example

{
  "id": "tts-1a2b3c4d5e6f7a8b9c0d1e2f",
  "status": "queued",
  "voice": "nova",
  "response_format": "mp3",
  "speed": 1.0,
  "created_at": 1754500000
}

The estimated cost is charged when the job is accepted and refunded automatically if the generation fails.

2. Poll the job / download the audio

GET /v1/audio/speech/{id}

Poll this endpoint every second or two. While the job is still running it returns a JSON status object; as soon as the audio is ready the same call returns the binary audio file instead — check the response Content-Type to tell the two apart.

curl https://api.nexusai.com/v1/audio/speech/tts-1a2b3c4d5e6f7a8b9c0d1e2f \
  -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxx" \
  --output speech.mp3

Pending Response

{
  "id": "tts-1a2b3c4d5e6f7a8b9c0d1e2f",
  "status": "processing",
  "voice": "nova",
  "response_format": "mp3",
  "speed": 1.0
}

Possible status values are queued, processing and error (failed jobs include an error field and are fully refunded). On success the response body is the audio file, served with the Content-Type matching the requested response_format (e.g. audio/mpeg for MP3), plus the X-Tts-Job-Id, X-Tts-Cost and X-Tts-Format headers. The audio stays stored in your account, so the call can be repeated at any time.

Audio Transcriptions

Transcribing audio is a two-step asynchronous process: Request a transcription (via URL or direct file upload), and poll until the job completes.

1. Request Transcription

POST /v1/transcript

Submit an audio file or an audio URL to begin the asynchronous transcription job.

Request Example (JSON)

curl -X POST https://api.nexusai.com/v1/transcript \
  -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://...",
    "speaker_labels": true
  }'

Parameters

Supported Languages

Response Example

{
  "id": "abc123def"
}

Response Fields

2. Poll Status

GET /v1/transcript/{id}

Retrieve the status of your transcription job. You should poll this endpoint every few seconds until the status becomes completed.

curl -X GET https://api.nexusai.com/v1/transcript/abc123def \
  -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxx"

Completed Response (with speaker_labels)

{
  "id": "abc123def",
  "language_code": "en_us",
  "status": "completed",
  "audio_url": "https://...",
  "text": "This is a mocked transcription from NexusAI. Hello, how are you doing today?",
  "words": [
    { "text": "This", "start": 100, "end": 500, "confidence": 0.98 }
  ],
  "utterances": [
    {
      "confidence": 0.95,
      "start": 100,
      "end": 3500,
      "speaker": "A",
      "text": "This is a mocked transcription from NexusAI. Hello, how are you doing today?"
    }
  ],
  "confidence": 0.97,
  "audio_duration": 345,
  "punctuate": true,
  "format_text": true,
  "speaker_labels": true,
  "language_detection": false
}

Response Fields