> For the complete documentation index, see [llms.txt](https://diffio.ai/llms.txt). This page is also available as HTML at https://diffio.ai/docs/api-reference/save-generation-mix/.

# Save the mix

Saves the balance (`background_gain` from `0` to `1` and optional `leveling`) of a generation's separated speech and background tracks. Pass `revision` for compare-and-swap protection.

PUT `https://api.diffio.ai/v2/projects/{project_id}/generations/{generation_id}/mix`

- Key scope: `generations:write`
- Auth header: `Authorization: Bearer <apiKey>`
- Body: JSON

## Request

Send `background_gain` (`0` to `1`), optional `leveling`, and optional `revision` from the last read.

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | string | Yes | Unique identifier of the project. |
| `generation_id` | string | Yes | Unique identifier of the generation within the project. |

### Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `Diffio-End-User` | string | No | Optional end-user identifier (up to 128 characters). Scopes the request to that end user's projects; omit to act across the whole account. |

### Body fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `background_gain` | number | Yes | Amount of background sound to keep under speech, from `0` (speech only) to `1` (full background). |
| `leveling` | boolean | No | Optional boolean to boost quiet speech; when omitted, the previously saved `leveling` setting is kept. |
| `revision` | string | No | Optional opaque `revision` last read from `GET .../mix`. Refuses stale saves with `409` (`revision_conflict`) and `details.current_revision`; omit to overwrite unconditionally. |

## Example request

**Python**

```python
import os
from diffio import DiffioClient

key = os.environ["DIFFIO_API_KEY"]
client = DiffioClient(api_key=key)

rev = "4014a8c299444bbb866971bbb7b657ca:0"
mix = client.mix.save(
    "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
    "ce832a32-a1ce-516a-b8bd-75457bd8517f",
    background_gain=0.3,
    revision=rev,
)
```

**Node.js**

```javascript
import { DiffioClient } from "diffio"

const client = new DiffioClient({
  apiKey: process.env.DIFFIO_API_KEY,
})

const mix = await client.mix.save(
  "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
  "ce832a32-a1ce-516a-b8bd-75457bd8517f",
  {
    background_gain: 0.3,
    revision: "4014a8c299444bbb866971bbb7b657ca:0",
  },
)
```

**cURL**

```bash
curl -X PUT "https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/mix" \
  -H "Authorization: Bearer $DIFFIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "background_gain": 0.3,
    "revision": "4014a8c299444bbb866971bbb7b657ca:0"
  }'
```

**JSON: JSON body**

```json
{
  "background_gain": 0.3,
  "revision": "4014a8c299444bbb866971bbb7b657ca:0"
}
```

## Response

Returns the updated `generation_mix` with its new `revision`.

Success: `200`

### Response fields

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `object` | string | Always | Resource type, always `"generation_mix"`. |
| `project_id` | string | Always | Identifier of the parent project. |
| `generation_id` | string | Always | Identifier of the generation. |
| `background_gain` | number | Always | Background track level from `0` (speech only) to `1` (full background); defaults to `0`. |
| `leveling` | boolean | Always | Whether quiet-speech leveling is enabled; defaults to `false`. |
| `revision` | string | Always | Opaque revision token that changes on every save and stems re-preparation; pass back to `PUT .../mix` to prevent stale overwrites. |
| `stems_revision` | string \| null | Always | Revision identifier of the separated tracks this mix applies to (matching `files.stems_manifest`), or `null`. |

## Example response (200)

**Successful response**

```json
{
  "object": "generation_mix",
  "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
  "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f",
  "background_gain": 0.3,
  "leveling": false,
  "revision": "4014a8c299444bbb866971bbb7b657ca:1",
  "stems_revision": "4014a8c299444bbb866971bbb7b657ca"
}
```

## Return codes

- `200` Mix saved and returned with a new `revision`.
- `400`
  - Malformed JSON
  - Missing `background_gain`
  - `background_gain` outside `0..1`
  - Non-boolean `leveling`
  - A `revision` no mix answer gave
  - Oversized header
  Codes: [`invalid_json`](https://diffio.ai/docs/api-reference/errors/#invalid_json), [`missing_field`](https://diffio.ai/docs/api-reference/errors/#missing_field), [`invalid_field`](https://diffio.ai/docs/api-reference/errors/#invalid_field), [`invalid_header`](https://diffio.ai/docs/api-reference/errors/#invalid_header)
- `403` Key is inactive or lacks `generations:write`. [`permission_denied`](https://diffio.ai/docs/api-reference/errors/#permission_denied)
- `404` Project not found, or generation not found. [`project_not_found`](https://diffio.ai/docs/api-reference/errors/#project_not_found) [`generation_not_found`](https://diffio.ai/docs/api-reference/errors/#generation_not_found)
- `409`
  - Sent `revision` is stale with `details.current_revision` naming the latest: [`revision_conflict`](https://diffio.ai/docs/api-reference/errors/#revision_conflict)
  - Separated tracks are still preparing: [`not_ready`](https://diffio.ai/docs/api-reference/errors/#not_ready)
  - Separated tracks are unavailable: [`not_available`](https://diffio.ai/docs/api-reference/errors/#not_available)
- `502` Upstream stems service error. [`internal_error`](https://diffio.ai/docs/api-reference/errors/#internal_error)
- **`401` `405` Same on every endpoint**

  - `401` Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).
  - `405` HTTP method not supported on this path; check the Allow header (code method_not_allowed).

### Example error response

Errors are JSON: an `error` object with `code`, `message` and `request_id`. An unrecognized key returns `401`:

**Error response**

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "request_id": "dead773b60e148fd9e22d680a22fa701"
  }
}
```

## Notes

- Saving the mix updates the default `background_gain` and `leveling` used when [Create an export](https://diffio.ai/docs/api-reference/create-generation-export/) is called with `artifact: "mix"` and no explicit `background_gain`.
- Saving the mix does not rewrite `files.audio` or `files.audio_mixed` in [Get a playback grant](https://diffio.ai/docs/api-reference/get-generation-media/); render a file with [Create an export](https://diffio.ai/docs/api-reference/create-generation-export/) to download the custom balance.

## Related pages

- Previous: [Get the saved mix](https://diffio.ai/docs/api-reference/get-generation-mix/): Read the saved background gain, speech leveling setting, and revision for a generation's separated tracks.
- Next: [Create an export](https://diffio.ai/docs/api-reference/create-generation-export/): Render a downloadable or inline-playable file from a generation's separated speech and background tracks.

- [Full API guide](https://diffio.ai/docs/developers/full-api-guide/): Every topic, limit and concept in one index.
- [Webhooks guide](https://diffio.ai/docs/developers/webhooks/): Get notified when a generation finishes instead of polling.
