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/api-reference/create-transcript-assistant-turn.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

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 for the reply and structured edit proposals.
POST https:/
- 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
Headers
| Field | Type | Required | Description |
|---|---|---|---|
#Diffio-End-User | string | Required: 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 | Required: Yes | Conversation history from 1 to 40 messages; the final item must be a non-empty user message. |
#messages[] | string | Required: Yes | Speaker of the message (user or assistant).userassistant |
#messages[] | string | Required: Yes | Message text (up to 4000 characters). |
#words | array | Required: 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 |
#selection | object | null | Required: No | Optional user word selection context, or null. |
#selection. | array | Required: Yes | Array of selected words[].id strings. |
#playhead_seconds | number | null | Required: No | Optional current playback position in seconds (>= 0), or null. |
#source | string | Required: No | Optional analytics label naming what triggered the turn (for example "typed" or "starter:fillers"). |
words[] 10 fields
| Field | Type | Required | Description |
|---|---|---|---|
#words[] | string | Required: Yes | Unique word identifier (up to 128 characters) from GET .../transcript. |
#words[] | string | Required: No | Word text (up to 2,000 characters); pass "" for a removed word. |
#words[] | number | null | Required: No | Start time in seconds on the recording for a kept word; omit or pass null for newly inserted words. |
#words[] | number | null | Required: No | End time in seconds on the recording for a kept word (>= start); omit or pass null for newly inserted words. |
#words[] | number | null | Required: No | Transcriber confidence from 0 to 1, or null; ignored by edits so GET .../transcript words pass back unchanged. |
#words[] | string | Required: No | Optional speaker label from the transcript; ignored by edits. |
#words[] | string | Required: No | Optional language code for the word. |
#words[] | string | Required: No | Alternate field name for word text; text takes precedence when both are present. |
#words[] | boolean | Required: No | Set true when the word's text was edited so it is re-synthesized (start and end are ignored). |
#words[] | boolean | Required: No | Set true to re-synthesize the word with its existing text (start and end are ignored). |
Request
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",
)Billed calls are not offered here; send this one from your code.
Response
Returns 202 Accepted with the newly created transcript_assistant_turn in status: "processing".
Success: 202Accepted: the work continues in the background.
Response fields
| Field | Type | Present | Description |
|---|---|---|---|
#object | string | Always | Resource type, always "transcript_assistant_turn".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.processingcompletefailed |
#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. |
Show all 23 fields (15 more)
| Field | Type | Present | Description |
|---|---|---|---|
#error. | 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. | 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 |
#moments | array | Sometimes | Notable timestamps referenced in the answer (up to 8 items, present when status is complete).Fields below |
#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[] | string | Sometimes | First word ID of the speaker turn. |
#speaker_turns[] | string | Sometimes | Speaker label for the turn. |
#shortening | object | null | Sometimes | Suggested tighten settings for audio projects, or null.Fields below |
#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. |
#feedback_offer. | string | Sometimes | Feedback category (bug, feature, or other).bugfeatureother |
#feedback_offer. | 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[] 13 fields
| Field | Type | Present | Description |
|---|---|---|---|
#proposals[] | string | Sometimes | Identifier of the proposal. |
#proposals[] | string | Sometimes | Short title summarizing the proposed edits. |
#proposals[] | string | Sometimes | Category icon identifier for the proposal.fillerreplacerephrasemuteregenerategrammarcleanupinsert |
#proposals[] | array | Sometimes | Ordered word-level changes in this proposal. |
#proposals[] | string | Sometimes | Identifier of the change. |
#proposals[] | string | Sometimes | Change action: replace, remove, insert, or regenerate.replaceremoveinsertregenerate |
#proposals[] | array | Sometimes | Ordered words[].id values covered by this change. |
#proposals[] | string | Sometimes | Original words before the change. |
#proposals[] | string | Sometimes | Words after the change, or "" when removing words. |
#proposals[] | string | Sometimes | Short reason explaining the change. |
#proposals[] | number | null | Sometimes | Start timestamp in seconds on the recording, or null. |
#proposals[] | number | null | Sometimes | End timestamp in seconds on the recording, or null. |
#proposals[] | integer | Sometimes | Additional 30-second restore windows this proposal adds to an edit. |
moments[] 4 fields
| Field | Type | Present | Description |
|---|---|---|---|
#moments[] | number | Sometimes | Moment start time in seconds. |
#moments[] | number | null | Sometimes | Moment end time in seconds, or null. |
#moments[] | string | Sometimes | Short label describing the moment. |
#moments[] | string | null | Sometimes | Associated words[].id, or null. |
shortening 4 fields
| Field | Type | Present | Description |
|---|---|---|---|
#shortening. | boolean | Sometimes | Whether to close silence left by removed words. |
#shortening. | number | null | Sometimes | Suggested maximum pause length in seconds, or null. |
#shortening. | number | Sometimes | Estimated seconds saved by applying the shortening. |
#shortening. | string | Sometimes | Explanation for the shortening suggestion. |
Response 202Accepted: the work continues in the background.
{
"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
202Accepted: the work continues in the background.Turn accepted and running (status: "processing").400Bad request.Malformed JSON, or 6 more causes
- Malformed JSON
- Missing
messages - Invalid
messages wordsselectionplayhead_seconds- Oversized header
invalid_jsonmissing_fieldinvalid_fieldinvalid_header403Forbidden: the key lacks permission.Key is inactive or lacksgenerations:write.permission_denied404Not found.Project not found, or generation not found.project_not_foundgeneration_not_found409Conflict: see error.code for which one.Generation or transcript is still running, or 2 more causes
- Generation or transcript is still running
- Generation or transcript failed
- Generation is not a finished editable Pro result
not_readynot_availablenot_editable422Unprocessable request.wordswas omitted and the stored transcript cannot be parsed.transcript_unreadable401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint401Unauthorized: the API key is missing or invalid. Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).405Client error. 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 401Unauthorized: the API key is missing or invalid.:
{
"error": {
"code": "invalid_api_key",
"message": "Invalid API key.",
"request_id": "dead773b60e148fd9e22d680a22fa701"
}
}Notes
- Assistant proposals never modify audio by themselves; apply accepted
proposals[].changesto yourwordsarray and submit Edit a generation's transcript. - Poll Get an edit assistant turn every 1 to 2 seconds (
client.assistant.wait_turn(...)/client.assistant.waitTurn(...)), or subscribe totranscript_assistant_turn.completedandtranscript_assistant_turn.failedwebhooks. - 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 endsfailedwitherror.coderate_limited.