---
title: "Generate a sound effect"
method: POST
path: "/api/ai/sound-effects"
tags: ["Audio"]
---

# Generate a sound effect

`POST /api/ai/sound-effects`

## Request

- Base URL: `https://your-deployment.example.com`
- URL: `https://your-deployment.example.com/api/ai/sound-effects`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Generates a short sound effect from a text description. Omitting `durationSeconds` lets the provider pick the length (and bills at its default); `promptInfluence` trades prompt fidelity (1) against variation (0). Credits are reserved before generation and refunded if it fails. `organization_id` picks the payer: an organization you belong to, or null for your personal credits; omitted bills your home organization (or personal credits if you have none). The default `encoding: "binary"` returns the raw audio bytes; `encoding: "base64"` returns JSON. Audio over the ~4MB response ceiling is returned by signed URL (a `303` for binary, the `delivery: "url"` variant for base64). Generated audio is saved to the file browser unless the call sets `preview`; the outcome is reported in the JSON save fields and the `X-B4M-Audio-*` headers - fetch the saved copy from `fileUrl` / `X-B4M-Audio-File-Url`, since `GET /api/files/{id}` fails closed until moderation completes. Authenticate with an API key (`b4m_live_`) or a JWT.

## Request body

- GenerateSoundEffectRequest
  - `provider` 'elevenlabs'
  - `text` string, required
  - `durationSeconds` number
  - `promptInfluence` number
  - `format` string
  - `organization_id` string, nullable: The organization to bill: one you belong to, or null for your personal credits. Omitted bills your home organization, or your personal credits if you have none. An organization-billed API key always bills its own organization: omit this or set it to the key's organization; any other value, null included, is rejected with a 403 (`errorCode: billing_organization_mismatch`).
  - `encoding` 'binary' | 'base64'
  - `preview` boolean

## Response `200`

Sound effect generated. Binary bodies carry a Content-Type that follows the requested `format` (mp3 by default). The default `encoding: "binary"` returns the raw audio bytes; `encoding: "base64"` returns the JSON body. Audio over the ~4MB response ceiling cannot ride in the body: the binary encoding answers `303` instead, and the base64 encoding returns the `delivery: "url"` variant, whose `url` is a time-limited signed GET for the audio (`bytes` is its size).

- union
  - object
    - `contentType` string, required
    - `saved` boolean
    - `fabFileId` string
    - `fileName` string
    - `fileUrl` string
    - `saveSkippedReason` 'storage_limit' | 'file_too_large' | 'error'
    - `delivery` 'url', required
    - `url` string, required
    - `bytes` integer, required
  - object
    - `contentType` string, required
    - `saved` boolean
    - `fabFileId` string
    - `fileName` string
    - `fileUrl` string
    - `saveSkippedReason` 'storage_limit' | 'file_too_large' | 'error'
    - `delivery` 'inline'
    - `audio` string, required

## Other responses

- `303`: Binary encoding only: the audio exceeds the ~4MB response ceiling, so it was offloaded to storage and `Location` is a time-limited signed GET for it. HTTP clients that follow redirects receive the audio transparently (they drop the `Authorization` header on the cross-origin hop, as the signed URL requires); browser callers should use `encoding: "base64"`, since the storage origin sends no CORS headers. Carries the same `X-B4M-*` headers as the 200.
- `400`: The billing user or organization could not be resolved. An organization-billed API key bills an organization that no longer exists, or one its owner is no longer a member of; re-mint the key.
- `401`: Missing or invalid credentials.
- `403`: The API key lacks the `ai:generate` scope (`required_scopes` names it), or the billing organization names one you do not belong to (or is not a valid id), or an organization-billed API key names any organization but its own (`errorCode: billing_organization_mismatch`).
- `404`: A nonexistent `organization_id`, for an admin caller; for anyone else it is `403`.
- `405`: The path does not serve this HTTP method.
- `413`: The audio was generated (and billed) and exceeds the response ceiling, and offloading it to storage failed. Retry, or request shorter output.
- `422`: Request body failed validation (including a `format` whose codec the provider cannot produce), or the caller cannot afford the effect - the latter is tagged `errorCode: "insufficient_credits"` (the balance is short, or the org member credit cap is exhausted).
- `502`: The provider failed to generate the effect; reserved credits are refunded.
- `503`: No provider API key is configured for this deployment.

## Changes

- **2026-10-20** `d437aaac22ac`: 3 info
  - added the new optional request property `organization_id`
  - added the non-success response with the status `404`
  - added the optional property `errorCode` to the response with the `403` status

[Operation history](https://skmtc.dev/bike4mind/apis/bike4mind-api/changes/api/ai/sound-effects/post.md)

---

[API](https://skmtc.dev/bike4mind/apis/bike4mind-api.md) · [All operations](https://skmtc.dev/bike4mind/apis/bike4mind-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bike4mind/apis/bike4mind-api/revisions/d437aaac22ac?raw)