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

Get a generation's transcript

Returns a generation's word-timed transcript in a normalized TranscriptWord shape, ready to display or pass back to Edit a generation's transcript and Ask the edit assistant.

GET https://api.diffio.ai/v2/projects/{project_id}/generations/{generation_id}/transcript

  • Key scope: generations:read
  • Auth header:Authorization: Bearer <apiKey>
  • Body: None

Request

Pass project_id and generation_id in the path, and optional preview_seconds in the query string.

Path parameters

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

Query parameters

FieldTypeRequiredDescription
#preview_secondsintegerRequired: NoOptional limit in seconds, from 4 to 3600 (rounded up to whole 4-second segments). Keeps only words starting within the preview.

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.

Request

import os
from diffio import DiffioClient

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

transcript = client.transcripts.get(
    "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
    "ce832a32-a1ce-516a-b8bd-75457bd8517f",
)

Response

Returns the normalized transcript with full text and ordered words.

Success: 200OK.

Response fields

FieldTypePresentDescription
#objectstringAlwaysResource type, always "transcript".transcript
#generation_idstringAlwaysIdentifier of the generation.
#textstringAlwaysFull transcript text (or the preview's words joined by spaces when preview_seconds is set).
#wordsarrayAlwaysOrdered array of word-timed TranscriptWord objects.Fields below
#truncatedbooleanAlwaysTrue when words starting at or after preview_seconds were omitted.
words[] 7 fields
FieldTypePresentDescription
#words[].idstringAlwaysStable word identifier within the transcript (stored ID or word-{index}).
#words[].textstringAlwaysTranscribed word text.
#words[].startnumber | nullAlwaysWord start timestamp in seconds on the recording, or null when untimed.
#words[].endnumber | nullAlwaysWord end timestamp in seconds on the recording, or null when untimed.
#words[].probabilitynumber | nullAlwaysTranscriber confidence from 0 to 1, or null when unknown.
#words[].speakerstringSometimesSpeaker label when recorded by the transcriber (omitted on preview_seconds reads).
#words[].languagestringSometimesWord language code when recorded by the transcriber.
Other response fields2 fields
FieldTypePresentDescription
#project_idstringAlwaysIdentifier of the parent project.
#preview_secondsinteger | nullAlwaysEffective preview limit in seconds (rounded up to a multiple of 4), or null for the complete transcript.

Response 200OK.

Return codes

  • 200OK.Returns the normalized word-timed transcript.
  • 400Bad request.preview_seconds is outside 4 to 3600, or Diffio-End-User exceeds 128 characters. invalid_parameterinvalid_header
  • 403Forbidden: the key lacks permission.Key is inactive or lacks generations:read. permission_denied
  • 404Not found.
    Project not found, or 2 more causes
    • Project not found
    • Generation not found
    • Finished generation has no stored transcript
    project_not_foundgeneration_not_foundtranscript_not_found
  • 409Conflict: see error.code for which one.transcription_status is still preparing or the generation is running, or transcription failed; details.transcription_status reports the state. not_readynot_available
  • 422Unprocessable request.Stored transcript file could not 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

  • Both Flash and Pro restores produce a word-timed transcript (transcription_status: "ready"), while only Pro restores support Edit a generation's transcript.
  • Pass the words array directly to POST .../edits, POST .../edits/estimate, or POST .../transcript/assistant/turns with your word-level edits applied.

Report an issue with this page