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

# Create a generation

Starts a speech restoration run on a project's recording using the specified `model`. Accepted while the upload is still in progress: the generation waits in `queued` and starts automatically once the project is `ready`.

POST `https://api.diffio.ai/v2/projects/{project_id}/generations`

- Key scope: `generations:write`
- Auth header: `Authorization: Bearer <apiKey>`
- Body: JSON

1. POST [/projects](https://diffio.ai/docs/api-reference/create-project/) `id`
2. POST `/projects/{project_id}/generations` `id`
3. GET [/projects/{project_id}/generations/{generation_id}](https://diffio.ai/docs/api-reference/get-generation/) `status`
4. GET [/projects/{project_id}/generations/{generation_id}/media](https://diffio.ai/docs/api-reference/get-generation-media/) `files`

**Replays and conflicts, case by case**

- First request `201` new generation
- Same `Idempotency-Key`, same body `201` the same generation `id`
- Same `Idempotency-Key`, other `model`, `sampling` or `label` `409` `idempotency_key_conflict`

## Request

Specify `model` (`diffio-flash`, `diffio-pro`, or any ID from `GET /models`) and optional `label` or `sampling`.

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | string | Yes | Unique identifier of 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. |
| `Idempotency-Key` | string | No | Optional key (up to 255 characters) for safe retries. Repeating the same request returns the original generation; changing `model`, `sampling`, or `label` returns `409` (`idempotency_key_conflict`). |

### Body fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Model ID from `GET /models`, such as `diffio-flash`, `diffio-pro`, `diffio-4.7-flash`, or `diffio-4.7-pro`. |
| `sampling` | object | No | Optional advanced sampling overrides object. |
| `label` | string | No | Optional caller-defined name for this generation (up to 120 characters), such as `"Take 1"`. |

## Example request

**Python**

```python
import os
from diffio import DiffioClient

key = os.environ["DIFFIO_API_KEY"]
client = DiffioClient(api_key=key)

generation = client.generations.create(
    "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
    model="diffio-flash",
    label="Take 1",
    idempotency_key="v2docs-g-mwe8tm1g",
)
```

**Node.js**

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

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

const generation =
  await client.generations.create(
    "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
    {
      model: "diffio-flash",
      label: "Take 1",
    },
    { idempotencyKey: "v2docs-g-mwe8tm1g" },
  )
```

**cURL**

```bash
curl -X POST "https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations" \
  -H "Authorization: Bearer $DIFFIO_API_KEY" \
  -H "Idempotency-Key: v2docs-g-mwe8tm1g" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "diffio-flash",
    "label": "Take 1"
  }'
```

**JSON: JSON body**

```json
{
  "model": "diffio-flash",
  "label": "Take 1"
}
```

## Response

Returns the new `generation` (`status: "queued"` or `"processing"`).

Success: `201`

### Response fields

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | Always | Unique generation identifier (UUID). |
| `object` | string | Always | Resource type, always `"generation"`. |
| `status` | string | Always | Lifecycle state: `queued`, `processing`, `complete`, or `failed`. |
| `model` | string \| null | Always | Hosted model that ran or is running (such as `diffio-4.7-flash` or `diffio-4.7-pro`), or `null`. |
| `stage` | string \| null | Always | Current worker stage (`pending`, `preparing`, `transcribing`, `queued`, `starting`, `downloading`, `decoding`, `restoring`, `finalizing`, `uploading`, then `complete` or `failed`), or `null`. |
| `stage_progress` | object \| null | Always | Live worker progress while `status` is `processing`, or `null` before a worker reports progress and after completion. [Fields below](#fields-stage-progress) |
| `queue` | object \| null | Always | Worker queue snapshot while the generation waits to start, or `null` otherwise. [Fields below](#fields-queue) |
| `error` | object \| null | Always | Failure details when `status` is `failed` (also includes boolean `retryable` and nullable `explanation` on the wire), or `null` otherwise. |
| `error.code` | string | Always | Stable `snake_case` generation failure code (such as `restoration_failed`, `no_speech_detected`, `transcription_failed`, `upload_missing`, or `generation_failed`). |
| `error.message` | string | Always | Human-readable message explaining why the generation failed. |

**`stage_progress` fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `stage_progress.overall_percent` | number | Sometimes | Overall generation completion percentage from `0` to `100`, present once reported. |
| `stage_progress.stage_percent` | number | Sometimes | Completion percentage of the current `stage` from `0` to `100`, present once reported. |
| `stage_progress.bytes_done` | number | Sometimes | Bytes transferred so far in a `downloading` or `uploading` stage. |
| `stage_progress.bytes_total` | number | Sometimes | Total bytes to transfer in the current `downloading` or `uploading` stage. |
| `stage_progress.available_through_seconds` | number | Sometimes | Seconds of restored output already playable via `hls_master` while processing. |
| `stage_progress.duration_seconds` | number | Sometimes | Recording length in seconds as reported by the worker. |

**`queue` fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `queue.position` | integer \| null | Always | Number of queued jobs ahead of this generation, or `null`. |
| `queue.connected_workers` | integer \| null | Always | Total workers connected to the queue, or `null`. |
| `queue.idle_workers` | integer \| null | Always | Connected workers currently idle, or `null`. |
| `queue.busy_workers` | integer \| null | Always | Connected workers currently running jobs, or `null`. |
| `queue.wait_reason` | string \| null | Always | Why the job is waiting (`all_busy`, `no_workers`, or `next_in_line`), or `null`. |
| `queue.message` | string | Always | Human-readable message explaining why the generation is waiting. |

**Other response fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `project_id` | string | Always | Identifier of the parent project. |
| `requested_model` | string \| null | Always | Model name sent in the request (hosted model, tier alias, or retired model), or `null`. |
| `substituted` | boolean | Always | True when `requested_model` was a retired model name and ran on the current hosted model of the same tier; `false` for hosted names and aliases. |
| `price_per_hour_usd` | number \| null | Always | List price per hour in USD applied to this generation (for retired models, the lower of the requested and serving models' list prices), or `null`. |
| `warnings` | array | Always | Non-fatal warnings recorded during processing (the generation still runs). [Fields below](#fields-warnings) |
| `label` | string \| null | Always | Caller-supplied label (up to 120 characters), `Transcript edit` for an edit, or `null` when none was set. |
| `kind` | string | Always | Generation kind: `restore` for a full recording restore, or `edit` for a transcript edit of a finished Pro generation. |
| `source_generation_id` | string \| null | Always | For `kind: "edit"`, the Pro generation that was edited; `null` for `restore`. |
| `edit` | object \| null | Always | Transcript edit details and progress when `kind` is `edit`, or `null` for `restore`. [Fields below](#fields-edit) |
| `transcript_editable` | boolean | Always | True when this result's transcript can be edited via `POST .../edits` (a finished Pro result with stored edit latents). |
| `duration_seconds` | number \| null | Always | Duration of the restored output in seconds once known, or `null`. |
| `quality_score` | number \| null | Always | Estimated speech quality score of the result from `1` to `5`, or `null`. |
| `transcription_status` | string \| null | Always | Word-timed transcript status: `preparing`, `ready`, or `failed`; `null` when no transcription is reported. |
| `files_available` | array | Always | Sorted names of artifacts currently available from `GET .../media` (such as `audio`, `video`, `hls_master`, `transcript`, `stems_manifest`). |
| `stems_status` | string \| null | Always | Separated speech and background track status: `preparing`, `ready`, or `failed`; `null` when none are reported. |
| `created_at` | string \| null | Always | ISO 8601 UTC timestamp when the generation was created, or `null`. |
| `updated_at` | string \| null | Always | ISO 8601 UTC timestamp when the generation last changed, or `null`. |

**`warnings[]` fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `warnings[].code` | string | Always | Warning code; `unsupported_language` when the transcript contains words in languages the model cannot restore. |
| `warnings[].languages` | array | Sometimes | ISO 639-1 language codes of unsupported words, ordered by word count. |
| `warnings[].message` | string | Always | Human-readable warning message. |

**`edit` fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `edit.edit_count` | integer \| null | Always | Number of edits (each run of changed, inserted, or removed words between kept words counts once), or `null`. |
| `edit.max_windows` | integer \| null | Always | Maximum number of 30-second windows this edit could restore, or `null`. |
| `edit.windows` | integer \| null | Always | Actual number of windows restored (or being restored) by the worker, or `null` before starting. |
| `edit.windows_done` | integer \| null | Always | Number of restore windows completed so far, or `null`. |
| `edit.ranges` | array | Always | Time ranges on the recording (in seconds) covered by the restored windows. |
| `edit.ranges[].start` | number | Sometimes | Window start time in seconds. |
| `edit.ranges[].end` | number | Sometimes | Window end time in seconds. |
| `edit.billable_seconds` | integer \| null | Always | Seconds billed once complete (`30` per restored window, `0` when no window was restored), or `null` until complete. |
| `edit.cut_seconds` | number \| null | Always | Seconds trimmed from the recording by `tighten`, or `null`. |
| `edit.request_id` | string \| null | Always | Caller-supplied `request_id` from the edit request, or `null`. |
| `edit.language` | string \| null | Always | Primary language code used for the edit, or `null`. |
| `edit.tighten` | object \| null | Always | Silence-shortening settings applied by the edit, or `null` when none were requested. |
| `edit.tighten.close_removed_gaps` | boolean | Always | Whether silence left by removed words was closed. |
| `edit.tighten.max_pause_seconds` | number \| null | Always | Maximum pause duration in seconds after shortening, or `null` when pauses were left unchanged. |

## Example response (201)

**Response, key fields: Response: key fields**

```json
{
  "id": "ce832a32-a1ce-516a-b8bd-75457bd8517f",
  "object": "generation",
  "status": "processing",
  "stage": "preparing",
  "stage_progress": null,
  "queue": null,
  "error": null,
  "model": "diffio-4.7-flash"
}
```

**Full response: Successful response**

```json
{
  "id": "ce832a32-a1ce-516a-b8bd-75457bd8517f",
  "object": "generation",
  "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
  "status": "processing",
  "stage": "preparing",
  "stage_progress": null,
  "queue": null,
  "warnings": [],
  "label": "Take 1",
  "kind": "restore",
  "source_generation_id": null,
  "edit": null,
  "transcript_editable": false,
  "duration_seconds": null,
  "quality_score": null,
  "transcription_status": null,
  "files_available": [],
  "error": null,
  "model": "diffio-4.7-flash",
  "requested_model": "diffio-flash",
  "substituted": false,
  "price_per_hour_usd": 5,
  "stems_status": null,
  "created_at": "2026-11-13T00:33:27.117344Z",
  "updated_at": "2026-11-13T00:33:27.999000Z"
}
```

## Return codes

- `201` Generation created and queued for restoration.
- `400`
  - Malformed JSON: [`invalid_json`](https://diffio.ai/docs/api-reference/errors/#invalid_json)
  - Missing `model`: [`missing_field`](https://diffio.ai/docs/api-reference/errors/#missing_field)
  - Invalid `label` or `sampling`: [`invalid_field`](https://diffio.ai/docs/api-reference/errors/#invalid_field)
  - Oversized header: [`invalid_header`](https://diffio.ai/docs/api-reference/errors/#invalid_header)
  - Unrecognized `model`: [`unknown_model`](https://diffio.ai/docs/api-reference/errors/#unknown_model)
- `402` The account cannot pay for this restore (checked at the 60-second minimum until the upload is probed); see the error codes below. [`insufficient_credit`](https://diffio.ai/docs/api-reference/errors/#insufficient_credit) [`needs_payment_method`](https://diffio.ai/docs/api-reference/errors/#needs_payment_method) [`payment_failed`](https://diffio.ai/docs/api-reference/errors/#payment_failed) [`usage_limit_reached`](https://diffio.ai/docs/api-reference/errors/#usage_limit_reached)
- `403` Key is inactive or lacks `generations:write`. [`permission_denied`](https://diffio.ai/docs/api-reference/errors/#permission_denied)
- `404` No project with that `project_id` exists for this account and end user. [`project_not_found`](https://diffio.ai/docs/api-reference/errors/#project_not_found)
- `409`
  - Reused `Idempotency-Key` with different body fields
  - The project failed or was removed
  - The API key was revoked
  - During admission
  Codes: [`idempotency_key_conflict`](https://diffio.ai/docs/api-reference/errors/#idempotency_key_conflict), [`generation_unavailable`](https://diffio.ai/docs/api-reference/errors/#generation_unavailable),
- `500` Generation record was created without starting or billing; retry with the same `Idempotency-Key`. [`generation_start_failed`](https://diffio.ai/docs/api-reference/errors/#generation_start_failed)
- **`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).

### Error codes

| Status | Code | Meaning | Also returned |
| --- | --- | --- | --- |
| `402` | [`insufficient_credit`](https://diffio.ai/docs/api-reference/errors/#insufficient_credit) | Your API credit is used up, or cannot cover this file. | `estimated_cost_cents` `remaining_credit_cents` |
| `402` | [`needs_payment_method`](https://diffio.ai/docs/api-reference/errors/#needs_payment_method) | Card billing accounts: no payment method, and the credit is used up or cannot cover this file. | `estimated_cost_cents` `remaining_credit_cents` (when the credit was read) |
| `402` | [`payment_failed`](https://diffio.ai/docs/api-reference/errors/#payment_failed) | A payment for API usage failed, or the last invoice of ended card billing is unpaid. | `details` omitted |
| `402` | [`usage_limit_reached`](https://diffio.ai/docs/api-reference/errors/#usage_limit_reached) | Unbilled usage reached $100; it is being charged now. | `details` omitted |
| `409` | [`idempotency_key_conflict`](https://diffio.ai/docs/api-reference/errors/#idempotency_key_conflict) | Idempotency-Key was already used with different request fields. | `details` omitted |

### Example error response

**Error response**

```json
{
  "error": {
    "code": "insufficient_credit",
    "message": "This file needs about $1.25 of API credit and your balance is $0.40. Add credit in the developer dashboard to continue.",
    "request_id": "f064e4099097414da3fb5b37684ab1bb",
    "details": {
      "estimated_cost_cents": 125,
      "remaining_credit_cents": 40
    }
  }
}
```

## Notes

- Restores bill whole seconds rounded up with a 60-second minimum (`$5`/hour for `diffio-4.7-flash`, `$10`/hour for `diffio-4.7-pro`). Failed generations charge nothing.
- Poll [Get a generation](https://diffio.ai/docs/api-reference/get-generation/) (or use `client.generations.wait(...)` or `generation.completed` / `generation.failed` webhooks), then fetch URLs from [Get a playback grant](https://diffio.ai/docs/api-reference/get-generation-media/).
- Only finished Pro generations (`diffio-pro` / `diffio-4.7-pro`) set `transcript_editable: true` for [Edit a generation's transcript](https://diffio.ai/docs/api-reference/create-transcript-edit/) and [Ask the edit assistant](https://diffio.ai/docs/api-reference/create-transcript-assistant-turn/).

## Related pages

- Previous: [Complete a project's upload](https://diffio.ai/docs/api-reference/complete-project-upload/): Verify and prepare a finished multipart upload immediately instead of waiting for edge callback.
- Next: [List a project's generations](https://diffio.ai/docs/api-reference/list-project-generations/): List every restore and transcript edit generation on a project, newest first.

- [Models](https://diffio.ai/docs/overview/models/): Choosing between Diffio 4.7 Flash and Pro.
- [API model cards](https://diffio.ai/api-model-cards/): Best uses for each model id.
- [API pricing](https://diffio.ai/api-pricing/): The current rate per hour for each model.
- [Webhooks guide](https://diffio.ai/docs/developers/webhooks/): Get notified when a generation finishes instead of polling.
