Nagovori
API Reference

API Reference

Native Nagovori REST API reference with routes, parameters, schemas, and locale-aware OpenAPI export.

Server
https://api.nagovori.ru
Authentication
All /v1/* endpoints require a Bearer API key or JWT.
Export OpenAPI
YAMLJSON
v1.0.0 · 13 schemas

Transcription

Speech-to-text transcription

get/v1/transcriptionsAuthentication required

List transcriptions

Parameters

limitquery
{
  "type": "integer",
  "default": 20
}
offsetquery
{
  "type": "integer",
  "default": 0
}

Responses

200List of transcriptions
application/json
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Transcription"
      }
    },
    "count": {
      "type": "integer"
    }
  }
}
401Authentication required or invalid credentials
application/json
{
  "$ref": "#/components/schemas/Error"
}
post/v1/transcriptionsAuthentication required

Create a transcription job

Starts a new transcription job for an uploaded audio file. The file must have been uploaded via the presign endpoint first.

Request body

application/json
{
  "type": "object",
  "required": [
    "object_key"
  ],
  "properties": {
    "object_key": {
      "type": "string",
      "description": "Object key from the presign response"
    },
    "filename": {
      "type": "string"
    },
    "content_type": {
      "type": "string",
      "example": "audio/mpeg"
    },
    "size_bytes": {
      "type": "integer",
      "format": "int64"
    },
    "duration_seconds": {
      "type": "integer",
      "description": "Audio duration in seconds (for billing)"
    },
    "language": {
      "type": "string",
      "description": "Language code or \"auto\" for detection",
      "example": "auto"
    },
    "model": {
      "type": "string",
      "description": "Gemma ASR model ID",
      "enum": [
        "gemma4-e2b-asr",
        "gemma4-e2b-asr-stream"
      ]
    },
    "chunk_prompt_preset": {
      "type": "string",
      "description": "Chunk-level ASR preset applied to each part before transcription",
      "enum": [
        "default",
        "verbatim",
        "remove_fillers",
        "concise"
      ],
      "default": "default"
    },
    "pricing_mode": {
      "type": "string",
      "description": "Pricing mode (free_test or package)"
    },
    "source_channel": {
      "type": "string",
      "description": "Source channel (web, api, telegram, etc.)"
    }
  }
}

Responses

201Transcription job created
application/json
{
  "$ref": "#/components/schemas/CreateTranscriptionResponse"
}
400Bad request (file too long, invalid params)
application/json
{
  "$ref": "#/components/schemas/Error"
}
401Authentication required or invalid credentials
application/json
{
  "$ref": "#/components/schemas/Error"
}
402No transcription credits remaining
application/json
{
  "$ref": "#/components/schemas/Error"
}
429Rate limited (concurrent job or daily limit)
application/json
{
  "$ref": "#/components/schemas/Error"
}
get/v1/transcriptions/{id}Authentication required

Get a transcription by ID

Parameters

idpathrequired
{
  "type": "string",
  "format": "uuid"
}

Responses

200Transcription details
application/json
{
  "$ref": "#/components/schemas/Transcription"
}
401Authentication required or invalid credentials
application/json
{
  "$ref": "#/components/schemas/Error"
}
404Transcription not found
application/json
{
  "$ref": "#/components/schemas/Error"
}
get/v1/transcriptions/{id}/streamAuthentication required

Stream transcription progress (SSE)

Server-Sent Events stream for real-time transcription progress.

Events:

  • update — full transcription state snapshot
  • token — individual text token (incremental)
  • done — transcription completed or failed
  • error — error occurred

Parameters

idpathrequired
{
  "type": "string",
  "format": "uuid"
}

Responses

200SSE event stream
text/event-stream
{
  "type": "string"
}
401Authentication required or invalid credentials
application/json
{
  "$ref": "#/components/schemas/Error"
}
get/v1/transcriptions/{id}/etaAuthentication required

Get estimated time for transcription

Parameters

idpathrequired
{
  "type": "string",
  "format": "uuid"
}

Responses

200ETA estimate
application/json
{
  "type": "object",
  "properties": {
    "queue_position": {
      "type": "integer"
    },
    "estimated_wait_seconds": {
      "type": "integer"
    },
    "average_duration_seconds": {
      "type": "integer"
    }
  }
}
401Authentication required or invalid credentials
application/json
{
  "$ref": "#/components/schemas/Error"
}

TTS

Text-to-speech synthesis

get/v1/tts/voicesAuthentication required

List available TTS voices

Responses

200Available voices
application/json
{
  "type": "object",
  "properties": {
    "voices": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/TTSVoice"
      }
    },
    "default": {
      "type": "string",
      "example": "alloy"
    }
  }
}
401Authentication required or invalid credentials
application/json
{
  "$ref": "#/components/schemas/Error"
}
post/v1/ttsAuthentication required

Create a TTS job

Queues a text-to-speech synthesis job.

Request body

application/json
{
  "type": "object",
  "required": [
    "text"
  ],
  "properties": {
    "text": {
      "type": "string",
      "description": "Text to synthesize (max 5000 characters)",
      "maxLength": 5000
    },
    "voice": {
      "type": "string",
      "description": "Voice ID",
      "example": "alloy",
      "enum": [
        "alloy",
        "ash",
        "nova",
        "onyx",
        "echo",
        "shimmer",
        "fable"
      ]
    }
  }
}

Responses

201TTS job created
application/json
{
  "type": "object",
  "properties": {
    "job": {
      "$ref": "#/components/schemas/TTSJob"
    }
  }
}
400Invalid request (text too long, invalid voice)
application/json
{
  "$ref": "#/components/schemas/Error"
}
401Authentication required or invalid credentials
application/json
{
  "$ref": "#/components/schemas/Error"
}
post/v1/tts/streamAuthentication required

Stream TTS audio

Streams synthesized audio in real-time as chunked MP3. Audio begins playing after the first sentence is processed.

Request body

application/json
{
  "type": "object",
  "required": [
    "text"
  ],
  "properties": {
    "text": {
      "type": "string",
      "maxLength": 5000
    },
    "voice": {
      "type": "string",
      "enum": [
        "alloy",
        "ash",
        "nova",
        "onyx",
        "echo",
        "shimmer",
        "fable"
      ]
    }
  }
}

Responses

200Streaming MP3 audio
audio/mpeg
{
  "type": "string",
  "format": "binary"
}
400Invalid request
application/json
{
  "$ref": "#/components/schemas/Error"
}
401Authentication required or invalid credentials
application/json
{
  "$ref": "#/components/schemas/Error"
}
get/v1/tts/{id}Authentication required

Get a TTS job by ID

Parameters

idpathrequired
{
  "type": "string",
  "format": "uuid"
}

Responses

200TTS job details
application/json
{
  "type": "object",
  "properties": {
    "job": {
      "$ref": "#/components/schemas/TTSJob"
    }
  }
}
401Authentication required or invalid credentials
application/json
{
  "$ref": "#/components/schemas/Error"
}
404Job not found
application/json
{
  "$ref": "#/components/schemas/Error"
}
get/v1/tts/{id}/downloadAuthentication required

Get download URL for completed TTS audio

Parameters

idpathrequired
{
  "type": "string",
  "format": "uuid"
}

Responses

200Presigned download URL
application/json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    }
  }
}
401Authentication required or invalid credentials
application/json
{
  "$ref": "#/components/schemas/Error"
}
404Job not found
application/json
{
  "$ref": "#/components/schemas/Error"
}

Upload

File upload via presigned URLs

post/v1/uploads/presignAuthentication required

Get a presigned URL for file upload

Returns a presigned URL for uploading an audio file to object storage. Upload the file with a PUT request to the returned URL.

Request body

application/json
{
  "type": "object",
  "required": [
    "filename"
  ],
  "properties": {
    "filename": {
      "type": "string",
      "description": "Original filename",
      "example": "meeting.mp3"
    },
    "content_type": {
      "type": "string",
      "description": "MIME type of the file",
      "example": "audio/mpeg"
    },
    "size_bytes": {
      "type": "integer",
      "format": "int64",
      "description": "File size in bytes",
      "example": 5242880
    },
    "content_sha256": {
      "type": "string",
      "description": "Optional SHA-256 hash to deduplicate uploads"
    }
  }
}

Responses

200Presigned upload details
application/json
{
  "type": "object",
  "properties": {
    "bucket": {
      "type": "string"
    },
    "object_key": {
      "type": "string",
      "example": "uploads/user123/abc123.mp3"
    },
    "upload_url": {
      "type": "string",
      "format": "uri",
      "description": "PUT this URL with the file body"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "already_uploaded": {
      "type": "boolean",
      "description": "True if file was already uploaded (dedup by SHA-256)"
    }
  }
}
401Authentication required or invalid credentials
application/json
{
  "$ref": "#/components/schemas/Error"
}