Skip to content

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

FieldTypeRequiredDescription
#project_idstringRequired: YesUnique identifier of the project.
#generation_idstringRequired: YesUnique identifier of the generation within the project.

Headers

FieldTypeRequiredDescription
#Diffio-End-UserstringRequired: NoOptional end-user identifier (up to 128 characters). Scopes the request to that end user's projects; omit to act across the whole account.
#Idempotency-KeystringRequired: NoOptional 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

FieldTypeRequiredDescription
#wordsarrayRequired: NoFull ordered transcript after editing (GET .../transcript words with your changes). Omit only when shortening pauses via tighten.max_pause_seconds.Fields below
#tightenobjectRequired: NoOptional silence-shortening settings for audio projects (409 not_editable on video projects).
#tighten.close_removed_gapsbooleanRequired: NoClose the silence left where words were removed.
#tighten.max_pause_secondsnumber | nullRequired: NoShorten every pause longer than this threshold (from 0.25 to 3 seconds), or null to leave pauses unchanged.
#request_idstringRequired: NoOptional caller-chosen identifier matching [A-Za-z0-9_-]{1,64}, echoed as edit.request_id.
words[] 10 fields
FieldTypeRequiredDescription
#words[].idstringRequired: NoWord identifier from GET .../transcript (such as word-0).
#words[].textstringRequired: NoWord text after editing (up to 200 characters); pass "" to remove the word.
#words[].startnumber | nullRequired: NoStart time in seconds on the recording for a kept word; omit or pass null for newly inserted words.
#words[].endnumber | nullRequired: NoEnd time in seconds on the recording for a kept word (>= start); omit or pass null for newly inserted words.
#words[].probabilitynumber | nullRequired: NoTranscriber confidence from 0 to 1, or null; ignored by edits so GET .../transcript words pass back unchanged.
#words[].speakerstringRequired: NoOptional speaker label from the transcript; ignored by edits.
#words[].languagestringRequired: NoOptional language code for the word.
#words[].wordstringRequired: NoAlternate field name for word text; text takes precedence when both are present.
#words[].changedbooleanRequired: NoSet true when the word's text was edited so it is re-synthesized (start and end are ignored).
#words[].regeneratebooleanRequired: NoSet true to re-synthesize the word with its existing text (start and end are ignored).

Request

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

FieldTypePresentDescription
#idstringAlwaysUnique generation identifier (UUID).
#objectstringAlwaysResource type, always "generation".generation
#statusstringAlwaysLifecycle state: queued, processing, complete, or failed.queuedprocessingcompletefailed
#modelstring | nullAlwaysHosted model that ran or is running (such as diffio-4.7-flash or diffio-4.7-pro), or null.
#kindstringAlwaysGeneration kind: restore for a full recording restore, or edit for a transcript edit of a finished Pro generation.restoreedit
#source_generation_idstring | nullAlwaysFor kind: "edit", the Pro generation that was edited; null for restore.
#editobject | nullAlwaysTranscript edit details and progress when kind is edit, or null for restore.Fields below
edit 14 fields
FieldTypePresentDescription
#edit.edit_countinteger | nullAlwaysNumber of edits (each run of changed, inserted, or removed words between kept words counts once), or null.
#edit.max_windowsinteger | nullAlwaysMaximum number of 30-second windows this edit could restore, or null.
#edit.windowsinteger | nullAlwaysActual number of windows restored (or being restored) by the worker, or null before starting.
#edit.windows_doneinteger | nullAlwaysNumber of restore windows completed so far, or null.
#edit.rangesarrayAlwaysTime ranges on the recording (in seconds) covered by the restored windows.
#edit.ranges[].startnumberSometimesWindow start time in seconds.
#edit.ranges[].endnumberSometimesWindow end time in seconds.
#edit.billable_secondsinteger | nullAlwaysSeconds billed once complete (30 per restored window, 0 when no window was restored), or null until complete.
#edit.cut_secondsnumber | nullAlwaysSeconds trimmed from the recording by tighten, or null.
#edit.request_idstring | nullAlwaysCaller-supplied request_id from the edit request, or null.
#edit.languagestring | nullAlwaysPrimary language code used for the edit, or null.
#edit.tightenobject | nullAlwaysSilence-shortening settings applied by the edit, or null when none were requested.
#edit.tighten.close_removed_gapsbooleanAlwaysWhether silence left by removed words was closed.
#edit.tighten.max_pause_secondsnumber | nullAlwaysMaximum pause duration in seconds after shortening, or null when pauses were left unchanged.
Other response fields35 fields
FieldTypePresentDescription
#project_idstringAlwaysIdentifier of the parent project.
#requested_modelstring | nullAlwaysModel name sent in the request (hosted model, tier alias, or retired model), or null.
#substitutedbooleanAlwaysTrue 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_usdnumber | nullAlwaysList price per hour in USD applied to this generation (for retired models, the lower of the requested and serving models' list prices), or null.
#stagestring | nullAlwaysCurrent worker stage (pending, preparing, transcribing, queued, starting, downloading, decoding, restoring, finalizing, uploading, then complete or failed), or null.
#stage_progressobject | nullAlwaysLive worker progress while status is processing, or null before a worker reports progress and after completion.Fields below
#queueobject | nullAlwaysWorker queue snapshot while the generation waits to start, or null otherwise.Fields below
#warningsarrayAlwaysNon-fatal warnings recorded during processing (the generation still runs).Fields below
Show all 20 fields (12 more)
FieldTypePresentDescription
#labelstring | nullAlwaysCaller-supplied label (up to 120 characters), Transcript edit for an edit, or null when none was set.
#transcript_editablebooleanAlwaysTrue when this result's transcript can be edited via POST .../edits (a finished Pro result with stored edit latents).
#duration_secondsnumber | nullAlwaysDuration of the restored output in seconds once known, or null.
#quality_scorenumber | nullAlwaysEstimated speech quality score of the result from 1 to 5, or null.
#transcription_statusstring | nullAlwaysWord-timed transcript status: preparing, ready, or failed; null when no transcription is reported.preparingreadyfailed
#files_availablearrayAlwaysSorted names of artifacts currently available from GET .../media (such as audio, video, hls_master, transcript, stems_manifest).
#errorobject | nullAlwaysFailure details when status is failed (also includes boolean retryable and nullable explanation on the wire), or null otherwise.
#error.codestringAlwaysStable snake_case generation failure code (such as restoration_failed, no_speech_detected, transcription_failed, upload_missing, or generation_failed).
#error.messagestringAlwaysHuman-readable message explaining why the generation failed.
#stems_statusstring | nullAlwaysSeparated speech and background track status: preparing, ready, or failed; null when none are reported.preparingreadyfailed
#created_atstring | nullAlwaysISO 8601 UTC timestamp when the generation was created, or null.
#updated_atstring | nullAlwaysISO 8601 UTC timestamp when the generation last changed, or null.
stage_progress 6 fields
FieldTypePresentDescription
#stage_progress.overall_percentnumberSometimesOverall generation completion percentage from 0 to 100, present once reported.
#stage_progress.stage_percentnumberSometimesCompletion percentage of the current stage from 0 to 100, present once reported.
#stage_progress.bytes_donenumberSometimesBytes transferred so far in a downloading or uploading stage.
#stage_progress.bytes_totalnumberSometimesTotal bytes to transfer in the current downloading or uploading stage.
#stage_progress.available_through_secondsnumberSometimesSeconds of restored output already playable via hls_master while processing.
#stage_progress.duration_secondsnumberSometimesRecording length in seconds as reported by the worker.
queue 6 fields
FieldTypePresentDescription
#queue.positioninteger | nullAlwaysNumber of queued jobs ahead of this generation, or null.
#queue.connected_workersinteger | nullAlwaysTotal workers connected to the queue, or null.
#queue.idle_workersinteger | nullAlwaysConnected workers currently idle, or null.
#queue.busy_workersinteger | nullAlwaysConnected workers currently running jobs, or null.
#queue.wait_reasonstring | nullAlwaysWhy the job is waiting (all_busy, no_workers, or next_in_line), or null.
#queue.messagestringAlwaysHuman-readable message explaining why the generation is waiting.
warnings[] 3 fields
FieldTypePresentDescription
#warnings[].codestringAlwaysWarning code; unsupported_language when the transcript contains words in languages the model cannot restore.unsupported_language
#warnings[].languagesarraySometimesISO 639-1 language codes of unsupported words, ordered by word count.
#warnings[].messagestringAlwaysHuman-readable warning message.

Response 201Created.

Response: key fields
{
  "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 tighten or request_id
    • Oversized header
    invalid_jsoninvalid_fieldinvalid_header
  • 402Payment required: see error.code for the billing problem.Account cannot cover max_billable_seconds,,,, or. insufficient_creditneeds_payment_methodpayment_failedusage_limit_reachedpayment_required
  • 403Forbidden: the key lacks permission.Key is inactive or lacks generations:write. permission_denied
  • 404Not found.Project not found, or source generation not found. project_not_foundgeneration_not_found
  • 409Conflict: see error.code for which one.
    Reused Idempotency-Key with different edit fields, or 3 more causes
    • Reused Idempotency-Key with different edit fields
    • Source generation still running
    • Source or transcript failed
    • Source is not an editable Pro result or tighten was requested on video
    idempotency_key_conflictnot_readynot_availablenot_editable
  • 502Bad gateway.Upstream edit service error. internal_error
  • 503Service unavailable.Edit record was created without queueing or billing; retry the same request with the same Idempotency-Key. edit_not_queued
  • 401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint
    • 401Unauthorized: 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 response
{
  "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 and fetch its output from Get a playback grant, just like a standard restore.
  • Call Estimate a transcript edit first to validate words and preview max_billable_seconds for free.

Report an issue with this page