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

FieldTypeRequiredDescription
#project_idstringRequired: YesUnique identifier of the project.
#generation_idstringRequired: YesUnique identifier of the generation within the project.

Headers

FieldTypeRequiredDescription
#Diffio-End-UserstringRequired: NoOptional 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

FieldTypeRequiredDescription
#messagesarrayRequired: YesConversation history from 1 to 40 messages; the final item must be a non-empty user message.
#messages[].rolestringRequired: YesSpeaker of the message (user or assistant).userassistant
#messages[].contentstringRequired: YesMessage text (up to 4000 characters).
#wordsarrayRequired: NoCurrent 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
#selectionobject | nullRequired: NoOptional user word selection context, or null.
#selection.word_idsarrayRequired: YesArray of selected words[].id strings.
#playhead_secondsnumber | nullRequired: NoOptional current playback position in seconds (>= 0), or null.
#sourcestringRequired: NoOptional analytics label naming what triggered the turn (for example "typed" or "starter:fillers").
words[] 10 fields
FieldTypeRequiredDescription
#words[].idstringRequired: YesUnique word identifier (up to 128 characters) from GET .../transcript.
#words[].textstringRequired: NoWord text (up to 2,000 characters); pass "" for a removed word.
#words[].startnumber | nullRequired: NoStart time in seconds on the recording for a kept word; omit or pass null for newly inserted words.
#words[].endnumber | nullRequired: NoEnd time in seconds on the recording for a kept word (>= start); omit or pass null for newly inserted words.
#words[].probabilitynumber | nullRequired: NoTranscriber confidence from 0 to 1, or null; ignored by edits so GET .../transcript words pass back unchanged.
#words[].speakerstringRequired: NoOptional speaker label from the transcript; ignored by edits.
#words[].languagestringRequired: NoOptional language code for the word.
#words[].wordstringRequired: NoAlternate field name for word text; text takes precedence when both are present.
#words[].changedbooleanRequired: NoSet true when the word's text was edited so it is re-synthesized (start and end are ignored).
#words[].regeneratebooleanRequired: NoSet 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

FieldTypePresentDescription
#objectstringAlwaysResource type, always "transcript_assistant_turn".transcript_assistant_turn
#idstringAlwaysUnique identifier of the assistant turn.
#project_idstringAlwaysIdentifier of the parent project.
#generation_idstringAlwaysIdentifier of the Pro generation.
#statusstringAlwaysTurn state: processing while running, complete when answer fields are populated, or failed when error is set.processingcompletefailed
#created_atstring | nullAlwaysISO 8601 UTC timestamp when the turn was created, or null.
#completed_atstring | nullAlwaysISO 8601 UTC timestamp when the turn finished, or null while processing.
#errorobject | nullAlwaysFailure details when status is failed, or null otherwise.
Show all 23 fields (15 more)
FieldTypePresentDescription
#error.codestringAlwaysStable 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.messagestringAlwaysHuman-readable message explaining why the turn failed.
#replystringSometimesAssistant reply text to show the user (present when status is complete, up to 1,200 characters).
#proposalsarraySometimesProposed transcript edit groups referencing words[].id (present when status is complete).Fields below
#momentsarraySometimesNotable timestamps referenced in the answer (up to 8 items, present when status is complete).Fields below
#unclear_word_idsarraySometimesWord IDs that an audio listening pass found hard to understand.
#speaker_turnsarraySometimesDetected speaker turn starts keyed by word_id.
#speaker_turns[].word_idstringSometimesFirst word ID of the speaker turn.
#speaker_turns[].speakerstringSometimesSpeaker label for the turn.
#shorteningobject | nullSometimesSuggested tighten settings for audio projects, or null.Fields below
#feedback_offerobject | nullSometimesOptional prompt inviting user feedback when the assistant detects a product report, or null; send the report with Send assistant feedback.
#feedback_offer.kindstringSometimesFeedback category (bug, feature, or other).bugfeatureother
#feedback_offer.summarystringSometimesSuggested one-line summary for the feedback report.
#noticesarraySometimesInformational notices returned alongside the answer.
#windows_totalintegerSometimesTotal 30-second windows that the current draft plus all proposals would restore.
proposals[] 13 fields
FieldTypePresentDescription
#proposals[].idstringSometimesIdentifier of the proposal.
#proposals[].titlestringSometimesShort title summarizing the proposed edits.
#proposals[].iconstringSometimesCategory icon identifier for the proposal.fillerreplacerephrasemuteregenerategrammarcleanupinsert
#proposals[].changesarraySometimesOrdered word-level changes in this proposal.
#proposals[].changes[].idstringSometimesIdentifier of the change.
#proposals[].changes[].kindstringSometimesChange action: replace, remove, insert, or regenerate.replaceremoveinsertregenerate
#proposals[].changes[].word_idsarraySometimesOrdered words[].id values covered by this change.
#proposals[].changes[].beforestringSometimesOriginal words before the change.
#proposals[].changes[].afterstringSometimesWords after the change, or "" when removing words.
#proposals[].changes[].reasonstringSometimesShort reason explaining the change.
#proposals[].changes[].start_secondsnumber | nullSometimesStart timestamp in seconds on the recording, or null.
#proposals[].changes[].end_secondsnumber | nullSometimesEnd timestamp in seconds on the recording, or null.
#proposals[].windowsintegerSometimesAdditional 30-second restore windows this proposal adds to an edit.
moments[] 4 fields
FieldTypePresentDescription
#moments[].start_secondsnumberSometimesMoment start time in seconds.
#moments[].end_secondsnumber | nullSometimesMoment end time in seconds, or null.
#moments[].labelstringSometimesShort label describing the moment.
#moments[].word_idstring | nullSometimesAssociated words[].id, or null.
shortening 4 fields
FieldTypePresentDescription
#shortening.close_removed_gapsbooleanSometimesWhether to close silence left by removed words.
#shortening.max_pause_secondsnumber | nullSometimesSuggested maximum pause length in seconds, or null.
#shortening.estimated_secondsnumberSometimesEstimated seconds saved by applying the shortening.
#shortening.reasonstringSometimesExplanation for the shortening suggestion.

Response 202Accepted: the work continues in the background.

Successful response
{
  "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
    • words
    • selection
    • playhead_seconds
    • Oversized header
    invalid_jsonmissing_fieldinvalid_fieldinvalid_header
  • 403Forbidden: the key lacks permission.Key is inactive or lacks generations:write. permission_denied
  • 404Not found.Project not found, or generation not found. project_not_foundgeneration_not_found
  • 409Conflict: 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_editable
  • 422Unprocessable request.words was omitted and the stored transcript cannot be parsed. transcript_unreadable
  • 401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint
    • 401Unauthorized: 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 response
{
  "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.
  • Poll Get an edit 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.

Report an issue with this page