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/estimate-transcript-edit.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

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:/
- 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
Headers
| Field | Type | Required | Description |
|---|---|---|---|
#Diffio-End-User | string | Required: 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 | Required: No | Full ordered transcript after editing (GET .../transcript words with your changes). Omit only when shortening pauses via tighten.max_pause_seconds.Fields below |
#tighten | object | Required: No | Optional silence-shortening settings for audio projects (409 not_editable on video projects). |
#tighten. | boolean | Required: No | Close the silence left where words were removed. |
#tighten. | number | null | Required: No | Shorten every pause longer than this threshold (from 0.25 to 3 seconds), or null to leave pauses unchanged. |
#request_id | string | Required: No | Optional caller-chosen identifier matching [A-Za-z0-9_-]{1,64}, echoed as edit.request_id. |
words[] 10 fields
| Field | Type | Required | Description |
|---|---|---|---|
#words[] | string | Required: No | Word identifier from GET .../transcript (such as word-0). |
#words[] | string | Required: No | Word text after editing (up to 200 characters); pass "" to remove the word. |
#words[] | number | null | Required: No | Start time in seconds on the recording for a kept word; omit or pass null for newly inserted words. |
#words[] | number | null | Required: No | End time in seconds on the recording for a kept word (>= start); omit or pass null for newly inserted words. |
#words[] | number | null | Required: No | Transcriber confidence from 0 to 1, or null; ignored by edits so GET .../transcript words pass back unchanged. |
#words[] | string | Required: No | Optional speaker label from the transcript; ignored by edits. |
#words[] | string | Required: No | Optional language code for the word. |
#words[] | string | Required: No | Alternate field name for word text; text takes precedence when both are present. |
#words[] | boolean | Required: No | Set true when the word's text was edited so it is re-synthesized (start and end are ignored). |
#words[] | boolean | Required: No | Set true to re-synthesize the word with its existing text (start and end are ignored). |
Request
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",
},
],
)Response
Returns the edit count, window size (30 seconds), and max_billable_seconds.
Success: 200OK.
Response fields
| Field | Type | Present | Description |
|---|---|---|---|
#object | string | Always | Resource type, always "transcript_edit_estimate".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. |
Response 200OK.
{
"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
200OK.Returns the validated edit estimate without creating a generation or holding credit.400Bad request.Malformed JSON, or 2 more causes
- Malformed JSON
- Invalid or unchanged
wordsor invalidtighten - Oversized header
invalid_jsoninvalid_fieldinvalid_header403Forbidden: the key lacks permission.Key is inactive or lacksgenerations:write.permission_denied404Not found.Project not found, or generation not found.project_not_foundgeneration_not_found409Conflict: see error.code for which one.Generation is still running, or 2 more causes
- Generation is still running
- Generation or transcript failed
- Generation is not a finished editable Pro result or
tightenwas requested on video
not_readynot_availablenot_editable502Bad gateway.Upstream edit estimator error.internal_error401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint401Unauthorized: 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": {
"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_secondsin an editor before submitting Edit a generation's transcript. - New or replaced words cannot contain digits or symbols and cannot be in Japanese or Thai (
400invalid_field), and on recordings over 30 seconds each changed span must fit within 26 seconds. wordsthat leave every word unchanged withouttighten.max_pause_secondsreturn400(invalid_fieldondetails.field: "words").