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

# Edit a generation's transcript

Creates a new generation (`kind: "edit"`) from a finished Pro generation (`transcript_editable: true`), re-synthesizing only the 30-second windows around changed, inserted, or removed words.

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

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

## Request

Send the full edited `words` array from `GET .../transcript` (with `text: ""` for removals, `changed: true` or omitted timings for replacements/insertions), optional audio `tighten`, and optional `request_id`. The example shows only the first three words; send every word of the transcript.

### 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. |
| `Idempotency-Key` | string | No | Optional key (up to 255 characters) for safe retries. Repeating the same edit returns the original edit generation and bills once; changing edit fields returns `409` (`idempotency_key_conflict`). |

### Body fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `words` | array | No | Full ordered transcript after editing (`GET .../transcript` words with your changes). Omit only when shortening pauses via `tighten.max_pause_seconds`. [Fields below](#fields-words) |
| `tighten` | object | No | Optional silence-shortening settings for audio projects (`409` `not_editable` on video projects). |
| `tighten.close_removed_gaps` | boolean | No | Close the silence left where words were removed. |
| `tighten.max_pause_seconds` | number \| null | No | Shorten every pause longer than this threshold (from `0.25` to `3` seconds), or `null` to leave pauses unchanged. |
| `request_id` | string | No | Optional caller-chosen identifier matching `[A-Za-z0-9_-]{1,64}`, echoed as `edit.request_id`. |

**`words[]` fields**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `words[].id` | string | No | Word identifier from `GET .../transcript` (such as `word-0`). |
| `words[].text` | string | No | Word text after editing (up to 200 characters); pass `""` to remove the word. |
| `words[].start` | number \| null | No | Start time in seconds on the recording for a kept word; omit or pass `null` for newly inserted words. |
| `words[].end` | number \| null | No | End time in seconds on the recording for a kept word (`>=` `start`); omit or pass `null` for newly inserted words. |
| `words[].probability` | number \| null | No | Transcriber confidence from `0` to `1`, or `null`; ignored by edits so `GET .../transcript` words pass back unchanged. |
| `words[].speaker` | string | No | Optional speaker label from the transcript; ignored by edits. |
| `words[].language` | string | No | Optional language code for the word. |
| `words[].word` | string | No | Alternate field name for word text; `text` takes precedence when both are present. |
| `words[].changed` | boolean | No | Set `true` when the word's text was edited so it is re-synthesized (`start` and `end` are ignored). |
| `words[].regenerate` | boolean | No | Set `true` to re-synthesize the word with its existing text (`start` and `end` are ignored). |

## Example request

**Python**

```python
import os
from diffio import DiffioClient

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

edit = client.edits.create(
    "73118d99-36cf-4039-8005-b962d522fff7",
    "73c84c4a-c1ca-5485-b396-171ab632d4b7",
    words=[
        {
            "id": "word-0",
            "text": "For",
            "start": 0.6,
            "end": 0.8,
            "probability": None,
            "language": "en",
        },
        {
            "id": "word-1",
            "text": "",
            "start": 0.84,
            "end": 0.94,
            "probability": None,
            "language": "en",
        },
        {
            "id": "word-2",
            "text": "lives",
            "start": 1.04,
            "end": 1.32,
            "probability": None,
            "language": "en",
        },
    ],
    request_id="edit-1042",
    idempotency_key="edit-1042",
)
```

**Node.js**

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

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

const edit = await client.edits.create(
  "73118d99-36cf-4039-8005-b962d522fff7",
  "73c84c4a-c1ca-5485-b396-171ab632d4b7",
  {
    words: [
      {
        id: "word-0",
        text: "For",
        start: 0.6,
        end: 0.8,
        probability: null,
        language: "en",
      },
      {
        id: "word-1",
        text: "",
        start: 0.84,
        end: 0.94,
        probability: null,
        language: "en",
      },
      {
        id: "word-2",
        text: "lives",
        start: 1.04,
        end: 1.32,
        probability: null,
        language: "en",
      },
    ],
    request_id: "edit-1042",
  },
  { idempotencyKey: "edit-1042" },
)
```

**cURL**

```bash
curl -X POST "https://api.diffio.ai/v2/projects/73118d99-36cf-4039-8005-b962d522fff7/generations/73c84c4a-c1ca-5485-b396-171ab632d4b7/edits" \
  -H "Authorization: Bearer $DIFFIO_API_KEY" \
  -H "Idempotency-Key: edit-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "words": [
      {
        "id": "word-0",
        "text": "For",
        "start": 0.6,
        "end": 0.8,
        "probability": null,
        "language": "en",
        "label": "speech"
      },
      {
        "id": "word-1",
        "text": "",
        "start": 0.84,
        "end": 0.94,
        "probability": null,
        "language": "en",
        "label": "speech"
      },
      {
        "id": "word-2",
        "text": "lives",
        "start": 1.04,
        "end": 1.32,
        "probability": null,
        "language": "en",
        "label": "speech"
      }
    ],
    "request_id": "edit-1042"
  }'
```

**JSON: JSON body**

```json
{
  "words": [
    {
      "id": "word-0",
      "text": "For",
      "start": 0.6,
      "end": 0.8,
      "probability": null,
      "language": "en",
      "label": "speech"
    },
    {
      "id": "word-1",
      "text": "",
      "start": 0.84,
      "end": 0.94,
      "probability": null,
      "language": "en",
      "label": "speech"
    },
    {
      "id": "word-2",
      "text": "lives",
      "start": 1.04,
      "end": 1.32,
      "probability": null,
      "language": "en",
      "label": "speech"
    }
  ],
  "request_id": "edit-1042"
}
```

## Response

Returns the new `Generation` (`kind: "edit"`, `source_generation_id` pointing to the edited Pro generation).

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`. |
| `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) |

**`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. |

**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`. |
| `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) |
| `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. |
| `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`). |
| `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. |
| `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`. |

**`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. |

**`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. |

## Example response (201)

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

```json
{
  "id": "00000000-0000-5000-8000-000000000001",
  "object": "generation",
  "status": "queued",
  "kind": "edit",
  "source_generation_id": "73c84c4a-c1ca-5485-b396-171ab632d4b7",
  "edit": {
    "edit_count": 1,
    "max_windows": 1,
    "windows": null,
    "windows_done": null,
    "ranges": [],
    "billable_seconds": null,
    "cut_seconds": null,
    "request_id": "edit-1042",
    "language": "en",
    "tighten": null
  },
  "model": "diffio-4.7-pro"
}
```

**Full response: Successful response**

```json
{
  "id": "00000000-0000-5000-8000-000000000001",
  "object": "generation",
  "project_id": "73118d99-36cf-4039-8005-b962d522fff7",
  "status": "queued",
  "stage": "preparing",
  "stage_progress": null,
  "queue": null,
  "warnings": [],
  "label": "Transcript edit",
  "kind": "edit",
  "source_generation_id": "73c84c4a-c1ca-5485-b396-171ab632d4b7",
  "edit": {
    "edit_count": 1,
    "max_windows": 1,
    "windows": null,
    "windows_done": null,
    "ranges": [],
    "billable_seconds": null,
    "cut_seconds": null,
    "request_id": "edit-1042",
    "language": "en",
    "tighten": null
  },
  "transcript_editable": false,
  "duration_seconds": 31.8,
  "quality_score": null,
  "transcription_status": "preparing",
  "files_available": [
    "edited_transcript"
  ],
  "error": null,
  "model": "diffio-4.7-pro",
  "requested_model": "diffio-pro",
  "substituted": false,
  "price_per_hour_usd": 10,
  "stems_status": null,
  "created_at": "2026-11-13T00:34:12.503218Z",
  "updated_at": "2026-11-13T00:34:12.503218Z"
}
```

## Return codes

- `201` Edit generation created and queued.
- `400`
  - Malformed JSON
  - Invalid or unchanged `words`
  - Unsupported characters/digits in new words
  - Changed span over 26 seconds
  - Invalid `tighten` or `request_id`
  - Oversized header
  Codes: [`invalid_json`](https://diffio.ai/docs/api-reference/errors/#invalid_json), [`invalid_field`](https://diffio.ai/docs/api-reference/errors/#invalid_field), [`invalid_header`](https://diffio.ai/docs/api-reference/errors/#invalid_header)
- `402` Account cannot cover `max_billable_seconds`,,,, or. [`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) [`payment_required`](https://diffio.ai/docs/api-reference/errors/#payment_required)
- `403` Key is inactive or lacks `generations:write`. [`permission_denied`](https://diffio.ai/docs/api-reference/errors/#permission_denied)
- `404` Project not found, or source 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`
  - Reused `Idempotency-Key` with different edit fields: [`idempotency_key_conflict`](https://diffio.ai/docs/api-reference/errors/#idempotency_key_conflict)
  - Source generation still running: [`not_ready`](https://diffio.ai/docs/api-reference/errors/#not_ready)
  - Source or transcript failed: [`not_available`](https://diffio.ai/docs/api-reference/errors/#not_available)
  - Source is not an editable Pro result or `tighten` was requested on video: [`not_editable`](https://diffio.ai/docs/api-reference/errors/#not_editable)
- `502` Upstream edit service error. [`internal_error`](https://diffio.ai/docs/api-reference/errors/#internal_error)
- `503` Edit record was created without queueing or billing; retry the same request with the same `Idempotency-Key`. [`edit_not_queued`](https://diffio.ai/docs/api-reference/errors/#edit_not_queued)
- **`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

- Transcript edits bill `30` seconds per restored window at the Pro model's rate with no 60-second minimum. Removed words are restored again too, unless `tighten.close_removed_gaps` cuts them out whole; an edit that restores nothing (`max_billable_seconds: 0`, such as one that only shortens pauses) holds no credit and bills `$0`.
- Poll the returned edit generation's `id` with [Get a generation](https://diffio.ai/docs/api-reference/get-generation/) and fetch its output from [Get a playback grant](https://diffio.ai/docs/api-reference/get-generation-media/), just like a standard restore.
- Call [Estimate a transcript edit](https://diffio.ai/docs/api-reference/estimate-transcript-edit/) first to validate `words` and preview `max_billable_seconds` for free.

## Related pages

- Previous: [Estimate a transcript edit](https://diffio.ai/docs/api-reference/estimate-transcript-edit/): Estimate the changed word runs, 30-second windows, and maximum billable seconds of a Pro transcript edit.
- Next: [Get the saved mix](https://diffio.ai/docs/api-reference/get-generation-mix/): Read the saved background gain, speech leveling setting, and revision for a generation's separated tracks.

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