Skip to content

# `mistral_common.protocol.transcription.request`

## `TranscriptionRequest(**data)`

Bases: `BaseCompletionRequest`

A class representing a request for audio transcription.

This class handles the conversion of audio data into a format suitable for transcription using the OpenAI API. It includes methods to convert the request to and from the OpenAI format.

Attributes:

Name | Type | Description
--- | --- | ---
`id` | `str | None` | An optional identifier for the transcription request.
`model` | `str | None` | The model to be used for transcription.
`audio` | `str | bytes` | The audio data to be transcribed.
`language` | `LanguageAlpha2 | None` | The language of the input audio in ISO-639-1 format (optional).
`strict_audio_validation` | `bool` | A flag indicating whether to perform strict validation of the audio data.

Source code in `pydantic/main.py`

    253
    254
    255
    256
    257
    258
    259
    260
    261
    262
    263
    264
    265
    266
    267
    268
    269
    270

    def __init__(self, /, **data: Any) -> None:
        """Create a new model by parsing and validating input data from keyword arguments.

        Raises [`ValidationError`][pydantic_core.ValidationError] if the input data cannot be
        validated to form a valid model.

        `self` is explicitly positional-only to allow `self` as a field name.
        """
        # `__tracebackhide__` tells pytest and some other tools to omit this function from tracebacks
        __tracebackhide__ = True
        validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
        if self is not validated_self:
            warnings.warn(
                'A custom validator is returning a value other than `self`.\n'
                "Returning anything other than `self` from a top level model validator isn't supported when validating via `__init__`.\n"
                'See the `model_validator` docs (https://docs.pydantic.dev/latest/concepts/validators/#model-validators) for more details.',
                stacklevel=2,
            )

### `from_openai(openai_request, strict=False)` `classmethod`

Create a TranscriptionRequest instance from an OpenAI request dictionary.

This method converts an OpenAI request dictionary into a TranscriptionRequest instance, handling the conversion of audio data and other parameters.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`openai_request` | `dict[str, Any]` | The OpenAI request dictionary. | required
`strict` | `bool` | A flag indicating whether to perform strict validation of the audio data. | `False`

Returns:

Type | Description
--- | ---
`TranscriptionRequest` | An instance of TranscriptionRequest.

Source code in `src/mistral_common/protocol/transcription/request.py`

    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165

    @classmethod
    def from_openai(cls, openai_request: dict[str, Any], strict: bool = False) -> "TranscriptionRequest":
        r"""Create a TranscriptionRequest instance from an OpenAI request dictionary.

        This method converts an OpenAI request dictionary into a TranscriptionRequest instance,
        handling the conversion of audio data and other parameters.

        Args:
            openai_request: The OpenAI request dictionary.
            strict: A flag indicating whether to perform strict validation of the audio data.

        Returns:
           An instance of TranscriptionRequest.
        """
        file = openai_request.get("file")
        seed = openai_request.get("seed")
        converted_dict = {
            k: v
            for k, v in openai_request.items()
            if (k in cls.model_fields and not (v is None and k in ["temperature", "top_p"]))
        }

        assert file is not None, file
        if isinstance(file, io.BytesIO):
            audio_bytes = file.getvalue()
        else:
            # for example if file is UploadFile, this should work
            audio_bytes = file.file.read()

        audio = Audio.from_bytes(audio_bytes, strict=strict)
        audio_str = audio.to_base64(audio.format)

        converted_dict["audio"] = audio_str
        converted_dict["random_seed"] = seed
        return cls(**converted_dict)

### `to_openai(exclude=(), **kwargs)`

Convert the transcription request into the OpenAI format.

This method prepares the transcription request data for compatibility with the OpenAI API. It handles the conversion of audio data and additional parameters into the required format.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`exclude` | `tuple` | Fields to exclude from the conversion. | `()`
`kwargs` | `Any` | Additional parameters to be added to the request. | `{}`

Returns:

Type | Description
--- | ---
`dict[str, list[dict[str, Any]]]` | The request in the OpenAI format.

Raises:

Type | Description
--- | ---
`ImportError` | If the required soundfile library is not installed.

Source code in `src/mistral_common/protocol/transcription/request.py`

     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129

    def to_openai(self, exclude: tuple = (), **kwargs: Any) -> dict[str, list[dict[str, Any]]]:
        r"""Convert the transcription request into the OpenAI format.

        This method prepares the transcription request data for compatibility with the OpenAI API.
        It handles the conversion of audio data and additional parameters into the required format.

        Args:
            exclude: Fields to exclude from the conversion.
            kwargs: Additional parameters to be added to the request.

        Returns:
            The request in the OpenAI format.

        Raises:
            ImportError: If the required soundfile library is not installed.
        """
        openai_request: dict[str, Any] = self.model_dump(exclude={"audio"})

        assert_soundfile_installed()

        if isinstance(self.audio, bytes):
            buffer = io.BytesIO(self.audio)
            fmt = _detect_audio_format(self.audio)
            buffer.seek(0)
        else:
            assert isinstance(self.audio, str)
            audio = Audio.from_base64(self.audio)
            assert audio.format is not None
            fmt = audio.format.lower()

            buffer = io.BytesIO()
            sf.write(buffer, audio.audio_array, audio.sampling_rate, format=audio.format)
            # reset cursor to beginning
            buffer.seek(0)

        # OpenAI's client uses the filename extension from .name to set the Content-Type.
        buffer.name = f"audio.{fmt}"

        openai_request["file"] = buffer
        openai_request["seed"] = openai_request.pop("random_seed")
        openai_request.update(kwargs)

        # remove mistral-specific
        # TODO: revisit which fields to expose in the OpenAI format
        default_exclude = ("id", "max_tokens", "strict_audio_validation", "streaming")
        default_exclude += exclude
        for k in default_exclude:
            openai_request.pop(k, None)

        return openai_request