> For the complete documentation index, see [llms.txt](https://diffio.ai/llms.txt). This page is also available as HTML at https://diffio.ai/docs/developers/guides/edit-by-asking/.

# 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. 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 `202` with `status: "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 `failed` with `assistant_timeout`; the `transcript_assistant_turn.completed` webhook also tells you.

### 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. 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](https://diffio.ai/docs/developers/guides/edit-transcript/) 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.

**assistant.py**

```python
"""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())
```

**assistant.mjs**

```javascript
// Ask the edit assistant about a Pro result, preview its proposals, and apply the one you name.
// node assistant.mjs PROJECT_ID GENERATION_ID "Remove the filler words"         # ask and preview
// node assistant.mjs 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 { parseArgs } from "node:util";
import { DiffioClient, DiffioResourceFailedError } from "diffio";

const { values: args, positionals } = parseArgs({
  allowPositionals: true,
  options: { turn: { type: "string" }, apply: { type: "string" }, feedback: { type: "string" } }
});
const [projectId, generationId, question] = positionals;
if (!question && !args.turn) throw new Error("Ask a question, or pass --turn");
const client = new DiffioClient(); // reads DIFFIO_API_KEY

// 1. Ask (or read an earlier turn), then poll for at most 10 minutes.
const turnId = args.turn ?? (await client.assistant.createTurn(projectId, generationId, {
  messages: [{ role: "user", content: question }]
})).id;
let turn;
try {
  turn = await client.assistant.waitTurn(projectId, generationId, turnId, { timeout: 600 });
} catch (error) {
  if (error instanceof DiffioResourceFailedError) throw new Error(`The assistant could not answer: ${error.code}: ${error.message}`);
  throw error;
}

// 2. A proposal accepted: the first word of a change takes "after", the rest are removed.
const transcriptWords = (await client.transcripts.get(projectId, generationId)).words;
function accepted(proposal) {
  const words = new Map(transcriptWords.map((word) => [word.id, { ...word }])); // a fresh copy, in order
  for (const change of proposal.changes) {
    if (change.kind === "regenerate") {
      for (const id of change.word_ids) words.get(id).regenerate = true;
      continue;
    }
    const [first, ...rest] = change.word_ids;
    const after = change.after.trim().split(/\s+/).filter(Boolean).join(" "); // whitespace as the server reads it
    Object.assign(words.get(first), { text: after, changed: true });
    for (const id of rest) Object.assign(words.get(id), { text: "", changed: true });
  }
  return [...words.values()];
}

// 3. Preview: what the person sees, and what each proposal would bill at most.
console.log("turn", turn.id);
console.log("reply:", turn.reply);
for (const moment of turn.moments ?? []) console.log(`moment ${moment.start_seconds.toFixed(1)}s: ${moment.label}`);
for (const proposal of turn.proposals ?? []) {
  const estimate = await client.edits.estimate(projectId, generationId, { words: accepted(proposal) });
  console.log(`proposal ${proposal.id}: ${proposal.title} (at most ${estimate.max_billable_seconds} billable seconds)`);
  for (const change of proposal.changes) console.log(`  ${change.kind}: "${change.before}" -> "${change.after}"`);
}

// 4. Apply only the proposal the person accepted.
if (args.apply) {
  const proposal = (turn.proposals ?? []).find((item) => item.id === args.apply);
  if (!proposal) throw new Error(`Turn ${turn.id} has no proposal ${args.apply}`);
  const edit = await client.edits.create(projectId, generationId, { words: accepted(proposal) }, {
    idempotencyKey: `assistant-${turn.id}-${proposal.id}`
  });
  const finished = await client.generations.wait(projectId, edit.id, { timeout: 1800 });
  await client.generations.download(projectId, finished.id, { path: "interview-assistant.mp3" });
  console.log(`applied ${proposal.id}: saved interview-assistant.mp3`);
} else if (turn.proposals?.length) {
  console.log(`to apply one: node assistant.mjs ${projectId} ${generationId} --turn ${turn.id} --apply <proposal id>`);
}

// 5. Feedback has no SDK helper yet: POST it over HTTP.
if (args.feedback) {
  const response = await fetch(`${await client.baseUrl()}/projects/${projectId}/generations/${generationId}/transcript/assistant/feedback`, {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.DIFFIO_API_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ kind: "other", message: args.feedback, turn_id: turn.id }),
    signal: AbortSignal.timeout(30_000)
  });
  console.log("feedback:", response.status, await 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`**

**Terminal**

```bash
$ 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

- POST [Ask the edit assistant](https://diffio.ai/docs/api-reference/create-transcript-assistant-turn/) (`/projects/{project_id}/generations/{generation_id}/transcript/assistant/turns`): Ask; refusals and turn error codes.
- GET [Get an edit assistant turn](https://diffio.ai/docs/api-reference/get-transcript-assistant-turn/) (`/projects/{project_id}/generations/{generation_id}/transcript/assistant/turns/{turn_id}`): reply, proposals, moments and the rest.
- POST [Estimate a transcript edit](https://diffio.ai/docs/api-reference/estimate-transcript-edit/) (`/projects/{project_id}/generations/{generation_id}/edits/estimate`): The most the edit can bill.
- POST [Edit a generation's transcript](https://diffio.ai/docs/api-reference/create-transcript-edit/) (`/projects/{project_id}/generations/{generation_id}/edits`): Restore the accepted changes.
- POST [Send assistant feedback](https://diffio.ai/docs/api-reference/create-transcript-assistant-feedback/) (`/projects/{project_id}/generations/{generation_id}/transcript/assistant/feedback`): Report a bug or an idea.

## Related pages

- Previous: [Edit a transcript](https://diffio.ai/docs/developers/guides/edit-transcript/): Transcript → estimate → edit
- Next: [Separate speech and background](https://diffio.ai/docs/developers/guides/separate-speech-and-background/): Stems → mix → export
