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

# Sound Effects

> Generate AI sound effects — loops or one-shot samples

## Endpoint

```http theme={null}
POST /api/v1/music/soundfx
```

**Asynchronous.** Returns a `task_id`. Poll [Get Task](/api-reference/tasks/get) for results.

Generate custom sound effects described in plain text. Suitable for game audio, UI sounds, ambient effects, and music production samples. Supports Chinese and English descriptions.

## Request body

| Field            | Type    | Required | Description                                                                                                       |
| ---------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `sound_desc`     | string  | **Yes**  | Text description of the sound. Supports Chinese and English (e.g. `"heavy rain on a tin roof"` or `"雨打在屋顶上的声音"`). |
| `sound_type`     | string  | No       | `"loop"` for a looping sample or `"one-shot"` for a single-play sound. Default: `"one-shot"`.                     |
| `sound_bpm`      | integer | No       | Beats per minute (for looping effects).                                                                           |
| `sound_key`      | string  | No       | Musical key (e.g. `"C"`, `"Am"`).                                                                                 |
| `mv`             | string  | No       | Model version override.                                                                                           |
| `callback_url`   | string  | No       | Webhook URL for completion notification. See [Webhooks](/api-reference/webhooks).                                 |
| `retention_days` | integer | No       | Days to retain audio files. Default `7`.                                                                          |

## Response

```json theme={null}
{
  "code": 0,
  "message": "ok",
  "request_id": "req-1710000000000",
  "data": {
    "task_id": "64f3a1b2c8d9e0f1a2b3c4d5",
    "status": "queuing"
  }
}
```

## Examples

**English description:**

```bash theme={null}
curl -X POST https://api.example.com/api/v1/music/soundfx \
  -H "Authorization: Bearer sk-mm-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "sound_desc": "Thunderstorm with distant thunder and heavy rain",
    "sound_type": "loop",
    "sound_bpm": 120
  }'
```

**Chinese description:**

```bash theme={null}
curl -X POST https://api.example.com/api/v1/music/soundfx \
  -H "Authorization: Bearer sk-mm-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "sound_desc": "森林中的鸟鸣声，清晨的宁静氛围",
    "sound_type": "loop"
  }'
```