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

# SDK reference

> every public class, method, exception, and type in rumik-ai.

the import name is `rumikai`. everything below is importable from the top level, for
example `from rumikai import Rumik, AudioChunk, RateLimitError`.

## clients

```python theme={null}
Rumik(api_key=None, base_url=None, timeout=60, max_retries=2,
      default_headers=None, http_client=None)
AsyncRumik(api_key=None, base_url=None, timeout=60, max_retries=2,
           default_headers=None, http_client=None)
```

`Rumik` is synchronous, `AsyncRumik` is asynchronous with the same surface. both are
context managers (`with` / `async with`) and expose `.close()`. synthesis lives under
the `client.speech` namespace.

| argument          | default                     | description                            |
| ----------------- | --------------------------- | -------------------------------------- |
| `api_key`         | `RUMIK_API_KEY`             | your API key.                          |
| `base_url`        | `https://silk-api.rumik.ai` | API base URL (or `RUMIK_BASE_URL`).    |
| `timeout`         | `60`                        | request timeout in seconds.            |
| `max_retries`     | `2`                         | automatic retries on transient errors. |
| `default_headers` | `None`                      | headers sent with every request.       |
| `http_client`     | `None`                      | a custom HTTP client.                  |

## client.speech

```python theme={null}
client.speech.create(
    text, model="muga", description=None, speaker=None,
    temperature=None, top_p=None, top_k=None, repetition_penalty=None,
    max_new_tokens=None, timeout=None, extra_headers=None,
) -> Audio

client.speech.stream(
    text, model="muga", description=None, speaker=None,
    timeout=None, idle_timeout=30,
) -> SpeechStream

client.speech.session(
    model="muga", description=None, speaker=None,
    timeout=None, idle_timeout=30,
) -> SpeechSession
```

`stream` and `session` require the `ws` extra. see [synthesis](/sdk/synthesis) for
usage and parameters.

## types

### Audio

| member          | description                             |
| --------------- | --------------------------------------- |
| `save(path)`    | write the audio to a WAV file.          |
| `__bytes__`     | `bytes(audio)` returns the raw bytes.   |
| `__len__`       | `len(audio)` returns the byte count.    |
| `.is_wav`       | whether the bytes include a WAV header. |
| `.content_type` | the response content type.              |
| `.request_id`   | the server request id.                  |

### SpeechStream

a context manager. iterate it for raw PCM chunks.

| member          | description                       |
| --------------- | --------------------------------- |
| iterate         | yields raw PCM chunks (`bytes`).  |
| `.read()`       | all remaining PCM as one `bytes`. |
| `.save(path)`   | drain and write a WAV file.       |
| `.request_id`   | server request id.                |
| `.credits_used` | credits billed.                   |

### SpeechSession

a context manager. iterate it for events.

| member               | description                                              |
| -------------------- | -------------------------------------------------------- |
| `send(text)`         | synthesize a new utterance (barge-in if one is playing). |
| `interrupt()`        | stop the current utterance.                              |
| `close()`            | end the session.                                         |
| iterate              | yields session events.                                   |
| `iter_audio()`       | yields only PCM chunks.                                  |
| `.last_request_id`   | request id of the latest utterance.                      |
| `.last_credits_used` | credits billed for the latest utterance.                 |

### events

| event                | attributes                                             |
| -------------------- | ------------------------------------------------------ |
| `AudioChunk`         | `.data` (raw PCM bytes)                                |
| `UtteranceDone`      | `.request_id`, `.credits_used`                         |
| `UtteranceCancelled` | `.request_id`, `.reason` (`"interrupt"` \| `"cancel"`) |

### helpers

```python theme={null}
pcm_to_wav(pcm_bytes) -> bytes   # wrap raw PCM in a 24 kHz mono 16-bit WAV header
```

## exceptions

all inherit from `RumikError`. see [error handling](/sdk/errors) for the full tree.

| exception                  | status  | notes                                                                          |
| -------------------------- | ------- | ------------------------------------------------------------------------------ |
| `RumikError`               | base    | base class.                                                                    |
| `APIConnectionError`       | network | connection failure.                                                            |
| `APITimeoutError`          | network | request timed out.                                                             |
| `APIStatusError`           | 4xx/5xx | base for HTTP errors; has `.status_code`, `.code`, `.request_id`, `.response`. |
| `BadRequestError`          | 400     |                                                                                |
| `AuthenticationError`      | 401     |                                                                                |
| `PermissionDeniedError`    | 403     |                                                                                |
| `NotFoundError`            | 404     |                                                                                |
| `UnprocessableEntityError` | 422     |                                                                                |
| `RateLimitError`           | 429     | adds `.retry_after`.                                                           |
| `InternalServerError`      | 500     |                                                                                |
| `ServiceUnavailableError`  | 503     |                                                                                |
| `StreamError`              | stream  | streaming/session failure.                                                     |