Наговори
Справка API

Справка API

Нативная справка по REST API Наговори с маршрутами, параметрами, схемами и экспортом OpenAPI в нужном языке.

Сервер
https://api.nagovori.ru
Аутентификация
Все эндпоинты /v1/* требуют Bearer API key или JWT.
Экспорт OpenAPI
YAMLJSON
v1.0.0 · 13 схемы

Transcription

Транскрибация речи в текст

get/v1/transcriptionsТребуется авторизация

List transcriptions

Параметры

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

Ответы

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/transcriptionsТребуется авторизация

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.

Тело запроса

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.)"
    }
  }
}

Ответы

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}Требуется авторизация

Get a transcription by ID

Параметры

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

Ответы

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}/streamТребуется авторизация

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

Параметры

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

Ответы

200SSE event stream
text/event-stream
{
  "type": "string"
}
401Authentication required or invalid credentials
application/json
{
  "$ref": "#/components/schemas/Error"
}
get/v1/transcriptions/{id}/etaТребуется авторизация

Get estimated time for transcription

Параметры

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

Ответы

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

Синтез речи из текста

get/v1/tts/voicesТребуется авторизация

List available TTS voices

Ответы

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/ttsТребуется авторизация

Create a TTS job

Queues a text-to-speech synthesis job.

Тело запроса

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"
      ]
    }
  }
}

Ответы

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/streamТребуется авторизация

Stream TTS audio

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

Тело запроса

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

Ответы

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}Требуется авторизация

Get a TTS job by ID

Параметры

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

Ответы

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}/downloadТребуется авторизация

Get download URL for completed TTS audio

Параметры

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

Ответы

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

Загрузка файлов через presigned URL

post/v1/uploads/presignТребуется авторизация

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.

Тело запроса

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"
    }
  }
}

Ответы

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"
}