# Audio generation

Buy music or a sound effect from a description. The response body is the audio file.

## Quickstart

```bash
curl https://router.inference.ai.exchange/v1/audio/generations \
  -H "Authorization: Bearer sk-liquid-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "prompt": "a calm piano piece with soft rain",
    "mode": "music",
    "seconds": 30,
    "response_format": "mp3"
  }' --output clip.mp3
```

## Find a model

- `GET /v1/models?kind=sound` lists the models as cards, with `kind` `audio_generation` and `modality` `sound`.
- `GET /v1/exchange/models?kind=sound` needs no key. The `audio` entry of `output_modalities` lists the `modes`, the `formats` and the longest clip (`max_duration_seconds`) of each offer.

See [Modalities](https://liquidinference.ai/docs/modalities.md#read-a-model-card) for the card and the other filters.

## Modes

`mode` is `music` (the default) or `sound_effect`. An offer lists the modes that it makes. A request for a mode that no offer lists gets no offer, and the error names `mode`. An offer can price each mode apart.

## Length

You must state `seconds`, from 1 to 300, because it is the whole of the charge. An offer that makes shorter clips than you ask for does not get the request, and the error names `seconds`.

## Billing

The price is for each second of audio that you ask for, so the cap is exactly the charge. A provider that sends a clip shorter than 90 percent of the seconds that you asked for, or that meters more seconds than you asked for, fails the job and is not paid.

## Response

The body is the audio.

- The `exchange` block comes back as JSON in the `x-liquid-exchange` response header, next to `x-liquid-cap-usd` and `x-liquid-job-id`.
- There is no streaming form. The exchange sends each clip complete.

## Request parameters

| Field             | Type   | Required | Description                                                                             |
| ----------------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `model`           | string | Yes      | The model to buy, or a preset of the sound kind.                                        |
| `prompt`          | string | Yes      | The description of the sound. At most 2,000 characters.                                 |
| `seconds`         | number | Yes      | The length of the clip, from 1 to 300.                                                  |
| `mode`            | string | No       | `music` or `sound_effect`. The default is `music`.                                      |
| `response_format` | string | No       | `mp3`, `opus`, `aac`, `flac`, `wav` or `pcm`. An offer that lists formats must list it. |
| `exchange`        | object | No       | Purchasing rules, such as `cap_usd`. See [Purchasing rules](https://liquidinference.ai/docs/rules.md).                |

The endpoint refuses a field that it does not read. It does not drop one, because you would pay for a clip made without it.

## Errors

| Error                       | Cause                                                                                   | Fix                                                                   |
| --------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `400 invalid_request`       | `seconds` is outside 1 to 300, or `mode` or `response_format` is not one of the values. | Send a listed value.                                                  |
| `400 unsupported_parameter` | No offer makes your `mode`, length or format. `param` names it.                         | Read the `audio` output on the model card, or `eligibility.excluded`. |
| `400 unsupported_model`     | The model is not an audio generation model.                                             | Read `/v1/models` for `kind: audio_generation`.                       |
