> 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/api-reference/create-transcript-assistant-turn/.

# Ask the edit assistant

Starts an asynchronous edit-assistant chat turn on a finished Pro generation's transcript (`202 Accepted`, `status: "processing"`). Poll [Get an edit assistant turn](https://diffio.ai/docs/api-reference/get-transcript-assistant-turn/) for the reply and structured edit `proposals`.

POST `https://api.diffio.ai/v2/projects/{project_id}/generations/{generation_id}/transcript/assistant/turns`

- Key scope: `generations:write`
- Auth header: `Authorization: Bearer <apiKey>`
- Body: JSON

## Request

Send `messages` (chat history ending with the user's question) and optional editor `words`, `selection`, `playhead_seconds`, or `source`.

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | string | Yes | Unique identifier of the project. |
| `generation_id` | string | Yes | Unique identifier of the generation within the project. |

### Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `Diffio-End-User` | string | No | Optional 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `messages` | array | Yes | Conversation history from `1` to `40` messages; the final item must be a non-empty `user` message. |
| `messages[].role` | string | Yes | Speaker of the message (`user` or `assistant`). |
| `messages[].content` | string | Yes | Message text (up to `4000` characters). |
| `words` | array | No | Current editor words in order (`1` to `60,000` words, up to `600,000` characters of text). Omit to ask about the stored transcript from `GET .../transcript`. [Fields below](#fields-words) |
| `selection` | object \| null | No | Optional user word selection context, or `null`. |
| `selection.word_ids` | array | Yes | Array of selected `words[].id` strings. |
| `playhead_seconds` | number \| null | No | Optional current playback position in seconds (`>= 0`), or `null`. |
| `source` | string | No | Optional analytics label naming what triggered the turn (for example `"typed"` or `"starter:fillers"`). |

**`words[]` fields**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `words[].id` | string | Yes | Unique word identifier (up to 128 characters) from `GET .../transcript`. |
| `words[].text` | string | No | Word text (up to 2,000 characters); pass `""` for a removed word. |
| `words[].start` | number \| null | No | Start time in seconds on the recording for a kept word; omit or pass `null` for newly inserted words. |
| `words[].end` | number \| null | No | End time in seconds on the recording for a kept word (`>=` `start`); omit or pass `null` for newly inserted words. |
| `words[].probability` | number \| null | No | Transcriber confidence from `0` to `1`, or `null`; ignored by edits so `GET .../transcript` words pass back unchanged. |
| `words[].speaker` | string | No | Optional speaker label from the transcript; ignored by edits. |
| `words[].language` | string | No | Optional language code for the word. |
| `words[].word` | string | No | Alternate field name for word text; `text` takes precedence when both are present. |
| `words[].changed` | boolean | No | Set `true` when the word's text was edited so it is re-synthesized (`start` and `end` are ignored). |
| `words[].regenerate` | boolean | No | Set `true` to re-synthesize the word with its existing text (`start` and `end` are ignored). |

## Example request

**Python**

```python
import os
from diffio import DiffioClient

key = os.environ["DIFFIO_API_KEY"]
client = DiffioClient(api_key=key)

turn = client.assistant.create_turn(
    "73118d99-36cf-4039-8005-b962d522fff7",
    "73c84c4a-c1ca-5485-b396-171ab632d4b7",
    messages=[
        {
            "role": "user",
            "content": "Remove the filler words.",
        },
    ],
    source="typed",
)
```

**Node.js**

```javascript
import { DiffioClient } from "diffio"

const client = new DiffioClient({
  apiKey: process.env.DIFFIO_API_KEY,
})

const turn =
  await client.assistant.createTurn(
    "73118d99-36cf-4039-8005-b962d522fff7",
    "73c84c4a-c1ca-5485-b396-171ab632d4b7",
    {
      messages: [
        {
          role: "user",
          content: "Remove the filler words.",
        },
      ],
      source: "typed",
    },
  )
```

**cURL**

```bash
curl -X POST "https://api.diffio.ai/v2/projects/73118d99-36cf-4039-8005-b962d522fff7/generations/73c84c4a-c1ca-5485-b396-171ab632d4b7/transcript/assistant/turns" \
  -H "Authorization: Bearer $DIFFIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Remove the filler words."
      }
    ],
    "source": "typed"
  }'
```

**JSON: JSON body**

```json
{
  "messages": [
    {
      "role": "user",
      "content": "Remove the filler words."
    }
  ],
  "source": "typed"
}
```

## Response

Returns `202 Accepted` with the newly created `transcript_assistant_turn` in `status: "processing"`.

Success: `202`

### Response fields

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `object` | string | Always | Resource type, always `"transcript_assistant_turn"`. |
| `id` | string | Always | Unique identifier of the assistant turn. |
| `project_id` | string | Always | Identifier of the parent project. |
| `generation_id` | string | Always | Identifier of the Pro generation. |
| `status` | string | Always | Turn state: `processing` while running, `complete` when answer fields are populated, or `failed` when `error` is set. |
| `created_at` | string \| null | Always | ISO 8601 UTC timestamp when the turn was created, or `null`. |
| `completed_at` | string \| null | Always | ISO 8601 UTC timestamp when the turn finished, or `null` while `processing`. |
| `error` | object \| null | Always | Failure details when `status` is `failed`, or `null` otherwise. |
| `error.code` | string | Always | Stable `snake_case` turn failure code (`rate_limited`, `assistant_timeout`, `assistant_unavailable`, `not_editable`, `invalid_field`, `permission_denied`, `unauthenticated`, `project_not_found`, or `internal_error`). |
| `error.message` | string | Always | Human-readable message explaining why the turn failed. |
| `reply` | string | Sometimes | Assistant reply text to show the user (present when `status` is `complete`, up to 1,200 characters). |
| `proposals` | array | Sometimes | Proposed transcript edit groups referencing `words[].id` (present when `status` is `complete`). [Fields below](#fields-proposals) |
| `moments` | array | Sometimes | Notable timestamps referenced in the answer (up to 8 items, present when `status` is `complete`). [Fields below](#fields-moments) |
| `unclear_word_ids` | array | Sometimes | Word IDs that an audio listening pass found hard to understand. |
| `speaker_turns` | array | Sometimes | Detected speaker turn starts keyed by `word_id`. |
| `speaker_turns[].word_id` | string | Sometimes | First word ID of the speaker turn. |
| `speaker_turns[].speaker` | string | Sometimes | Speaker label for the turn. |
| `shortening` | object \| null | Sometimes | Suggested `tighten` settings for audio projects, or `null`. [Fields below](#fields-shortening) |
| `feedback_offer` | object \| null | Sometimes | Optional prompt inviting user feedback when the assistant detects a product report, or `null`; send the report with [Send assistant feedback](https://diffio.ai/docs/api-reference/create-transcript-assistant-feedback/). |
| `feedback_offer.kind` | string | Sometimes | Feedback category (`bug`, `feature`, or `other`). |
| `feedback_offer.summary` | string | Sometimes | Suggested one-line summary for the feedback report. |
| `notices` | array | Sometimes | Informational notices returned alongside the answer. |
| `windows_total` | integer | Sometimes | Total 30-second windows that the current draft plus all proposals would restore. |

**`proposals[]` fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `proposals[].id` | string | Sometimes | Identifier of the proposal. |
| `proposals[].title` | string | Sometimes | Short title summarizing the proposed edits. |
| `proposals[].icon` | string | Sometimes | Category icon identifier for the proposal. Values: `filler`, `replace`, `rephrase`, `mute`, `regenerate`, `grammar`, `cleanup`, `insert`. |
| `proposals[].changes` | array | Sometimes | Ordered word-level changes in this proposal. |
| `proposals[].changes[].id` | string | Sometimes | Identifier of the change. |
| `proposals[].changes[].kind` | string | Sometimes | Change action: `replace`, `remove`, `insert`, or `regenerate`. |
| `proposals[].changes[].word_ids` | array | Sometimes | Ordered `words[].id` values covered by this change. |
| `proposals[].changes[].before` | string | Sometimes | Original words before the change. |
| `proposals[].changes[].after` | string | Sometimes | Words after the change, or `""` when removing words. |
| `proposals[].changes[].reason` | string | Sometimes | Short reason explaining the change. |
| `proposals[].changes[].start_seconds` | number \| null | Sometimes | Start timestamp in seconds on the recording, or `null`. |
| `proposals[].changes[].end_seconds` | number \| null | Sometimes | End timestamp in seconds on the recording, or `null`. |
| `proposals[].windows` | integer | Sometimes | Additional 30-second restore windows this proposal adds to an edit. |

**`moments[]` fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `moments[].start_seconds` | number | Sometimes | Moment start time in seconds. |
| `moments[].end_seconds` | number \| null | Sometimes | Moment end time in seconds, or `null`. |
| `moments[].label` | string | Sometimes | Short label describing the moment. |
| `moments[].word_id` | string \| null | Sometimes | Associated `words[].id`, or `null`. |

**`shortening` fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `shortening.close_removed_gaps` | boolean | Sometimes | Whether to close silence left by removed words. |
| `shortening.max_pause_seconds` | number \| null | Sometimes | Suggested maximum pause length in seconds, or `null`. |
| `shortening.estimated_seconds` | number | Sometimes | Estimated seconds saved by applying the shortening. |
| `shortening.reason` | string | Sometimes | Explanation for the shortening suggestion. |

## Example response (202)

**Successful response**

```json
{
  "object": "transcript_assistant_turn",
  "id": "8f14e45fceea4e6b9d2c7a1b3e5d9f02",
  "project_id": "73118d99-36cf-4039-8005-b962d522fff7",
  "generation_id": "73c84c4a-c1ca-5485-b396-171ab632d4b7",
  "status": "processing",
  "created_at": "2026-11-13T00:40:00.418207Z",
  "completed_at": null,
  "error": null
}
```

## Return codes

- `202` Turn accepted and running (`status: "processing"`).
- `400`
  - Malformed JSON
  - Missing `messages`
  - Invalid `messages`
  - `words`
  - `selection`
  - `playhead_seconds`
  - Oversized header
  Codes: [`invalid_json`](https://diffio.ai/docs/api-reference/errors/#invalid_json), [`missing_field`](https://diffio.ai/docs/api-reference/errors/#missing_field), [`invalid_field`](https://diffio.ai/docs/api-reference/errors/#invalid_field), [`invalid_header`](https://diffio.ai/docs/api-reference/errors/#invalid_header)
- `403` Key is inactive or lacks `generations:write`. [`permission_denied`](https://diffio.ai/docs/api-reference/errors/#permission_denied)
- `404` Project not found, or generation not found. [`project_not_found`](https://diffio.ai/docs/api-reference/errors/#project_not_found) [`generation_not_found`](https://diffio.ai/docs/api-reference/errors/#generation_not_found)
- `409`
  - Generation or transcript is still running: [`not_ready`](https://diffio.ai/docs/api-reference/errors/#not_ready)
  - Generation or transcript failed: [`not_available`](https://diffio.ai/docs/api-reference/errors/#not_available)
  - Generation is not a finished editable Pro result: [`not_editable`](https://diffio.ai/docs/api-reference/errors/#not_editable)
- `422` `words` was omitted and the stored transcript cannot be parsed. [`transcript_unreadable`](https://diffio.ai/docs/api-reference/errors/#transcript_unreadable)
- **`401` `405` Same on every endpoint**

  - `401` Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).
  - `405` 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 `401`:

**Error response**

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "request_id": "dead773b60e148fd9e22d680a22fa701"
  }
}
```

## Notes

- Assistant proposals never modify audio by themselves; apply accepted `proposals[].changes` to your `words` array and submit [Edit a generation's transcript](https://diffio.ai/docs/api-reference/create-transcript-edit/).
- Poll [Get an edit assistant turn](https://diffio.ai/docs/api-reference/get-transcript-assistant-turn/) every 1 to 2 seconds (`client.assistant.wait_turn(...)` / `client.assistant.waitTurn(...)`), or subscribe to `transcript_assistant_turn.completed` and `transcript_assistant_turn.failed` webhooks.
- Assistant turns are not billed per turn and are limited to 30 turns per 10 minutes plus a daily usage cap per end user (or per account without `Diffio-End-User`); a turn over the limit is still created and ends `failed` with `error.code` `rate_limited`.

## Related pages

- Previous: [Delete the transcript draft](https://diffio.ai/docs/api-reference/delete-transcript-draft/): Delete a generation's saved transcript editor draft with optional revision checking.
- Next: [Get an edit assistant turn](https://diffio.ai/docs/api-reference/get-transcript-assistant-turn/): Poll an edit-assistant turn for its reply, word-level edit proposals, moments, or failure details.

- [Full API guide](https://diffio.ai/docs/developers/full-api-guide/): Every topic, limit and concept in one index.
- [Billing](https://diffio.ai/docs/overview/administration/billing/): Starter credit, metering and invoices.
