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/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://api.diffio.ai/v2/projects/{project_id}/generations/{generation_id}/exports

  • 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

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
#artifactstringRequired: YesWhat to export: speech, background, mix, both (archive), or original (timeline-aligned original, requires inline: true).speechbackgroundmixbothoriginal
#inlinebooleanRequired: NoSet true for an in-page playback URL instead of a download (mp3 or mp4 only; required when artifact is original).
#formatstringRequired: YesOutput 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_gainnumberRequired: NoOptional background gain from 0 to 1 when artifact is mix (ignored for other artifacts). Defaults to the saved mix (GET .../mix).
#levelingbooleanRequired: NoOptional 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_namestringRequired: NoOptional 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

FieldTypePresentDescription
#objectstringAlwaysResource type, always "generation_export".generation_export
#idstringAlwaysDeterministic export identifier (32 hex characters for the recipe, plus -inline when inline is true).
#project_idstringAlwaysIdentifier of the parent project.
#generation_idstringAlwaysIdentifier of the generation.
#statusstringAlwaysExport render state: queued, processing, ready, or failed.queuedprocessingreadyfailed
#artifactstring | nullAlwaysExported track recipe (speech, background, mix, both, or original), or null.
#formatstring | nullAlwaysOutput container format (wav, mp3, m4a, mp4, or zip), or null.
#background_gainnumber | nullAlwaysBackground gain from 0 to 1 used for a mix export; 0 for other artifacts.
Show all 14 fields (6 more)
FieldTypePresentDescription
#levelingbooleanAlwaysTrue when speech leveling was applied to this export.
#inlinebooleanAlwaysTrue when url is served for in-page playback rather than as a file download.
#urlstring | nullAlwaysSigned media URL valid for 6 hours once status is ready, or null while rendering or failed.
#errorobject | nullAlwaysFailure details when status is failed, or null otherwise.
#error.codestringAlwaysStable snake_case export failure code (export_failed).
#error.messagestringAlwaysHuman-readable explanation of why export rendering failed.

Response 201Created.

Successful response
{
  "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 existing ready export returned with a fresh url).
  • 400Bad request.
    Malformed JSON, or 3 more causes
    • Malformed JSON
    • Missing artifact or format
    • Incompatible artifact/format/inline/background_gain/leveling combination
    • 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.
    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
    • mp4 requested on an audio project
    not_readynot_availabletoo_many_exportsleveling_not_availablevideo_not_available
  • 502Bad gateway.Upstream export 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

  • Exports are free and idempotent by recipe: requesting the same artifact, format, background_gain, leveling, and inline returns the existing export instead of rendering twice, and re-renders a failed export.
  • Poll Get an export (or client.exports.wait(...) or the export.ready / export.failed webhooks) until status is ready, then fetch url without an API key.
  • At most 4 exports per generation can render concurrently (409 too_many_exports).

Report an issue with this page