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

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:/
- 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
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. |
#Idempotency-Key | string | Required: 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 | 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)
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",
)Billed calls are not offered here; send this one from your code.
Response
Returns the new Generation (kind: "edit", source_generation_id pointing to the edited Pro generation).
Success: 201Created.
Response fields
| Field | Type | Present | Description |
|---|---|---|---|
#id | string | Always | Unique generation identifier (UUID). |
#object | string | Always | Resource type, always "generation".generation |
#status | string | Always | Lifecycle state: queued, processing, complete, or failed.queuedprocessingcompletefailed |
#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.restoreedit |
#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 |
edit 14 fields
| Field | Type | Present | Description |
|---|---|---|---|
#edit. | integer | null | Always | Number of edits (each run of changed, inserted, or removed words between kept words counts once), or null. |
#edit. | integer | null | Always | Maximum number of 30-second windows this edit could restore, or null. |
#edit. | integer | null | Always | Actual number of windows restored (or being restored) by the worker, or null before starting. |
#edit. | integer | null | Always | Number of restore windows completed so far, or null. |
#edit. | array | Always | Time ranges on the recording (in seconds) covered by the restored windows. |
#edit. | number | Sometimes | Window start time in seconds. |
#edit. | number | Sometimes | Window end time in seconds. |
#edit. | integer | null | Always | Seconds billed once complete (30 per restored window, 0 when no window was restored), or null until complete. |
#edit. | number | null | Always | Seconds trimmed from the recording by tighten, or null. |
#edit. | string | null | Always | Caller-supplied request_id from the edit request, or null. |
#edit. | string | null | Always | Primary language code used for the edit, or null. |
#edit. | object | null | Always | Silence-shortening settings applied by the edit, or null when none were requested. |
#edit. | boolean | Always | Whether silence left by removed words was closed. |
#edit. | number | null | Always | Maximum pause duration in seconds after shortening, or null when pauses were left unchanged. |
Other response fields35 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 |
#queue | object | null | Always | Worker queue snapshot while the generation waits to start, or null otherwise.Fields below |
#warnings | array | Always | Non-fatal warnings recorded during processing (the generation still runs).Fields below |
Show all 20 fields (12 more)
| Field | Type | Present | Description |
|---|---|---|---|
#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.preparingreadyfailed |
#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. | string | Always | Stable snake_case generation failure code (such as restoration_failed, no_speech_detected, transcription_failed, upload_missing, or generation_failed). |
#error. | 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.preparingreadyfailed |
#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 6 fields
| Field | Type | Present | Description |
|---|---|---|---|
#stage_progress. | number | Sometimes | Overall generation completion percentage from 0 to 100, present once reported. |
#stage_progress. | number | Sometimes | Completion percentage of the current stage from 0 to 100, present once reported. |
#stage_progress. | number | Sometimes | Bytes transferred so far in a downloading or uploading stage. |
#stage_progress. | number | Sometimes | Total bytes to transfer in the current downloading or uploading stage. |
#stage_progress. | number | Sometimes | Seconds of restored output already playable via hls_master while processing. |
#stage_progress. | number | Sometimes | Recording length in seconds as reported by the worker. |
queue 6 fields
| Field | Type | Present | Description |
|---|---|---|---|
#queue. | integer | null | Always | Number of queued jobs ahead of this generation, or null. |
#queue. | integer | null | Always | Total workers connected to the queue, or null. |
#queue. | integer | null | Always | Connected workers currently idle, or null. |
#queue. | integer | null | Always | Connected workers currently running jobs, or null. |
#queue. | string | null | Always | Why the job is waiting (all_busy, no_workers, or next_in_line), or null. |
#queue. | string | Always | Human-readable message explaining why the generation is waiting. |
warnings[] 3 fields
| Field | Type | Present | Description |
|---|---|---|---|
#warnings[] | string | Always | Warning code; unsupported_language when the transcript contains words in languages the model cannot restore.unsupported_language |
#warnings[] | array | Sometimes | ISO 639-1 language codes of unsupported words, ordered by word count. |
#warnings[] | string | Always | Human-readable warning message. |
Response 201Created.
{
"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"
}Return codes
201Created.Edit generation created and queued.400Bad request.Malformed JSON, or 5 more causes
- Malformed JSON
- Invalid or unchanged
words - Unsupported characters/digits in new words
- Changed span over 26 seconds
- Invalid
tightenorrequest_id - Oversized header
invalid_jsoninvalid_fieldinvalid_header402Payment required: see error.code for the billing problem.Account cannot covermax_billable_seconds,,,, or.insufficient_creditneeds_payment_methodpayment_failedusage_limit_reachedpayment_required403Forbidden: the key lacks permission.Key is inactive or lacksgenerations:write.permission_denied404Not found.Project not found, or source generation not found.project_not_foundgeneration_not_found409Conflict: see error.code for which one.Reused
Idempotency-Keywith different edit fields, or 3 more causes- Reused
Idempotency-Keywith different edit fields - Source generation still running
- Source or transcript failed
- Source is not an editable Pro result or
tightenwas requested on video
idempotency_key_conflictnot_readynot_availablenot_editable- Reused
502Bad gateway.Upstream edit service error.internal_error503Service unavailable.Edit record was created without queueing or billing; retry the same request with the sameIdempotency-Key.edit_not_queued401Unauthorized: 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
- Transcript edits bill
30seconds per restored window at the Pro model's rate with no 60-second minimum. Removed words are restored again too, unlesstighten.close_removed_gapscuts 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
idwith Get a generation and fetch its output from Get a playback grant, just like a standard restore. - Call Estimate a transcript edit first to validate
wordsand previewmax_billable_secondsfor free.