# Audio Transcription

The `POST /v1/audio/transcriptions` endpoint accepts multipart form-data audio uploads and returns transcribed text. Supports both simple and verbose response formats with word-level timestamps and segments.

## Endpoint

Method | Path | Format
--- | --- | ---
POST | /v1/audio/transcriptions | Multipart form-data request, JSON response

## Unit Test: Simple Transcription

Using the programmatic API with vitest, register a fixture and assert on the response.

transcription-simple.test.ts ts

    import { LLMock } from "@copilotkit/aimock";
    import { describe, it, expect, beforeAll, afterAll } from "vitest";

    let mock: LLMock;

    beforeAll(async () => {
      mock = new LLMock();
      await mock.start();
    });

    afterAll(async () => {
      await mock.stop();
    });

    it("returns simple transcription text", async () => {
      mock.onTranscription({
        transcription: { text: "Hello, how are you today?" },
      });

      const form = new FormData();
      form.append("file", new Blob(["fake-audio"]), "audio.mp3");
      form.append("model", "whisper-1");

      const res = await fetch(`${mock.url}/v1/audio/transcriptions`, {
        method: "POST",
        body: form,
      });

      const body = await res.json();
      expect(body.text).toBe("Hello, how are you today?");
    });

## Unit Test: Verbose Response with Segments

transcription-verbose.test.ts ts

    it("returns verbose transcription with words and segments", async () => {
      mock.onTranscription({
        transcription: {
          text: "Welcome to the meeting.",
          words: [
            { word: "Welcome", start: 0.0, end: 0.5 },
            { word: "to", start: 0.5, end: 0.7 },
            { word: "the", start: 0.7, end: 0.9 },
            { word: "meeting", start: 0.9, end: 1.4 },
          ],
          segments: [
            { id: 0, text: "Welcome to the meeting.", start: 0.0, end: 1.4 },
          ],
        },
      });

      const form = new FormData();
      form.append("file", new Blob(["fake-audio"]), "meeting.wav");
      form.append("model", "whisper-1");
      form.append("response_format", "verbose_json");
      form.append("timestamp_granularities[]", "word");
      form.append("timestamp_granularities[]", "segment");

      const res = await fetch(`${mock.url}/v1/audio/transcriptions`, {
        method: "POST",
        body: form,
      });

      const body = await res.json();
      expect(body.text).toBe("Welcome to the meeting.");
      expect(body.words).toHaveLength(4);
      expect(body.segments).toHaveLength(1);
    });

## JSON Fixture

fixtures/transcription.json json

    {
      "fixtures": [
        {
          "match": { "userMessage": "audio.mp3" },
          "response": {
            "transcription": {
              "text": "Hello, how are you today?"
            }
          }
        }
      ]
    }

## Response Format

Matches the OpenAI `/v1/audio/transcriptions` response format:

### Simple (default)

- `text` — the transcribed text

### Verbose (response_format: "verbose_json")

- `text` — the full transcribed text
- `task` — `"transcribe"`
- `language` — detected language code
- `duration` — audio duration in seconds
- `words[]` — word-level timestamps with `word`, `start`, `end`
- `segments[]` — segment-level data with `id`, `text`, `start`, `end`

Transcription requests use multipart form-data. The fixture `match.userMessage` maps to the uploaded filename. This allows matching different fixtures based on which audio file is submitted.

## Record & Replay

When no fixture matches an incoming request, aimock can proxy it to the real API and record the response as a fixture for future replays. Enable recording with the `--record` flag or via `RecordConfig` in the programmatic API. Recorded transcription fixtures preserve the full response including `text`, `language`, `duration`, `words`, and `segments`, so verbose-mode responses replay with complete word-level timestamps intact.

CLI sh

    npx -p @copilotkit/aimock llmock --record --provider-openai https://api.openai.com