> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Listen to a voice of the catalog

> One short sentence read by a voice of a speech model, returned as an
MP3 data URL a browser plays as is (the listen buttons of AI
Governance). `voice` must match a voice of the catalog: only the
catalog's ids reach the provider. Platform administrators hear any
voice of the catalog; other callers, the voices their organization may
use (visible to it and in its allowed models) and that their role and
API key grant.

Rate limited per user (`config.voice.quotas.per_user.previews_per_hour`,
30 by default). The characters and their cost
(`pricing.per_1m_characters`) are counted in `analytics.llm.voice`.

Requires the `llm-gateway:models:audio-transcriptions` permission.




## OpenAPI

````yaml /api-reference/llm-gateway/swagger.yml post /v1/voice/preview
openapi: 3.0.3
info:
  version: 1.0.0
  title: LLM Gateway API
  description: |
    Public REST API for the Prisme.ai LLM Gateway - OpenAI-compatible
    chat completions, embeddings and image generation/editing, a standard
    rerank endpoint, a managed model catalogue with governance overrides
    per organization, and quota status for users and organizations.

    The gateway abstracts multi-provider LLM access (OpenAI, Azure OpenAI,
    Anthropic, Google Vertex, AWS Bedrock, OpenAI-compatible providers) behind
    an OpenAI-compatible request/response shape. It enforces per-tenant
    governance (allowed models, default models, quotas) and emits analytics
    events (`analytics.llm.completion`) usable for cost and carbon reporting.

    This spec documents only the public REST surface (endpoints exposed via
    Prisme.ai workspace webhooks). Internal helpers (private automations
    prefixed with `_`) and load-test mocks are not part of the public contract.
  contact:
    name: Prisme.ai
    url: https://prisme.ai
servers:
  - url: https://{host}/v2/workspaces/slug:llm-gateway/webhooks
    description: Prisme.ai workspace webhooks
    variables:
      host:
        default: api.studio.prisme.ai
        description: API host (override for self-hosted or sandbox)
security:
  - BearerAuth: []
  - OrgApiKeyAuth: []
tags:
  - name: Completions
    description: OpenAI-compatible chat completions (with optional SSE streaming).
  - name: Embeddings
    description: OpenAI-compatible text embeddings.
  - name: Rerank
    description: >-
      Rerank documents by relevance to a query (standard rerank contract,
      LLM-as-reranker backend).
  - name: Images
    description: OpenAI-compatible image generation and image editing.
  - name: Models
    description: Model catalogue (CRUD + bulk replace + governance-aware listing).
  - name: Audio
    description: OpenAI-compatible speech-to-text (audio transcriptions).
  - name: Quotas
    description: >-
      Effective LLM quota limits and current usage, per user and per
      organization.
  - name: Defaults
    description: >-
      Resolved default models for completions / embeddings / image generation /
      transcription / file parsing.
  - name: Test
    description: Smoke-test reachability of a model through the gateway.
paths:
  /v1/voice/preview:
    post:
      tags:
        - Audio
      summary: Listen to a voice of the catalog
      description: |
        One short sentence read by a voice of a speech model, returned as an
        MP3 data URL a browser plays as is (the listen buttons of AI
        Governance). `voice` must match a voice of the catalog: only the
        catalog's ids reach the provider. Platform administrators hear any
        voice of the catalog; other callers, the voices their organization may
        use (visible to it and in its allowed models) and that their role and
        API key grant.

        Rate limited per user (`config.voice.quotas.per_user.previews_per_hour`,
        30 by default). The characters and their cost
        (`pricing.per_1m_characters`) are counted in `analytics.llm.voice`.

        Requires the `llm-gateway:models:audio-transcriptions` permission.
      operationId: previewVoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - voice
              properties:
                voice:
                  type: string
                  maxLength: 300
                  description: The voice, `<model_id>/<voice_id>`.
                text:
                  type: string
                  maxLength: 200
                  description: >-
                    The sentence; the voice's `sample_text` by default, else a
                    greeting.
                rate:
                  type: string
                  maxLength: 8
                  description: Speech rate, a multiplier between 0.5 and 2.
      responses:
        '200':
          description: The sentence, read.
          content:
            application/json:
              schema:
                type: object
                properties:
                  audio:
                    type: string
                    description: '`data:audio/mpeg;base64,…`'
                  characters:
                    type: integer
                  cost:
                    type: number
        '403':
          description: >-
            `VOICE_NOT_ALLOWED`: the organization, or the role or API key scopes
            of the caller, do not allow this model; or the permission is
            missing.
        '404':
          description: '`VOICE_NOT_FOUND`: no such voice in the catalog.'
        '429':
          description: '`RATE_LIMITED`: too many previews in the hour.'
        '502':
          description: >-
            `PROVIDER_ERROR` or `PROVIDER_NOT_CONFIGURED`: the provider did not
            answer with audio.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        User-bound credential carrying an identity: either a session JWT
        or a user access token (`at:*`) generated from the user settings UI.
        Send as `Authorization: Bearer <token>`.
        Org API keys (`iak_*`) are **not** accepted here - they carry
        no user identity. Use the `x-prismeai-api-key` header instead
        (see `OrgApiKeyAuth`).
    OrgApiKeyAuth:
      type: apiKey
      in: header
      name: x-prismeai-api-key
      description: |
        Organization API key (`iak_{orgSlug}_{uuid}`). Unlike
        `Authorization: Bearer`, this credential is **not** tied to a user
        identity - it is bound to the org and its effective access is
        defined by the scopes / permission rules attached to it (it can
        be restricted to a single project, or kept broader).
        Send as `x-prismeai-api-key: iak_...`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.