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

Let users edit by asking
Let people ask for changes in plain words, show the assistant's proposals, and turn the one they accept into an edit.
How it works
- Person → Your app:
"Remove the filler words" - Your app → Diffio API:
POST …/assistant/turns, messages; 202 processing - Your app → Diffio API:
GET …/assistant/turns/{id}, until complete - Diffio API → Your app:
reply, proposals, moments - Your app → Diffio API:
POST …/edits/estimate, once per proposal - Your app → Person:
proposals and estimates - Person → Your app:
accept p1 - Your app → Diffio API:
POST …/edits, the accepted words - Your app → Diffio API:
POST …/assistant/feedback, optional, over HTTP
Build it
- 1
Ask a turn
Send the chat so far in
messages(1 to 40{role, content}, the question last). Leavewordsout to ask about the stored transcript, or send your editor's words as they stand. It works on finisheddiffio-proresults and answers202Accepted: the work continues in the background. withstatus: "processing". - 2
Poll until it answers
Read the turn every second or two; it can take a few minutes, because it may listen to the audio. A turn still running after 600 seconds ends
failedwithassistant_timeout; thetranscript_assistant_turn.completedwebhook also tells you. - 3
Show the reply, proposals and moments
replyis for the person. Each proposal has atitleandchanges(kind,word_ids,before,after);momentsare times to jump to. Nothing changes the audio yet. - 4
Estimate each, apply the one the person accepts
Accepting a change gives its first word the
aftertext (whitespace collapsed) and removes the rest (regenerateflags the words instead), the same rule the assistant uses. The script previews every proposal with its estimate and creates an edit only for the proposal named with--apply. - 5
Send feedback (HTTP)
A report about the assistant goes to Diffio with
POST …/assistant/feedback. The SDKs have no helper for it yet, so the script calls it over HTTP. Up to 10 reports an hour per end user.
The complete script
Ask with a question to preview; apply with --turn and --apply; add --feedback "a note" to either to send feedback.
"""Ask the edit assistant about a Pro result, preview its proposals, and apply the one you name.
python assistant.py PROJECT_ID GENERATION_ID "Remove the filler words" # ask and preview
python assistant.py PROJECT_ID GENERATION_ID --turn TURN_ID --apply p1 # apply proposal p1 of that turn
Add --feedback "a note for the Diffio team" to either.
"""
import argparse
import sys
import httpx
from diffio import AssistantTurnFailedError, DiffioClient
parser = argparse.ArgumentParser()
parser.add_argument("project_id")
parser.add_argument("generation_id")
parser.add_argument("question", nargs="?")
parser.add_argument("--turn", help="an earlier turn to read instead of asking")
parser.add_argument("--apply", metavar="PROPOSAL_ID", help="create the edit for this proposal")
parser.add_argument("--feedback", help="send this note to the Diffio team")
args = parser.parse_args()
if not args.question and not args.turn:
parser.error("ask a question, or pass --turn")
client = DiffioClient() # reads DIFFIO_API_KEY
project_id, generation_id = args.project_id, args.generation_id
# 1. Ask (or read an earlier turn), then poll for at most 10 minutes.
turn_id = args.turn or client.assistant.create_turn(
project_id, generation_id, messages=[{"role": "user", "content": args.question}]).id
try:
turn = client.assistant.wait_turn(project_id, generation_id, turn_id, timeout=600)
except AssistantTurnFailedError as error:
sys.exit(f"the assistant could not answer: {error.message}") # the message ends with (code)
# 2. A proposal accepted: the first word of a change takes "after", the rest are removed.
transcript_words = [word.to_dict() for word in client.transcripts.get(project_id, generation_id).words]
def accepted(proposal):
words = {word["id"]: dict(word) for word in transcript_words} # a fresh copy, in the transcript's order
for change in proposal["changes"]:
if change["kind"] == "regenerate":
for word_id in change["word_ids"]:
words[word_id]["regenerate"] = True
continue
first, *rest = change["word_ids"]
words[first].update(text=" ".join(change["after"].split()), changed=True) # whitespace as the server reads it
for word_id in rest:
words[word_id].update(text="", changed=True)
return list(words.values())
# 3. Preview: what the person sees, and what each proposal would bill at most.
print("turn", turn.id)
print("reply:", turn.reply)
for moment in turn.moments or []:
print(f"moment {moment['start_seconds']:.1f}s: {moment['label']}")
for proposal in turn.proposals or []:
estimate = client.edits.estimate(project_id, generation_id, words=accepted(proposal))
print(f"proposal {proposal['id']}: {proposal['title']} (at most {estimate.max_billable_seconds} billable seconds)")
for change in proposal["changes"]:
print(f" {change['kind']}: {change['before']!r} -> {change['after']!r}")
# 4. Apply only the proposal the person accepted.
if args.apply:
proposal = next((item for item in turn.proposals or [] if item["id"] == args.apply), None)
if proposal is None:
sys.exit(f"turn {turn.id} has no proposal {args.apply}")
edit = client.edits.create(project_id, generation_id, words=accepted(proposal),
idempotency_key=f"assistant-{turn.id}-{proposal['id']}")
finished = client.generations.wait(project_id, edit.id, timeout=1800)
client.generations.download(project_id, finished.id, path="interview-assistant.mp3")
print(f"applied {proposal['id']}: saved interview-assistant.mp3")
elif turn.proposals:
print(f"to apply one: python assistant.py {project_id} {generation_id} --turn {turn.id} --apply <proposal id>")
# 5. Feedback has no SDK helper yet: POST it over HTTP.
if args.feedback:
response = httpx.post(
f"{client.base_url}/projects/{project_id}/generations/{generation_id}/transcript/assistant/feedback",
headers={"Authorization": f"Bearer {client.api_key}"},
json={"kind": "other", "message": args.feedback, "turn_id": turn.id},
timeout=30,
)
print("feedback:", response.status_code, response.json())What you get
| Limit | Value |
|---|---|
| Turns | 30 per 10 minutes, plus a daily usage cap; over either, the turn ends failed with rate_limited |
| A turn's run | failed with assistant_timeout after 600 seconds |
messages | 1 to 40, the question last |
reply, moments | up to 1,200 characters; up to 8 moments |
| Feedback | 10 reports per hour; message up to 4,000 characters |
- The assistant's reply, its proposals and the moments it points to, ready to show in your editor.
- Each proposal's estimate before anything is billed, and the accepted one as an edit:
interview-assistant.mp3.
Output of a preview, then --apply p1
$ python assistant.py 62f62565-... ce832a32-... "Remove the filler words"
turn 8f14e45fceea4e6b9d2c7a1b3e5d9f02
reply: I found two filler words and grouped them into one proposal.
moment 12.4s: "um" before the main point
proposal p1: Remove filler words (at most 30 billable seconds)
remove: 'um' -> ''
remove: 'you know' -> ''
to apply one: python assistant.py 62f62565-... ce832a32-... --turn 8f14e45fceea4e6b9d2c7a1b3e5d9f02 --apply <proposal id>
$ python assistant.py 62f62565-... ce832a32-... --turn 8f14e45fceea4e6b9d2c7a1b3e5d9f02 --apply p1
turn 8f14e45fceea4e6b9d2c7a1b3e5d9f02
reply: I found two filler words and grouped them into one proposal.
moment 12.4s: "um" before the main point
proposal p1: Remove filler words (at most 30 billable seconds)
remove: 'um' -> ''
remove: 'you know' -> ''
applied p1: saved interview-assistant.mp3API reference
- POSTAsk the edit assistant (
/projects/{project_id}/generations/{generation_id}/transcript/assistant/turns): Ask; refusals and turn error codes. - GETGet an edit assistant turn (
/projects/{project_id}/generations/{generation_id}/transcript/assistant/turns/{turn_id}): reply, proposals, moments and the rest. - POSTEstimate a transcript edit (
/projects/{project_id}/generations/{generation_id}/edits/estimate): The most the edit can bill. - POSTEdit a generation's transcript (
/projects/{project_id}/generations/{generation_id}/edits): Restore the accepted changes. - POSTSend assistant feedback (
/projects/{project_id}/generations/{generation_id}/transcript/assistant/feedback): Report a bug or an idea.