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

# Transcribe audio (beta)

> Upload an audio file and get its transcript back in the same response. Cloud transcription through the API is in beta. Limits, response shape, and availability may change, and there is no SLA. For long recordings or free, private transcription, use the OpenWhispr CLI with the desktop app running. Requires a Pro or Business plan and transcriptions:write on a personal key (owk_live_); workspace keys get 403. Files are capped at 4 MB per request, usage at 600 audio minutes per calendar month, and one transcription runs at a time per key. Each call counts as 5 requests against the key's per-minute and per-day rate limits.



## OpenAPI

````yaml /openapi.json post /transcribe
openapi: 3.1.0
info:
  title: OpenWhispr API
  version: 1.0.0
  description: >-
    Manage notes, folders, transcriptions, dictionary words, snippets, and usage
    programmatically, and transcribe audio files (beta).
servers:
  - url: https://api.openwhispr.com/api/v1
    description: Production
security:
  - bearerAuth: []
paths:
  /transcribe:
    post:
      tags:
        - Transcriptions
      summary: Transcribe audio (beta)
      description: >-
        Upload an audio file and get its transcript back in the same response.
        Cloud transcription through the API is in beta. Limits, response shape,
        and availability may change, and there is no SLA. For long recordings or
        free, private transcription, use the OpenWhispr CLI with the desktop app
        running. Requires a Pro or Business plan and transcriptions:write on a
        personal key (owk_live_); workspace keys get 403. Files are capped at 4
        MB per request, usage at 600 audio minutes per calendar month, and one
        transcription runs at a time per key. Each call counts as 5 requests
        against the key's per-minute and per-day rate limits.
      operationId: transcribeAudio
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: 'Audio file: wav, mp3, m4a/mp4, ogg, flac, or webm. 4 MB max.'
                language:
                  type: string
                  description: Language code of the audio (e.g. 'en').
                prompt:
                  type: string
                  description: Names and jargon to spell correctly, comma-separated.
      responses:
        '200':
          description: The transcript.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TranscribeResult'
        '400':
          description: validation_error — the file was not recognised as audio.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            plan_required — Pro or Business needed. Or forbidden — missing
            transcriptions:write, a workspace key, or an organization policy
            that blocks cloud transcription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: concurrency_limit — a transcription is already running on this key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: payload_too_large — the file exceeds 4 MB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            quota_exceeded — 600 audio minutes used this calendar month; the
            message includes the reset date. Or rate_limited — see Retry-After.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: service_unavailable — the beta is paused. Retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    TranscribeResult:
      type: object
      properties:
        id:
          type: string
        text:
          type: string
          description: The transcript.
        language:
          type: string
          description: Language of the transcript (e.g. 'en').
        duration_ms:
          type: integer
          description: >-
            Audio length in milliseconds, estimated from file size when the
            engine does not report it. Counts against the monthly quota.
        words:
          type: integer
          description: Word count of the transcript.
        provider:
          type: string
          description: >-
            Which transcription provider produced the result. Informational; may
            change during the beta.
        model:
          type: string
          description: >-
            Which model produced the result. Informational; may change during
            the beta.
        beta:
          type: boolean
          const: true
          description: Always true while cloud transcription through the API is in beta.
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
          required:
            - code
            - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key starting with owk_live_ (personal) or ow_wks_live_ (workspace —
        see space_id on the Notes/Folders endpoints below)

````