For AI agents: every API docs page in one plain-text file is at /docs/llms-full.txt, and the documentation index is at /llms.txt. This page is available as Markdown at https://diffio.ai/docs/api-reference/save-generation-mix.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

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:/
- 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
Headers
| Field | Type | Required | Description |
|---|---|---|---|
#Diffio-End-User | string | Required: 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 | Required: Yes | Amount of background sound to keep under speech, from 0 (speech only) to 1 (full background). |
#leveling | boolean | Required: No | Optional boolean to boost quiet speech; when omitted, the previously saved leveling setting is kept. |
#revision | string | Required: No | Optional opaque revision last read from GET .../mix. Refuses stale saves with 409 (revision_conflict) and details.current_revision; omit to overwrite unconditionally. |
Request
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,
)Response
Returns the updated generation_mix with its new revision.
Success: 200OK.
Response fields
| Field | Type | Present | Description |
|---|---|---|---|
#object | string | Always | Resource type, always "generation_mix".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. |
Response 200OK.
{
"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
200OK.Mix saved and returned with a newrevision.400Bad request.Malformed JSON, or 5 more causes
- Malformed JSON
- Missing
background_gain background_gainoutside0..1- Non-boolean
leveling - A
revisionno mix answer gave - Oversized header
invalid_jsonmissing_fieldinvalid_fieldinvalid_header403Forbidden: the key lacks permission.Key is inactive or lacksgenerations:write.permission_denied404Not found.Project not found, or generation not found.project_not_foundgeneration_not_found409Conflict: see error.code for which one.Sent
revisionis stale withdetails.current_revisionnaming the latest, or 2 more causes- Sent
revisionis stale withdetails.current_revisionnaming the latest - Separated tracks are still preparing
- Separated tracks are unavailable
revision_conflictnot_readynot_available- Sent
502Bad gateway.Upstream stems service error.internal_error401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint401Unauthorized: the API key is missing or invalid. Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).405Client error. 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 401Unauthorized: the API key is missing or invalid.:
{
"error": {
"code": "invalid_api_key",
"message": "Invalid API key.",
"request_id": "dead773b60e148fd9e22d680a22fa701"
}
}Notes
- Saving the mix updates the default
background_gainandlevelingused when Create an export is called withartifact: "mix"and no explicitbackground_gain. - Saving the mix does not rewrite
files.audioorfiles.audio_mixedin Get a playback grant; render a file with Create an export to download the custom balance.