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

# Estimate a transcript edit

Validates a proposed transcript edit on a finished Pro generation and returns the maximum 30-second windows and `max_billable_seconds` it could bill, without creating or charging anything.

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

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

## Request

Send the same JSON body (`words`, optional `tighten`, optional `request_id`) that you plan to pass to `POST .../edits`. 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. |

### 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)

estimate = client.edits.estimate(
    "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",
        },
    ],
)
```

**Node.js**

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

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

const estimate =
  await client.edits.estimate(
    "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",
        },
      ],
    },
  )
```

**cURL**

```bash
curl -X POST "https://api.diffio.ai/v2/projects/73118d99-36cf-4039-8005-b962d522fff7/generations/73c84c4a-c1ca-5485-b396-171ab632d4b7/edits/estimate" \
  -H "Authorization: Bearer $DIFFIO_API_KEY" \
  -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"
      }
    ]
  }'
```

**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"
    }
  ]
}
```

## Response

Returns the edit count, window size (`30` seconds), and `max_billable_seconds`.

Success: `200`

### Response fields

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `object` | string | Always | Resource type, always `"transcript_edit_estimate"`. |
| `project_id` | string | Always | Identifier of the parent project. |
| `generation_id` | string | Always | Identifier of the Pro generation being checked. |
| `edit_count` | integer \| null | Always | Number of edits: each run of changed, inserted, or removed words between kept words counts once (`0` when the edit only shortens pauses), or `null`. |
| `max_windows` | integer \| null | Always | Upper bound on 30-second windows the edit could restore, or `null`. |
| `window_seconds` | integer | Always | Billable seconds per restored window (`30`). |
| `max_billable_seconds` | integer | Always | Maximum seconds this edit could bill, with no 60-second minimum. `0` only when nothing is said again: the edit only shortens pauses, or only removes runs that `tighten.close_removed_gaps` cuts out whole. Other removed words are restored again and bill a window. |

## Example response (200)

**Successful response**

```json
{
  "object": "transcript_edit_estimate",
  "project_id": "73118d99-36cf-4039-8005-b962d522fff7",
  "generation_id": "73c84c4a-c1ca-5485-b396-171ab632d4b7",
  "edit_count": 1,
  "max_windows": 1,
  "window_seconds": 30,
  "max_billable_seconds": 30
}
```

## Return codes

- `200` Returns the validated edit estimate without creating a generation or holding credit.
- `400`
  - Malformed JSON: [`invalid_json`](https://diffio.ai/docs/api-reference/errors/#invalid_json)
  - Invalid or unchanged `words` or invalid `tighten`: [`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`
  - Generation is still running: [`not_ready`](https://diffio.ai/docs/api-reference/errors/#not_ready)
  - Generation or transcript failed: [`not_available`](https://diffio.ai/docs/api-reference/errors/#not_available)
  - Generation is not a finished editable Pro result or `tighten` was requested on video: [`not_editable`](https://diffio.ai/docs/api-reference/errors/#not_editable)
- `502` Upstream edit estimator 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

- Estimating is free and skips credit checks, so you can preview `max_billable_seconds` in an editor before submitting [Edit a generation's transcript](https://diffio.ai/docs/api-reference/create-transcript-edit/).
- New or replaced words cannot contain digits or symbols and cannot be in Japanese or Thai (`400` `invalid_field`), and on recordings over 30 seconds each changed span must fit within 26 seconds.
- `words` that leave every word unchanged without `tighten.max_pause_seconds` return `400` (`invalid_field` on `details.field: "words"`).

## Related pages

- Previous: [Get a playback grant](https://diffio.ai/docs/api-reference/get-generation-media/): Mint 6-hour signed playback and download URLs for a generation's audio, video, HLS, stems, and transcript files.
- Next: [Edit a generation's transcript](https://diffio.ai/docs/api-reference/create-transcript-edit/): Edit a finished Pro generation's transcript and re-restore only the windows around changed words.

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