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

Edit a transcript and re-render the audio
Change a word in a Pro result's transcript and get back the whole recording with the new word said in the same voice.
How it works
- Your code → Diffio API:
POST /projects, model diffio-pro - Diffio API → Your code:
generation complete, transcript_editable: true - Your code → Diffio API:
GET …/transcript, words with id, text, start, end - Your code:
change words, text, changed: true - Your code → Diffio API:
POST …/edits/estimate, max_billable_seconds - Your code → Diffio API:
POST …/edits, Idempotency-Key - Diffio API → Your code:
generation, kind "edit", complete (or generation.completed) - Your code → Diffio API:
GET …/media, files.audio of the edit
Build it
- 1
Restore with Pro
Only a finished
diffio-proresult can be edited (transcript_editableis true). The transcript can arrive a moment after the audio: wait whiletranscription_statusispreparing, for a bounded time, and show the generation'serrorwhen it fails. - 2
Change the words
Read the transcript and send every word back, in order. Change a word's
textand mark itchanged;text: ""removes a word. - 3
Estimate first
edits.estimatecreates and bills nothing. Each restored window bills 30 seconds;max_billable_secondsis the most this edit can bill. - 4
Create the edit and wait
The edit is a new generation with
kind: "edit"; only the windows around changed words are restored again. A fixedIdempotency-Keymakes a retry return the same edit and bill it once. - 5
Download the edited recording
The edit's media is the whole recording with the new words in it.
The complete script
Put interview.mp3 next to it and name the word to replace and its replacement.
"""Restore interview.mp3 with Pro, replace one word in its transcript, and save the re-rendered audio.
python edit.py Tuesday Thursday
"""
import sys
import time
from diffio import DiffioClient, DiffioTimeoutError, GenerationFailedError
old_word, new_word = sys.argv[1], sys.argv[2]
client = DiffioClient() # reads DIFFIO_API_KEY
# 1. A finished Pro result, and its transcript (bounded waits).
try:
result = client.restore_audio("interview.mp3", model="diffio-pro", output_path="interview-restored.mp3",
timeout=1800)
except (GenerationFailedError, DiffioTimeoutError) as error:
sys.exit(f"restore did not finish: {error}")
project_id, generation = result.project.id, result.generation
deadline = time.monotonic() + 300
while generation.transcription_status == "preparing" and time.monotonic() < deadline:
time.sleep(2)
generation = client.generations.get(project_id, generation.id)
if generation.transcription_status != "ready" or not generation.transcript_editable:
sys.exit(f"{generation.id} cannot be edited (transcription_status {generation.transcription_status}, "
f"error {generation.error.to_dict() if generation.error else None})")
# 2. Every word goes back; only the replaced ones change.
transcript = client.transcripts.get(project_id, generation.id)
words = [word.to_dict() for word in transcript.words]
changed = 0
for word in words:
core = word["text"].strip().rstrip(".,?!")
if core.lower() == old_word.lower():
word["text"] = word["text"].replace(core, new_word)
word["changed"] = True # said again in the same voice
changed += 1
if not changed:
sys.exit(f'"{old_word}" is not in the transcript')
# 3. The most it can bill, before anything runs.
estimate = client.edits.estimate(project_id, generation.id, words=words)
print(f"{estimate.edit_count} change(s), at most {estimate.max_billable_seconds} billable seconds")
# 4. The edit is a new generation; the same key never creates or bills it twice.
edit = client.edits.create(project_id, generation.id, words=words, idempotency_key=f"edit-{generation.id}")
try:
finished = client.generations.wait(project_id, edit.id, timeout=1800)
except GenerationFailedError as error:
sys.exit(f"edit failed: {error.message}") # the message ends with (code)
except DiffioTimeoutError:
sys.exit(f"edit {edit.id} still running after 30 minutes")
# 5. The whole recording with the new word.
saved = client.generations.download(project_id, finished.id, path="interview-edited.mp3")
print("saved", saved, "from generation", finished.id, "kind", finished.kind)What you get
on the ground of scientific historical (changed: true) evidence, or in the end on the ground of any evidence whatever.
changed. Only the window around it is restored again. interview-restored.mp3: the Pro restore.interview-edited.mp3: the same recording with the word replaced, from a generation ofkindedit.
Output of python edit.py Tuesday Thursday
1 change(s), at most 30 billable seconds
saved interview-edited.mp3 from generation 9d1f4c2a-5b7e-5c3d-8a6f-2e4b1c0d9f87 kind editAPI reference
- GETGet a generation's transcript (
/projects/{project_id}/generations/{generation_id}/transcript): Words with ids and timings. - POSTEstimate a transcript edit (
/projects/{project_id}/generations/{generation_id}/edits/estimate): The most an edit can bill. - POSTEdit a generation's transcript (
/projects/{project_id}/generations/{generation_id}/edits): Word fields, refusals and billing. - GETGet a generation (
/projects/{project_id}/generations/{generation_id}): Status and progress of the edit. - GETGet a playback grant (
/projects/{project_id}/generations/{generation_id}/media): The edited files.