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/create-generation-export.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

Create an export
Renders a file from a generation's separated tracks (speech, background, mix, both as a zip, or timeline-aligned original) in wav, mp3, m4a, mp4, or zip format.
POST https:/
- Key scope:
generations:write - Auth header:
Authorization: Bearer <apiKey> - Body: JSON
Request
Choose artifact and format, plus optional background_gain, leveling, inline, and file_name.
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 |
|---|---|---|---|
#artifact | string | Required: Yes | What to export: speech, background, mix, both (archive), or original (timeline-aligned original, requires inline: true).speechbackgroundmixbothoriginal |
#inline | boolean | Required: No | Set true for an in-page playback URL instead of a download (mp3 or mp4 only; required when artifact is original). |
#format | string | Required: Yes | Output container: wav, mp3, m4a, or mp4 for speech/background/mix (mp4 requires a video project); zip for both; mp3 or mp4 for original.wavmp3m4amp4zip |
#background_gain | number | Required: No | Optional background gain from 0 to 1 when artifact is mix (ignored for other artifacts). Defaults to the saved mix (GET .../mix). |
#leveling | boolean | Required: No | Optional quiet-speech leveling for speech, mix, or both (rejected for background and original). Defaults to the saved mix when artifact is mix and background_gain is omitted. |
#file_name | string | Required: No | Optional download filename without an extension (up to 200 characters). |
Request
import os
from diffio import DiffioClient
key = os.environ["DIFFIO_API_KEY"]
client = DiffioClient(api_key=key)
export = client.exports.create(
"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
"ce832a32-a1ce-516a-b8bd-75457bd8517f",
artifact="mix",
format="mp3",
file_name="interview mix",
)Billed calls are not offered here; send this one from your code.
Response
Returns the generation_export (queued, processing, or ready immediately when the same recipe was already rendered).
Success: 201Created.
Response fields
| Field | Type | Present | Description |
|---|---|---|---|
#object | string | Always | Resource type, always "generation_export".generation_export |
#id | string | Always | Deterministic export identifier (32 hex characters for the recipe, plus -inline when inline is true). |
#project_id | string | Always | Identifier of the parent project. |
#generation_id | string | Always | Identifier of the generation. |
#status | string | Always | Export render state: queued, processing, ready, or failed.queuedprocessingreadyfailed |
#artifact | string | null | Always | Exported track recipe (speech, background, mix, both, or original), or null. |
#format | string | null | Always | Output container format (wav, mp3, m4a, mp4, or zip), or null. |
#background_gain | number | null | Always | Background gain from 0 to 1 used for a mix export; 0 for other artifacts. |
Show all 14 fields (6 more)
| Field | Type | Present | Description |
|---|---|---|---|
#leveling | boolean | Always | True when speech leveling was applied to this export. |
#inline | boolean | Always | True when url is served for in-page playback rather than as a file download. |
#url | string | null | Always | Signed media URL valid for 6 hours once status is ready, or null while rendering or failed. |
#error | object | null | Always | Failure details when status is failed, or null otherwise. |
#error. | string | Always | Stable snake_case export failure code (export_failed). |
#error. | string | Always | Human-readable explanation of why export rendering failed. |
Response 201Created.
{
"object": "generation_export",
"id": "d51fd816be75bc302ecc3def3da4f22d",
"project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
"generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f",
"status": "queued",
"artifact": "mix",
"format": "mp3",
"background_gain": 0.3,
"leveling": false,
"inline": false,
"url": null,
"error": null
}Return codes
201Created.Export queued (or existingreadyexport returned with a freshurl).400Bad request.Malformed JSON, or 3 more causes
- Malformed JSON
- Missing
artifactorformat - Incompatible
artifact/format/inline/background_gain/levelingcombination - 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.Separated tracks still preparing, or 4 more causes
- Separated tracks still preparing
- Separated tracks unavailable
- Four exports already rendering on this generation
- Speech leveling unavailable
mp4requested on an audio project
not_readynot_availabletoo_many_exportsleveling_not_availablevideo_not_available502Bad gateway.Upstream export 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
- Exports are free and idempotent by recipe: requesting the same
artifact,format,background_gain,leveling, andinlinereturns the existing export instead of rendering twice, and re-renders afailedexport. - Poll Get an export (or
client.exports.wait(...)or theexport.ready/export.failedwebhooks) untilstatusisready, then fetchurlwithout an API key. - At most 4 exports per generation can render concurrently (
409too_many_exports).