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

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.

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

Response

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

Success: 200OK.

Response fields

FieldTypePresentDescription
#objectstringAlwaysResource type, always "transcript_edit_estimate".transcript_edit_estimate
#project_idstringAlwaysIdentifier of the parent project.
#generation_idstringAlwaysIdentifier of the Pro generation being checked.
#edit_countinteger | nullAlwaysNumber 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_windowsinteger | nullAlwaysUpper bound on 30-second windows the edit could restore, or null.
#window_secondsintegerAlwaysBillable seconds per restored window (30).
#max_billable_secondsintegerAlwaysMaximum 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.

Successful response
{
  "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 words or invalid tighten
    • Oversized header
    invalid_jsoninvalid_fieldinvalid_header
  • 403Forbidden: the key lacks permission.Key is inactive or lacks generations:write. permission_denied
  • 404Not found.Project not found, or generation not found. project_not_foundgeneration_not_found
  • 409Conflict: 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 tighten was requested on video
    not_readynot_availablenot_editable
  • 502Bad gateway.Upstream edit estimator error. internal_error
  • 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

  • Estimating is free and skips credit checks, so you can preview max_billable_seconds in 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 (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").

Report an issue with this page