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

> ## Agent Instructions
> For AgentScope Python, use https://docs.agentscope.io/stable/en/index for new projects. For existing projects, check the installed agentscope version and use matching versioned documentation.
> The /latest/ alias points to the newest documentation and may move ahead of /stable/ when a development version exists. Do not mix AgentScope 1.x and 2.x APIs.
> State the AgentScope version when providing installation commands or code examples. ReMe uses its own continuously updated /reme/latest/ documentation.

# ASR

> Transcribe audio into text with batch or realtime speech recognition models

An **ASR Model** converts speech audio into text. AgentScope exposes one
interface for complete-file transcription and realtime audio input. The
2.0.11 development version includes the following built-in implementation:

| Provider | Model Class | Mode | Built-in Models |
| - | - | - | - |
| OpenAI | `OpenAIASRModel` | Batch | `gpt-4o-mini-transcribe`, `gpt-4o-transcribe` |

## Create an ASR Model

Create an `OpenAIASRModel` with an `OpenAICredential`. The default model is
`gpt-4o-mini-transcribe`:

```python theme={null}
import os

from agentscope.asr import OpenAIASRModel
from agentscope.credential import OpenAICredential

asr = OpenAIASRModel(
    credential=OpenAICredential(
        api_key=os.environ["OPENAI_API_KEY"],
    ),
    model="gpt-4o-mini-transcribe",
    parameters=OpenAIASRModel.Parameters(
        language="en",
        prompt="AgentScope product meeting",
    ),
)
```

The OpenAI implementation supports two optional parameters:

| Parameter | Type | Description |
| - | - | - |
| `language` | `str \| None` | ISO-639-1 language code for the audio |
| `prompt` | `str \| None` | Text that guides transcription vocabulary and style |

## Transcribe Audio

`transcribe()` accepts the complete audio as bytes. Pass the original
filename so the provider can identify the in-memory audio format:

```python theme={null}
import asyncio
import os
from pathlib import Path

from agentscope.asr import OpenAIASRModel
from agentscope.credential import OpenAICredential


async def main() -> None:
    audio_path = Path("meeting.wav")
    asr = OpenAIASRModel(
        credential=OpenAICredential(
            api_key=os.environ["OPENAI_API_KEY"],
        ),
    )
    response = await asr.transcribe(
        audio=audio_path.read_bytes(),
        filename=audio_path.name,
    )
    if response.content is not None:
        print(response.content.text)


asyncio.run(main())
```

The bundled OpenAI model cards advertise FLAC, MP3/MPEG, MP4, OGG, WAV, and
WebM input. An empty `audio` value or `filename` raises `ValueError`.
Keyword arguments passed directly to `transcribe()` override values from the
model's `Parameters` object for that call.

## Read the Response

`transcribe()` returns an `ASRResponse`:

| Field | Type | Description |
| - | - | - |
| `content` | `TextBlock \| None` | Transcribed text, or no content when a realtime model has no new text |
| `id` | `str` | Unique response identifier |
| `created_at` | `str` | Response creation timestamp |
| `type` | `"asr"` | Response type discriminator |
| `metadata` | `dict \| None` | Optional provider-specific metadata |
| `is_last` | `bool` | Whether this is the final transcription response |

Batch models return a final response with `is_last=True`. Realtime models may
return intermediate responses with `is_last=False` from `push()`.

## Discover Available Models

ASR model cards describe supported audio types, output types, realtime
capability, and the provider parameter schema. Discover them from either the
credential or the model class:

<CodeGroup>
  ```python Credential theme={null}
  from agentscope.credential import OpenAICredential

  cards = OpenAICredential.list_asr_models()
  for card in cards:
      print(f"{card.name}: {card.input_types}")
  ```

  ```python Model class theme={null}
  from agentscope.asr import OpenAIASRModel

  cards = OpenAIASRModel.list_models()
  for card in cards:
      print(f"{card.name}: realtime={card.realtime}")
  ```
</CodeGroup>

## Implement a Custom ASR Model

Subclass `ASRModelBase` and implement `transcribe()` for a batch provider:

```python theme={null}
async def transcribe(
    self,
    audio: bytes | None = None,
    filename: str = "audio.wav",
    **kwargs: Any,
) -> ASRResponse:
    ...
```

For realtime input, set `realtime=True`, implement `connect()`, `push()`, and
`close()`, and use the model as an asynchronous context manager. Send audio
chunks through `push()` and call `transcribe()` without audio to finalize the
current transcript.

<Note>
  AgentScope 2.0.11dev currently ships only the batch OpenAI ASR
  implementation. The realtime lifecycle is available for custom and future
  providers.
</Note>


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