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

  1. Person → Your app: "Remove the filler words"
  2. Your app → Diffio API: POST …/assistant/turns, messages; 202 processing
  3. Your app → Diffio API: GET …/assistant/turns/{id}, until complete
  4. Diffio API → Your app: reply, proposals, moments
  5. Your app → Diffio API: POST …/edits/estimate, once per proposal
  6. Your app → Person: proposals and estimates
  7. Person → Your app: accept p1
  8. Your app → Diffio API: POST …/edits, the accepted words
  9. Your app → Diffio API: POST …/assistant/feedback, optional, over HTTP
Proposals change nothing until your app creates an edit with the words the person accepted.

Build it

  1. 1

    Ask a turn

    Send the chat so far in messages (1 to 40 {role, content}, the question last). Leave words out to ask about the stored transcript, or send your editor's words as they stand. It works on finished diffio-pro results and answers 202Accepted: the work continues in the background. with status: "processing".

  2. 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 failed with assistant_timeout; the transcript_assistant_turn.completed webhook also tells you.

  3. 3

    Show the reply, proposals and moments

    reply is for the person. Each proposal has a title and changes (kind, word_ids, before, after); moments are times to jump to. Nothing changes the audio yet.

  4. 4

    Estimate each, apply the one the person accepts

    Accepting a change gives its first word the after text (whitespace collapsed) and removes the rest (regenerate flags 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. 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.

What you get

Limits, per end user (or per account without Diffio-End-User)
LimitValue
Turns30 per 10 minutes, plus a daily usage cap; over either, the turn ends failed with rate_limited
A turn's runfailed with assistant_timeout after 600 seconds
messages1 to 40, the question last
reply, momentsup to 1,200 characters; up to 8 moments
Feedback10 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
Terminal
$ 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.mp3

API 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.

Report an issue with this page