Skip to content

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://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

FieldTypeRequiredDescription
#project_idstringRequired: YesUnique identifier of the project.
#generation_idstringRequired: YesUnique identifier of the generation within the project.

Headers

FieldTypeRequiredDescription
#Diffio-End-UserstringRequired: NoOptional 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

FieldTypeRequiredDescription
#background_gainnumberRequired: YesAmount of background sound to keep under speech, from 0 (speech only) to 1 (full background).
#levelingbooleanRequired: NoOptional boolean to boost quiet speech; when omitted, the previously saved leveling setting is kept.
#revisionstringRequired: NoOptional 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

FieldTypePresentDescription
#objectstringAlwaysResource type, always "generation_mix".generation_mix
#project_idstringAlwaysIdentifier of the parent project.
#generation_idstringAlwaysIdentifier of the generation.
#background_gainnumberAlwaysBackground track level from 0 (speech only) to 1 (full background); defaults to 0.
#levelingbooleanAlwaysWhether quiet-speech leveling is enabled; defaults to false.
#revisionstringAlwaysOpaque revision token that changes on every save and stems re-preparation; pass back to PUT .../mix to prevent stale overwrites.
#stems_revisionstring | nullAlwaysRevision identifier of the separated tracks this mix applies to (matching files.stems_manifest), or null.

Response 200OK.

Successful response
{
  "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 new revision.
  • 400Bad request.
    Malformed JSON, or 5 more causes
    • Malformed JSON
    • Missing background_gain
    • background_gain outside 0..1
    • Non-boolean leveling
    • A revision no mix answer gave
    • Oversized header
    invalid_jsonmissing_fieldinvalid_fieldinvalid_header
  • 403Forbidden: the key lacks permission.Key is inactive or lacks generations:write. permission_denied
  • 404Not found.Project not found, or generation not found. project_not_foundgeneration_not_found
  • 409Conflict: see error.code for which one.
    Sent revision is stale with details.current_revision naming the latest, or 2 more causes
    • Sent revision is stale with details.current_revision naming the latest
    • Separated tracks are still preparing
    • Separated tracks are unavailable
    revision_conflictnot_readynot_available
  • 502Bad gateway.Upstream stems service error. internal_error
  • 401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint
    • 401Unauthorized: 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 response
{
  "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 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; render a file with Create an export to download the custom balance.

Report an issue with this page