> 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/create-generation-export/.

# 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

| 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 |
| --- | --- | --- | --- |
| `artifact` | string | Yes | What to export: `speech`, `background`, `mix`, `both` (archive), or `original` (timeline-aligned original, requires `inline: true`). |
| `inline` | boolean | No | Set `true` for an in-page playback URL instead of a download (`mp3` or `mp4` only; required when `artifact` is `original`). |
| `format` | string | 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`. |
| `background_gain` | number | 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 | 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 | No | Optional download filename without an extension (up to 200 characters). |

## Example request

**Python**

```python
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",
)
```

**Node.js**

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

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

const rendered =
  await client.exports.create(
    "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
    "ce832a32-a1ce-516a-b8bd-75457bd8517f",
    {
      artifact: "mix",
      format: "mp3",
      file_name: "interview mix",
    },
  )
```

**cURL**

```bash
curl -X POST "https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/exports" \
  -H "Authorization: Bearer $DIFFIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "artifact": "mix",
    "format": "mp3",
    "file_name": "interview mix"
  }'
```

**JSON: JSON body**

```json
{
  "artifact": "mix",
  "format": "mp3",
  "file_name": "interview mix"
}
```

## Response

Returns the `generation_export` (`queued`, `processing`, or `ready` immediately when the same recipe was already rendered).

Success: `201`

### Response fields

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `object` | string | Always | Resource type, always `"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`. |
| `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. |
| `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.code` | string | Always | Stable `snake_case` export failure code (`export_failed`). |
| `error.message` | string | Always | Human-readable explanation of why export rendering failed. |

## Example response (201)

**Successful response**

```json
{
  "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

- `201` Export queued (or existing `ready` export returned with a fresh `url`).
- `400`
  - Malformed JSON: [`invalid_json`](https://diffio.ai/docs/api-reference/errors/#invalid_json)
  - Missing `artifact` or `format`: [`missing_field`](https://diffio.ai/docs/api-reference/errors/#missing_field)
  - Incompatible `artifact`/`format`/`inline`/`background_gain`/`leveling` combination: [`invalid_field`](https://diffio.ai/docs/api-reference/errors/#invalid_field)
  - Oversized header: [`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`
  - Separated tracks still preparing: [`not_ready`](https://diffio.ai/docs/api-reference/errors/#not_ready)
  - Separated tracks unavailable: [`not_available`](https://diffio.ai/docs/api-reference/errors/#not_available)
  - Four exports already rendering on this generation: [`too_many_exports`](https://diffio.ai/docs/api-reference/errors/#too_many_exports)
  - Speech leveling unavailable: [`leveling_not_available`](https://diffio.ai/docs/api-reference/errors/#leveling_not_available)
  - `mp4` requested on an audio project: [`video_not_available`](https://diffio.ai/docs/api-reference/errors/#video_not_available)
- `502` Upstream export 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

- 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](https://diffio.ai/docs/api-reference/get-generation-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`).

## Related pages

- Previous: [Save the mix](https://diffio.ai/docs/api-reference/save-generation-mix/): Save the background track gain and speech leveling setting for a generation's separated tracks.
- Next: [Get an export](https://diffio.ai/docs/api-reference/get-generation-export/): Poll an export's render status and mint a fresh 6-hour download or playback URL once ready.

- [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.
