{"openapi": "3.1.0", "info": {"title": "Diffio API", "version": "2.0.0", "description": "Restore speech in audio and video. Create a project, upload the recording, create a generation with the model you want, then read its files."}, "servers": [{"url": "https://api.diffio.ai/v2"}], "paths": {"/models": {"get": {"operationId": "listModels", "summary": "List models", "tags": ["Models"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ModelList"}, "example": {"object": "list", "data": [{"id": "diffio-4.7-flash", "object": "model", "status": "hosted", "label": "Diffio 4.7 Flash", "served_by": "diffio-4.7-flash", "price_per_hour_usd": 5}, {"id": "diffio-4.7-pro", "object": "model", "status": "hosted", "label": "Diffio 4.7 Pro", "served_by": "diffio-4.7-pro", "price_per_hour_usd": 10}, {"id": "diffio-flash", "object": "model", "status": "alias", "label": "Diffio 4.7 Flash", "served_by": "diffio-4.7-flash", "price_per_hour_usd": 5}, {"id": "diffio-pro", "object": "model", "status": "alias", "label": "Diffio 4.7 Pro", "served_by": "diffio-4.7-pro", "price_per_hour_usd": 10}, {"id": "diffio-2", "object": "model", "status": "retired", "label": null, "served_by": "diffio-4.7-flash", "price_per_hour_usd": 5}, {"id": "diffio-2-flash", "object": "model", "status": "retired", "label": null, "served_by": "diffio-4.7-flash", "price_per_hour_usd": 5}, {"id": "diffio-2.0", "object": "model", "status": "retired", "label": null, "served_by": "diffio-4.7-flash", "price_per_hour_usd": 5}, {"id": "diffio-2.0-flash", "object": "model", "status": "retired", "label": null, "served_by": "diffio-4.7-flash", "price_per_hour_usd": 5}, {"id": "diffio-3.0", "object": "model", "status": "retired", "label": null, "served_by": "diffio-4.7-pro", "price_per_hour_usd": 10}, {"id": "diffio-3.2", "object": "model", "status": "retired", "label": null, "served_by": "diffio-4.7-pro", "price_per_hour_usd": 10}, {"id": "diffio-3.4", "object": "model", "status": "retired", "label": null, "served_by": "diffio-4.7-pro", "price_per_hour_usd": 10}, {"id": "diffio-3.5", "object": "model", "status": "retired", "label": null, "served_by": "diffio-4.7-pro", "price_per_hour_usd": 10}, {"id": "diffio-4.0", "object": "model", "status": "retired", "label": null, "served_by": "diffio-4.7-flash", "price_per_hour_usd": 5}, {"id": "diffio-4.0-flash", "object": "model", "status": "retired", "label": null, "served_by": "diffio-4.7-flash", "price_per_hour_usd": 5}, {"id": "diffio-4.0-pro", "object": "model", "status": "retired", "label": null, "served_by": "diffio-4.7-pro", "price_per_hour_usd": 10}, {"id": "diffio-4.5-flash", "object": "model", "status": "retired", "label": null, "served_by": "diffio-4.7-flash", "price_per_hour_usd": 5}, {"id": "diffio-4.5-pro", "object": "model", "status": "retired", "label": null, "served_by": "diffio-4.7-pro", "price_per_hour_usd": 10}, {"id": "diffio-4.6-flash", "object": "model", "status": "retired", "label": null, "served_by": "diffio-4.7-flash", "price_per_hour_usd": 5}, {"id": "diffio-4.6-pro", "object": "model", "status": "retired", "label": null, "served_by": "diffio-4.7-pro", "price_per_hour_usd": 10}], "next_cursor": null}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Every model name a generation may ask for, with the model that serves it and its price.", "security": [], "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "from diffio import DiffioClient\n\n# A public call: no API key needed.\nclient = DiffioClient()\n\nmodels = client.models.list()\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\n// A public call: no API key needed.\nconst client = new DiffioClient()\n\nconst models = await client.models.list()\n"}, {"lang": "Shell", "label": "cURL", "source": "curl \"https://api.diffio.ai/v2/models\""}]}}, "/projects": {"post": {"operationId": "createProject", "summary": "Create a project", "tags": ["Projects"], "responses": {"201": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProjectWithUpload"}, "example": {"id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "object": "project", "status": "awaiting_upload", "file_name": "interview.mp3", "content_type": "audio/mpeg", "size_bytes": 510957, "duration_seconds": null, "has_video": false, "end_user": "customer-mwe8tm1g", "metadata": {"order_id": "1042"}, "generation_count": 0, "video_preview_status": null, "latest_generation": null, "share_id": null, "created_at": "2026-11-13T00:33:21.812909Z", "updated_at": "2026-11-13T00:33:21.812909Z", "error": null, "upload": {"upload_session_id": "api-62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "edge_base_url": "https://media.diffio.io", "upload_token": "v1.REDACTED", "part_size_bytes": 33554432, "max_bytes": 2147483648, "expires_at": "2026-11-14T00:33:21.812909Z", "requests": {"start": {"method": "POST", "url": "https://media.diffio.io/v1/uploads/start", "headers": {"Authorization": "Bearer v1.REDACTED"}, "body": null, "returns": ["uploadId", "partSizeBytes", "maxBytes"], "description": "Once, first. Keep uploadId for the other requests."}, "part": {"method": "PUT", "url": "https://media.diffio.io/v1/uploads/parts/{part_number}?uploadId={upload_id}", "headers": {"Authorization": "Bearer v1.REDACTED", "Content-Length": "{part_length}"}, "body": null, "returns": ["partNumber", "etag"], "description": "Once per part, numbered from 1; the body is the part's raw bytes. Every part but the last is exactly part_size_bytes. Keep each etag."}, "complete": {"method": "POST", "url": "https://media.diffio.io/v1/uploads/complete", "headers": {"Authorization": "Bearer v1.REDACTED", "Content-Type": "application/json"}, "body": {"uploadId": "{upload_id}", "parts": [{"partNumber": "{part_number}", "etag": "{etag}"}]}, "returns": ["sizeBytes", "etag"], "description": "Once, after every part, listing every part. Repeating it is safe."}, "abort": {"method": "POST", "url": "https://media.diffio.io/v1/uploads/abort", "headers": {"Authorization": "Bearer v1.REDACTED", "Content-Type": "application/json"}, "body": {"uploadId": "{upload_id}"}, "returns": [], "description": "Optional: drop an unfinished upload's parts."}}}}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Create a project for one recording and return how to upload it (``upload.requests``).  With ``generation`` the first restore is requested now: it is created queued (``latest_generation``), admitted at the 60 second minimum, and starts by itself once the upload is ready. A request with the ``Diffio-End-User`` header creates the project for that end user (``end_user``). ``Idempotency-Key`` makes a repeated request return the first project and its first generation, with fresh upload instructions while the file has not arrived (``upload`` is null after that). The key is the account's (any of its API keys repeats the same request) and each end user's own; repeating it with any field changed (``file_name``, ``content_type``, ``size_bytes``, ``metadata`` or ``generation``) is refused (409 ``idempotency_key_conflict``).", "parameters": [{"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}, {"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string"}, "description": "A repeated request with the same key (and end user), from any of the account's keys, returns the first project and its first generation. Any field changed (file_name, content_type, size_bytes, metadata or generation) is refused (409 idempotency_key_conflict)."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProjectCreate"}, "example": {"file_name": "interview.mp3", "content_type": "audio/mpeg", "size_bytes": 510957, "metadata": {"order_id": "1042"}}}}}, "security": [{"apiKey": []}], "x-required-scope": "projects:write", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\nproject = client.projects.create(\n    file_name=\"interview.mp3\",\n    content_type=\"audio/mpeg\",\n    size_bytes=510957,\n    metadata={\"order_id\": \"1042\"},\n    end_user=\"customer-mwe8tm1g\",\n    idempotency_key=\"v2docs-a-mwe8tm1g\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst project =\n  await client.projects.create(\n    {\n      file_name: \"interview.mp3\",\n      content_type: \"audio/mpeg\",\n      size_bytes: 510957,\n      metadata: { \"order_id\": \"1042\" },\n    },\n    {\n      endUser: \"customer-mwe8tm1g\",\n      idempotencyKey: \"v2docs-a-mwe8tm1g\",\n    },\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl -X POST \"https://api.diffio.ai/v2/projects\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\" \\\n  -H \"Diffio-End-User: customer-mwe8tm1g\" \\\n  -H \"Idempotency-Key: v2docs-a-mwe8tm1g\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"file_name\": \"interview.mp3\",\n    \"content_type\": \"audio/mpeg\",\n    \"size_bytes\": 510957,\n    \"metadata\": {\n      \"order_id\": \"1042\"\n    }\n  }'"}]}, "get": {"operationId": "listProjects", "summary": "List projects", "tags": ["Projects"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProjectList"}, "example": {"object": "list", "data": [{"id": "73118d99-36cf-4039-8005-b962d522fff7", "object": "project", "status": "ready", "file_name": "sermon clip.mp3", "content_type": "audio/mpeg", "size_bytes": 510957, "duration_seconds": 31.9, "has_video": false, "end_user": "customer-mwe8tm1g", "metadata": {}, "generation_count": 1, "video_preview_status": null, "latest_generation": {"id": "73c84c4a-c1ca-5485-b396-171ab632d4b7", "object": "generation", "project_id": "73118d99-36cf-4039-8005-b962d522fff7", "status": "complete", "stage": "complete", "stage_progress": null, "queue": null, "warnings": [], "label": "First pass", "kind": "restore", "source_generation_id": null, "edit": null, "transcript_editable": true, "duration_seconds": 31.8, "quality_score": 4.518, "transcription_status": "ready", "files_available": ["audio", "audio_mixed", "hls_master", "hls_original", "hls_restored", "metadata", "stems_manifest", "transcript", "waveform_original", "waveform_restored"], "error": null, "model": "diffio-4.7-pro", "requested_model": "diffio-pro", "substituted": false, "price_per_hour_usd": 10, "stems_status": "ready", "created_at": "2026-11-13T00:33:29.591679Z", "updated_at": "2026-11-13T00:33:47.290000Z"}, "share_id": null, "created_at": "2026-11-13T00:33:29.384479Z", "updated_at": "2026-11-13T00:33:31.899000Z", "error": null}, {"id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "object": "project", "status": "ready", "file_name": "interview.mp3", "content_type": "audio/mpeg", "size_bytes": 510957, "duration_seconds": 31.9, "has_video": false, "end_user": "customer-mwe8tm1g", "metadata": {"order_id": "1042"}, "generation_count": 1, "video_preview_status": null, "latest_generation": {"id": "ce832a32-a1ce-516a-b8bd-75457bd8517f", "object": "generation", "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "status": "complete", "stage": "complete", "stage_progress": null, "queue": null, "warnings": [], "label": "Take 1", "kind": "restore", "source_generation_id": null, "edit": null, "transcript_editable": false, "duration_seconds": 31.8, "quality_score": 4.572, "transcription_status": "ready", "files_available": ["audio", "audio_mixed", "hls_master", "hls_original", "hls_restored", "metadata", "stems_manifest", "transcript", "waveform_original", "waveform_restored"], "error": null, "model": "diffio-4.7-flash", "requested_model": "diffio-flash", "substituted": false, "price_per_hour_usd": 5, "stems_status": "ready", "created_at": "2026-11-13T00:33:27.117344Z", "updated_at": "2026-11-13T00:33:40.864000Z"}, "share_id": null, "created_at": "2026-11-13T00:33:21.812909Z", "updated_at": "2026-11-13T00:33:27.117344Z", "error": null}], "next_cursor": null}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "The account's projects, newest first, one page at a time, whichever of its keys created them; the ``Diffio-End-User`` header narrows it to that end user's projects.", "parameters": [{"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}, "description": "Page size, 1 to 100 (default 20)."}, {"name": "cursor", "in": "query", "required": false, "schema": {"type": "string"}, "description": "The next_cursor of the previous page."}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "security": [{"apiKey": []}], "x-required-scope": "projects:read", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\npage = client.projects.list()\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst page = await client.projects.list()\n"}, {"lang": "Shell", "label": "cURL", "source": "curl \"https://api.diffio.ai/v2/projects\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\""}]}}, "/projects/{project_id}": {"get": {"operationId": "getProject", "summary": "Get a project", "tags": ["Projects"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Project"}, "example": {"id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "object": "project", "status": "awaiting_upload", "file_name": "interview.mp3", "content_type": "audio/mpeg", "size_bytes": 510957, "duration_seconds": null, "has_video": false, "end_user": "customer-mwe8tm1g", "metadata": {"order_id": "1042"}, "generation_count": 0, "video_preview_status": null, "latest_generation": null, "share_id": null, "created_at": "2026-11-13T00:33:21.812909Z", "updated_at": "2026-11-13T00:33:21.812909Z", "error": null}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "One project.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "security": [{"apiKey": []}], "x-required-scope": "projects:read", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\nproject = client.projects.get(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst project = await client.projects.get(\n  \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n)\n"}, {"lang": "Shell", "label": "cURL", "source": "curl \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\""}]}, "delete": {"operationId": "deleteProject", "summary": "Delete a project", "tags": ["Projects"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProjectDeleted"}, "example": {"id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "object": "project", "deleted": true, "deleted_generations": 1, "deleted_media_objects": 48}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Delete a project and everything Diffio stored for it: the upload, every result and their records.  Refused while a generation is still queued or processing, except one still waiting for a file that never arrived (deleted with the project, uncharged). Usage already charged stays on the account's billing records. If a delete fails part-way, repeating it finishes the job. The project's share is revoked first (its links stop within a minute); from then on publishing or revoking it is 409 ``not_available``.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "security": [{"apiKey": []}], "x-required-scope": "projects:write", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\ndeleted = client.projects.delete(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst deleted =\n  await client.projects.delete(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl -X DELETE \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\""}]}}, "/projects/{project_id}/upload": {"post": {"operationId": "reopenProjectUpload", "summary": "Get new upload instructions", "tags": ["Projects"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProjectWithUpload"}, "example": {"id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "object": "project", "status": "awaiting_upload", "file_name": "interview.mp3", "content_type": "audio/mpeg", "size_bytes": 510957, "duration_seconds": null, "has_video": false, "end_user": "customer-mwe8tm1g", "metadata": {"order_id": "1042"}, "generation_count": 0, "video_preview_status": null, "latest_generation": null, "share_id": null, "created_at": "2026-11-13T00:33:21.812909Z", "updated_at": "2026-11-13T00:33:21.812909Z", "error": null, "upload": {"upload_session_id": "api-62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "edge_base_url": "https://media.diffio.io", "upload_token": "v1.REDACTED", "part_size_bytes": 33554432, "max_bytes": 2147483648, "expires_at": "2026-11-14T00:33:21.812909Z", "requests": {"start": {"method": "POST", "url": "https://media.diffio.io/v1/uploads/start", "headers": {"Authorization": "Bearer v1.REDACTED"}, "body": null, "returns": ["uploadId", "partSizeBytes", "maxBytes"], "description": "Once, first. Keep uploadId for the other requests."}, "part": {"method": "PUT", "url": "https://media.diffio.io/v1/uploads/parts/{part_number}?uploadId={upload_id}", "headers": {"Authorization": "Bearer v1.REDACTED", "Content-Length": "{part_length}"}, "body": null, "returns": ["partNumber", "etag"], "description": "Once per part, numbered from 1; the body is the part's raw bytes. Every part but the last is exactly part_size_bytes. Keep each etag."}, "complete": {"method": "POST", "url": "https://media.diffio.io/v1/uploads/complete", "headers": {"Authorization": "Bearer v1.REDACTED", "Content-Type": "application/json"}, "body": {"uploadId": "{upload_id}", "parts": [{"partNumber": "{part_number}", "etag": "{etag}"}]}, "returns": ["sizeBytes", "etag"], "description": "Once, after every part, listing every part. Repeating it is safe."}, "abort": {"method": "POST", "url": "https://media.diffio.io/v1/uploads/abort", "headers": {"Authorization": "Bearer v1.REDACTED", "Content-Type": "application/json"}, "body": {"uploadId": "{upload_id}"}, "returns": [], "description": "Optional: drop an unfinished upload's parts."}}}}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Get new upload instructions for a project whose file never arrived (the first upload failed or its token expired). The file goes to the same place; a project whose upload already arrived is refused.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "security": [{"apiKey": []}], "x-required-scope": "projects:write", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\nproject = client.projects.reopen_upload(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst project =\n  await client.projects.reopenUpload(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl -X POST \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/upload\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\""}]}}, "/projects/{project_id}/upload/complete": {"post": {"operationId": "completeProjectUpload", "summary": "Complete a project's upload", "tags": ["Projects"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Project"}, "example": {"id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "object": "project", "status": "ready", "file_name": "interview.mp3", "content_type": "audio/mpeg", "size_bytes": 510957, "duration_seconds": 31.9, "has_video": false, "end_user": "customer-mwe8tm1g", "metadata": {"order_id": "1042"}, "generation_count": 0, "video_preview_status": null, "latest_generation": null, "share_id": null, "created_at": "2026-11-13T00:33:21.812909Z", "updated_at": "2026-11-13T00:33:26.311000Z", "error": null}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Optional: say the upload finished, so the file is checked and prepared now.  The edge reports a completed upload by itself about 30 seconds after its own complete request, and the project then becomes ready the same way; calling this only makes readiness immediate. Safe to repeat. Answers with the project, its ``latest_generation`` included.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "security": [{"apiKey": []}], "x-required-scope": "projects:write", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\nproject = client.projects.complete_upload(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst project =\n  await client.projects.completeUpload(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl -X POST \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/upload/complete\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\""}]}}, "/projects/{project_id}/generations": {"post": {"operationId": "createGeneration", "summary": "Create a generation", "tags": ["Generations"], "responses": {"201": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Generation"}, "example": {"id": "ce832a32-a1ce-516a-b8bd-75457bd8517f", "object": "generation", "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "status": "processing", "stage": "preparing", "stage_progress": null, "queue": null, "warnings": [], "label": "Take 1", "kind": "restore", "source_generation_id": null, "edit": null, "transcript_editable": false, "duration_seconds": null, "quality_score": null, "transcription_status": null, "files_available": [], "error": null, "model": "diffio-4.7-flash", "requested_model": "diffio-flash", "substituted": false, "price_per_hour_usd": 5, "stems_status": null, "created_at": "2026-11-13T00:33:27.117344Z", "updated_at": "2026-11-13T00:33:27.999000Z"}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Restore a project's recording with the model named in the body.  Accepted before the project is ready: while the upload is awaited or prepared the generation stays queued and starts by itself once the project is ready (it fails if the upload does). A retired model name runs on the hosted model of the same tier at the lower list price; the answer's ``model`` is what ran. ``Idempotency-Key`` makes a repeated request (from any of the account's keys) return the first generation; repeating it with another ``model``, ``sampling`` or ``label`` is refused (409 ``idempotency_key_conflict``). A generation that could not be started (500 ``generation_start_failed``; nothing ran or was charged) is started again by a repeat of the same request with the same key.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}, {"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string"}, "description": "A repeated request with the same key, from any of the account's keys, returns the first generation. Another model, sampling or label is refused (409 idempotency_key_conflict)."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerationCreate"}, "example": {"model": "diffio-flash", "label": "Take 1"}}}}, "security": [{"apiKey": []}], "x-required-scope": "generations:write", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\ngeneration = client.generations.create(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    model=\"diffio-flash\",\n    label=\"Take 1\",\n    idempotency_key=\"v2docs-g-mwe8tm1g\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst generation =\n  await client.generations.create(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    {\n      model: \"diffio-flash\",\n      label: \"Take 1\",\n    },\n    { idempotencyKey: \"v2docs-g-mwe8tm1g\" },\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl -X POST \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\" \\\n  -H \"Idempotency-Key: v2docs-g-mwe8tm1g\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"diffio-flash\",\n    \"label\": \"Take 1\"\n  }'"}]}, "get": {"operationId": "listGenerations", "summary": "List a project's generations", "tags": ["Generations"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerationList"}, "example": {"object": "list", "data": [{"id": "ce832a32-a1ce-516a-b8bd-75457bd8517f", "object": "generation", "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "status": "complete", "stage": "complete", "stage_progress": null, "queue": null, "warnings": [], "label": "Take 1", "kind": "restore", "source_generation_id": null, "edit": null, "transcript_editable": false, "duration_seconds": 31.8, "quality_score": 4.572, "transcription_status": "ready", "files_available": ["audio", "audio_mixed", "hls_master", "hls_original", "hls_restored", "metadata", "stems_manifest", "transcript", "waveform_original", "waveform_restored"], "error": null, "model": "diffio-4.7-flash", "requested_model": "diffio-flash", "substituted": false, "price_per_hour_usd": 5, "stems_status": "ready", "created_at": "2026-11-13T00:33:27.117344Z", "updated_at": "2026-11-13T00:33:40.864000Z"}], "next_cursor": null}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "A project's generations, newest first.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}, "description": "Page size, 1 to 100 (default 20)."}, {"name": "cursor", "in": "query", "required": false, "schema": {"type": "string"}, "description": "The next_cursor of the previous page."}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "security": [{"apiKey": []}], "x-required-scope": "generations:read", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\npage = client.generations.list(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst page =\n  await client.generations.list(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\""}]}}, "/projects/{project_id}/generations/{generation_id}": {"get": {"operationId": "getGeneration", "summary": "Get a generation", "tags": ["Generations"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Generation"}, "example": {"id": "ce832a32-a1ce-516a-b8bd-75457bd8517f", "object": "generation", "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "status": "processing", "stage": "finalizing", "stage_progress": {"overall_percent": 88, "stage_percent": 0, "available_through_seconds": 0, "duration_seconds": 31.8}, "queue": null, "warnings": [], "label": "Take 1", "kind": "restore", "source_generation_id": null, "edit": null, "transcript_editable": false, "duration_seconds": null, "quality_score": null, "transcription_status": "ready", "files_available": [], "error": null, "model": "diffio-4.7-flash", "requested_model": "diffio-flash", "substituted": false, "price_per_hour_usd": 5, "stems_status": null, "created_at": "2026-11-13T00:33:27.117344Z", "updated_at": "2026-11-13T00:33:36.673000Z"}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "One generation: where it is (stage, stage_progress, queue), any warnings and, when it failed, why.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "generation_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "security": [{"apiKey": []}], "x-required-scope": "generations:read", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\ngeneration = client.generations.get(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst generation =\n  await client.generations.get(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\""}]}}, "/projects/{project_id}/generations/{generation_id}/media": {"get": {"operationId": "getGenerationMedia", "summary": "Get a playback grant", "tags": ["Generations"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerationMedia"}, "example": {"object": "generation_media", "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f", "status": "complete", "base_url": "https://media.diffio.io/m/v1.REDACTED/", "expires_at": "2026-11-13T06:33:47Z", "preview_seconds": null, "files": {"audio": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/restored.mp3", "audio_mixed": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/mixed.mp3", "hls_master": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/master.m3u8", "hls_original": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/noisy/index.m3u8", "hls_restored": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/clean/index.m3u8", "metadata": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/metadata.json", "original": "https://media.diffio.io/m/v1.REDACTED/original/interview.mp3", "stems_manifest": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/stems/4014a8c299444bbb866971bbb7b657ca/manifest.v2.json", "transcript": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/word_timestamps.json", "waveform_original": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/visualizations/hls_waveform_noisy.json", "waveform_restored": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/visualizations/hls_waveform_clean.json"}}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "A playback grant for a browser: a URL for each of the generation's files, all valid until ``expires_at``.  ``files`` maps a file's name to its URL; add ``?download=<file name>`` to one to have a browser save it under that name. The adaptive stream (``hls_master``) is readable while the generation is still processing and grows as it runs; the entries inside its playlists are relative and resolve against the playlist's own URL. For a video project it also carries the picture (the project's ``video_hls``), which plays once the project's ``video_preview_status`` is ready. Every URL starts with ``base_url``. The separated tracks' manifest (``stems_manifest``) names its chunks, masters and picture stream by paths relative to its own URL (``chunks/000000.flac``); the speech leveling curve, when the result has one, is ``leveling-v1.bin`` beside it. With ``preview_seconds`` the grant serves only that much of each stream, plus waveforms, the separated tracks' manifest, the picture-only stream and the original upload; the full-length files (``audio``, ``audio_mixed``, ``video``, ``transcript``, ``metadata``, ``edited_transcript``) are left out. The restored audio, the restored video of a video project (``video``, an mp4) and the transcript are downloaded from here: ``?download=<file name>`` names the download.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "generation_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "preview_seconds", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 4, "maximum": 3600}, "description": "Limit playback to the first seconds of each stream (rounded up to whole 4 second segments)."}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "security": [{"apiKey": []}], "x-required-scope": "artifacts:read", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\nmedia = client.generations.media(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst media =\n  await client.generations.media(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/media\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\""}]}}, "/projects/{project_id}/generations/{generation_id}/edits": {"post": {"operationId": "createTranscriptEdit", "summary": "Edit a generation's transcript", "tags": ["Generations"], "responses": {"201": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Generation"}, "example": {"id": "00000000-0000-5000-8000-000000000001", "object": "generation", "project_id": "73118d99-36cf-4039-8005-b962d522fff7", "status": "queued", "stage": "preparing", "stage_progress": null, "queue": null, "warnings": [], "label": "Transcript edit", "kind": "edit", "source_generation_id": "73c84c4a-c1ca-5485-b396-171ab632d4b7", "edit": {"edit_count": 1, "max_windows": 1, "windows": null, "windows_done": null, "ranges": [], "billable_seconds": null, "cut_seconds": null, "request_id": "edit-1042", "language": "en", "tighten": null}, "transcript_editable": false, "duration_seconds": 31.8, "quality_score": null, "transcription_status": "preparing", "files_available": ["edited_transcript"], "error": null, "model": "diffio-4.7-pro", "requested_model": "diffio-pro", "substituted": false, "price_per_hour_usd": 10, "stems_status": null, "created_at": "2026-11-13T00:34:12.503218Z", "updated_at": "2026-11-13T00:34:12.503218Z"}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Edit the transcript of a finished Pro generation: send its words with the changes made, and only the windows around the changed words are restored again, as a new generation of ``kind`` ``edit``.  ``words`` is the whole transcript after editing. A word that was kept carries the ``start`` and ``end`` it has in the transcript; a new or changed word carries neither. Left out, it is the stored transcript as it is (the words ``GET .../transcript`` gives), for an edit that only shortens long pauses (``tighten.max_pause_seconds``). The editor's words, as the assistant takes them, are accepted as they are: ``text`` ``''`` is a removed word, and ``changed`` or ``regenerate`` true is a word said again (its ``start`` and ``end`` are ignored). ``tighten`` cuts the recording shorter where words were removed or pauses are long (audio only). An edit bills 30 seconds for each window restored, with no minimum: one that only cuts bills nothing. POST .../edits/estimate says the most it could bill first (``max_billable_seconds``); that much credit is held while the edit runs, and an edit that can bill nothing holds none and is never refused for credit. ``Idempotency-Key`` makes a repeated request (from any of the account's keys, concurrent ones included) return the first edit of that generation and bill it once, without checking or estimating the words again; repeating it with another edit (other words, timing, flags, ``tighten`` or ``request_id``) is refused (409 ``idempotency_key_conflict``). An edit created but never queued (503 ``edit_not_queued``) is queued by a repeat of the same request with the same key. Word fields the edit does not read (anything but ``id``, ``text`` or ``word``, ``start``, ``end``, ``language``, ``changed`` and ``regenerate``) are not compared.  Refusals (``error.code``): 400 ``missing_field`` or ``invalid_field`` for a malformed body (``invalid_field`` with ``details.field`` ``words`` when the words change nothing and ``tighten.max_pause_seconds`` is not set, ``words`` left out included); 404 ``generation_not_found``; 409 ``not_ready`` while the generation is still queued or processing (``details.generation_status``; edit it once it is complete); 409 ``not_available`` when it never can be: the generation failed, its transcript failed or is unavailable (``details.transcription_status``), or the project is being deleted; 409 ``not_editable`` when it is not a finished Pro result that kept what an edit needs, or ``tighten`` was asked of a video project; 402 ``insufficient_credit``, ``usage_limit_reached``, ``payment_failed``, ``needs_payment_method`` or ``payment_required`` when the account cannot pay for the most the edit could bill (an edit that only cuts is refused only for ``payment_failed``); 503 ``edit_not_queued`` when the edit was created but could not be queued (nothing is billed; send it again, with the same Idempotency-Key if it had one).", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "generation_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}, {"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string"}, "description": "A repeated request with the same key, from any of the account's keys, returns the first edit of that generation and bills it once, even when the requests run at the same time. Another edit (words, timing, flags, tighten or request_id) is refused (409 idempotency_key_conflict); word fields the edit does not read are not compared."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TranscriptEditCreate"}, "example": {"words": [{"id": "word-0", "text": "For", "start": 0.6, "end": 0.8, "probability": null, "language": "en", "label": "speech"}, {"id": "word-1", "text": "", "start": 0.84, "end": 0.94, "probability": null, "language": "en", "label": "speech"}, {"id": "word-2", "text": "lives", "start": 1.04, "end": 1.32, "probability": null, "language": "en", "label": "speech"}], "request_id": "edit-1042"}}}}, "security": [{"apiKey": []}], "x-required-scope": "generations:write", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\nedit = client.edits.create(\n    \"73118d99-36cf-4039-8005-b962d522fff7\",\n    \"73c84c4a-c1ca-5485-b396-171ab632d4b7\",\n    words=[\n        {\n            \"id\": \"word-0\",\n            \"text\": \"For\",\n            \"start\": 0.6,\n            \"end\": 0.8,\n            \"probability\": None,\n            \"language\": \"en\",\n        },\n        {\n            \"id\": \"word-1\",\n            \"text\": \"\",\n            \"start\": 0.84,\n            \"end\": 0.94,\n            \"probability\": None,\n            \"language\": \"en\",\n        },\n        {\n            \"id\": \"word-2\",\n            \"text\": \"lives\",\n            \"start\": 1.04,\n            \"end\": 1.32,\n            \"probability\": None,\n            \"language\": \"en\",\n        },\n    ],\n    request_id=\"edit-1042\",\n    idempotency_key=\"edit-1042\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst edit = await client.edits.create(\n  \"73118d99-36cf-4039-8005-b962d522fff7\",\n  \"73c84c4a-c1ca-5485-b396-171ab632d4b7\",\n  {\n    words: [\n      {\n        id: \"word-0\",\n        text: \"For\",\n        start: 0.6,\n        end: 0.8,\n        probability: null,\n        language: \"en\",\n      },\n      {\n        id: \"word-1\",\n        text: \"\",\n        start: 0.84,\n        end: 0.94,\n        probability: null,\n        language: \"en\",\n      },\n      {\n        id: \"word-2\",\n        text: \"lives\",\n        start: 1.04,\n        end: 1.32,\n        probability: null,\n        language: \"en\",\n      },\n    ],\n    request_id: \"edit-1042\",\n  },\n  { idempotencyKey: \"edit-1042\" },\n)\n"}, {"lang": "Shell", "label": "cURL", "source": "curl -X POST \"https://api.diffio.ai/v2/projects/73118d99-36cf-4039-8005-b962d522fff7/generations/73c84c4a-c1ca-5485-b396-171ab632d4b7/edits\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\" \\\n  -H \"Idempotency-Key: edit-1042\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"words\": [\n      {\n        \"id\": \"word-0\",\n        \"text\": \"For\",\n        \"start\": 0.6,\n        \"end\": 0.8,\n        \"probability\": null,\n        \"language\": \"en\",\n        \"label\": \"speech\"\n      },\n      {\n        \"id\": \"word-1\",\n        \"text\": \"\",\n        \"start\": 0.84,\n        \"end\": 0.94,\n        \"probability\": null,\n        \"language\": \"en\",\n        \"label\": \"speech\"\n      },\n      {\n        \"id\": \"word-2\",\n        \"text\": \"lives\",\n        \"start\": 1.04,\n        \"end\": 1.32,\n        \"probability\": null,\n        \"language\": \"en\",\n        \"label\": \"speech\"\n      }\n    ],\n    \"request_id\": \"edit-1042\"\n  }'"}]}}, "/projects/{project_id}/generations/{generation_id}/edits/estimate": {"post": {"operationId": "estimateTranscriptEdit", "summary": "Estimate a transcript edit", "tags": ["Generations"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TranscriptEditEstimate"}, "example": {"object": "transcript_edit_estimate", "project_id": "73118d99-36cf-4039-8005-b962d522fff7", "generation_id": "73c84c4a-c1ca-5485-b396-171ab632d4b7", "edit_count": 1, "max_windows": 1, "window_seconds": 30, "max_billable_seconds": 30}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "The most a transcript edit could bill, without starting it: the same body as POST .../edits.  The words are checked and the changed runs counted as the edit would; nothing is created or charged. Needs ``generations:write``, the scope of the edit itself. It refuses as the edit does, but for the 402s and ``edit_not_queued`` (nothing is admitted or queued).  Refusals (``error.code``): 400 ``missing_field`` or ``invalid_field`` for a malformed body (``invalid_field`` with ``details.field`` ``words`` when the words change nothing and ``tighten.max_pause_seconds`` is not set, ``words`` left out included); 404 ``generation_not_found``; 409 ``not_ready`` while the generation is still queued or processing (``details.generation_status``; edit it once it is complete); 409 ``not_available`` when it never can be: the generation failed, its transcript failed or is unavailable (``details.transcription_status``), or the project is being deleted; 409 ``not_editable`` when it is not a finished Pro result that kept what an edit needs, or ``tighten`` was asked of a video project; 402 ``insufficient_credit``, ``usage_limit_reached``, ``payment_failed``, ``needs_payment_method`` or ``payment_required`` when the account cannot pay for the most the edit could bill (an edit that only cuts is refused only for ``payment_failed``); 503 ``edit_not_queued`` when the edit was created but could not be queued (nothing is billed; send it again, with the same Idempotency-Key if it had one).", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "generation_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TranscriptEditCreate"}, "example": {"words": [{"id": "word-0", "text": "For", "start": 0.6, "end": 0.8, "probability": null, "language": "en", "label": "speech"}, {"id": "word-1", "text": "", "start": 0.84, "end": 0.94, "probability": null, "language": "en", "label": "speech"}, {"id": "word-2", "text": "lives", "start": 1.04, "end": 1.32, "probability": null, "language": "en", "label": "speech"}]}}}}, "security": [{"apiKey": []}], "x-required-scope": "generations:write", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\nestimate = client.edits.estimate(\n    \"73118d99-36cf-4039-8005-b962d522fff7\",\n    \"73c84c4a-c1ca-5485-b396-171ab632d4b7\",\n    words=[\n        {\n            \"id\": \"word-0\",\n            \"text\": \"For\",\n            \"start\": 0.6,\n            \"end\": 0.8,\n            \"probability\": None,\n            \"language\": \"en\",\n        },\n        {\n            \"id\": \"word-1\",\n            \"text\": \"\",\n            \"start\": 0.84,\n            \"end\": 0.94,\n            \"probability\": None,\n            \"language\": \"en\",\n        },\n        {\n            \"id\": \"word-2\",\n            \"text\": \"lives\",\n            \"start\": 1.04,\n            \"end\": 1.32,\n            \"probability\": None,\n            \"language\": \"en\",\n        },\n    ],\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst estimate =\n  await client.edits.estimate(\n    \"73118d99-36cf-4039-8005-b962d522fff7\",\n    \"73c84c4a-c1ca-5485-b396-171ab632d4b7\",\n    {\n      words: [\n        {\n          id: \"word-0\",\n          text: \"For\",\n          start: 0.6,\n          end: 0.8,\n          probability: null,\n          language: \"en\",\n        },\n        {\n          id: \"word-1\",\n          text: \"\",\n          start: 0.84,\n          end: 0.94,\n          probability: null,\n          language: \"en\",\n        },\n        {\n          id: \"word-2\",\n          text: \"lives\",\n          start: 1.04,\n          end: 1.32,\n          probability: null,\n          language: \"en\",\n        },\n      ],\n    },\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl -X POST \"https://api.diffio.ai/v2/projects/73118d99-36cf-4039-8005-b962d522fff7/generations/73c84c4a-c1ca-5485-b396-171ab632d4b7/edits/estimate\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"words\": [\n      {\n        \"id\": \"word-0\",\n        \"text\": \"For\",\n        \"start\": 0.6,\n        \"end\": 0.8,\n        \"probability\": null,\n        \"language\": \"en\",\n        \"label\": \"speech\"\n      },\n      {\n        \"id\": \"word-1\",\n        \"text\": \"\",\n        \"start\": 0.84,\n        \"end\": 0.94,\n        \"probability\": null,\n        \"language\": \"en\",\n        \"label\": \"speech\"\n      },\n      {\n        \"id\": \"word-2\",\n        \"text\": \"lives\",\n        \"start\": 1.04,\n        \"end\": 1.32,\n        \"probability\": null,\n        \"language\": \"en\",\n        \"label\": \"speech\"\n      }\n    ]\n  }'"}]}}, "/projects/{project_id}/generations/{generation_id}/mix": {"get": {"operationId": "getGenerationMix", "summary": "Get the saved mix", "tags": ["Separated tracks"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerationMix"}, "example": {"object": "generation_mix", "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f", "background_gain": 0, "leveling": false, "revision": "4014a8c299444bbb866971bbb7b657ca:0", "stems_revision": "4014a8c299444bbb866971bbb7b657ca"}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "The saved balance of a generation's separated tracks: how much background to keep under the speech.  ``stems_revision`` names the separated tracks the balance is for (the revision their manifest names), so a player can tell a balance of tracks prepared again from the tracks it plays. ``revision`` is opaque: send it back unchanged when saving.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "generation_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "security": [{"apiKey": []}], "x-required-scope": "artifacts:read", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\nmix = client.mix.get(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst mix = await client.mix.get(\n  \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n  \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n)\n"}, {"lang": "Shell", "label": "cURL", "source": "curl \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/mix\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\""}]}, "put": {"operationId": "saveGenerationMix", "summary": "Save the mix", "tags": ["Separated tracks"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerationMix"}, "example": {"object": "generation_mix", "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f", "background_gain": 0.3, "leveling": false, "revision": "4014a8c299444bbb866971bbb7b657ca:1", "stems_revision": "4014a8c299444bbb866971bbb7b657ca"}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Save the balance. With the ``revision`` last read, a save made from a stale mix is refused (409 ``revision_conflict``, with the current revision in ``details.current_revision``), so two editors cannot silently overwrite each other; without it the save replaces whatever is saved. ``leveling`` left out keeps the saved setting. Separated tracks that are not ready yet are 409 ``not_ready``; a generation that will never have them is 409 ``not_available``.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "generation_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerationMixSave"}, "example": {"background_gain": 0.3, "revision": "4014a8c299444bbb866971bbb7b657ca:0"}}}}, "security": [{"apiKey": []}], "x-required-scope": "generations:write", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\nrev = \"4014a8c299444bbb866971bbb7b657ca:0\"\nmix = client.mix.save(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n    background_gain=0.3,\n    revision=rev,\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst mix = await client.mix.save(\n  \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n  \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n  {\n    background_gain: 0.3,\n    revision: \"4014a8c299444bbb866971bbb7b657ca:0\",\n  },\n)\n"}, {"lang": "Shell", "label": "cURL", "source": "curl -X PUT \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/mix\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"background_gain\": 0.3,\n    \"revision\": \"4014a8c299444bbb866971bbb7b657ca:0\"\n  }'"}]}}, "/projects/{project_id}/generations/{generation_id}/exports": {"post": {"operationId": "createGenerationExport", "summary": "Create an export", "tags": ["Separated tracks"], "responses": {"201": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerationExport"}, "example": {"object": "generation_export", "id": "d51fd816be75bc302ecc3def3da4f22d", "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f", "status": "queued", "artifact": "mix", "format": "mp3", "background_gain": 0.3, "leveling": false, "inline": false, "url": null, "error": null}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Render a download from a generation's separated tracks: the speech, the background, a mix of the two at a chosen balance, or both tracks in a zip.  ``inline`` asks for a file to play in a page instead of download (mp3 or mp4, and the only way to get ``original``: the upload on the same timeline, for comparison). A ``mix`` without ``background_gain`` uses the saved mix (GET .../mix), its leveling included.  The answer's ``status`` moves from queued to processing to ready, when ``url`` is a download link (a link to play in a page for an inline export). Asking for the same export again returns the same one instead of rendering it twice; asking again for one that failed renders it again. GET .../exports/{id} reads it.  Refusals: 409 ``not_ready`` while the separated tracks are not ready yet (``stems_status`` preparing, or the generation still running); 409 ``not_available`` when the generation will never have them; 409 ``too_many_exports`` while four exports of the generation are rendering; 409 ``leveling_not_available`` and 409 ``video_not_available`` when leveling or an mp4 cannot be made for this generation.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "generation_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerationExportCreate"}, "example": {"artifact": "mix", "format": "mp3", "file_name": "interview mix"}}}}, "security": [{"apiKey": []}], "x-required-scope": "generations:write", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\nexport = client.exports.create(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n    artifact=\"mix\",\n    format=\"mp3\",\n    file_name=\"interview mix\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst rendered =\n  await client.exports.create(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n    {\n      artifact: \"mix\",\n      format: \"mp3\",\n      file_name: \"interview mix\",\n    },\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl -X POST \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/exports\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"artifact\": \"mix\",\n    \"format\": \"mp3\",\n    \"file_name\": \"interview mix\"\n  }'"}]}}, "/projects/{project_id}/generations/{generation_id}/exports/{export_id}": {"get": {"operationId": "getGenerationExport", "summary": "Get an export", "tags": ["Separated tracks"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerationExport"}, "example": {"object": "generation_export", "id": "d51fd816be75bc302ecc3def3da4f22d", "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f", "status": "ready", "artifact": "mix", "format": "mp3", "background_gain": 0.3, "leveling": false, "inline": false, "url": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/downloads/stems/d51fd816be75bc302ecc3def3da4f22d/98111c08d1f247d0b43a4eeeb50b5e7a/diffio_mix.mp3?download=interview%20mix.mp3", "error": null}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "An export's status and, once it is ready, a fresh link: a download, or a link to play in a page for an inline export. Reading only reads the stored export: it never renders anything, even after the separated tracks were prepared again, and a failed export stays failed (POST .../exports renders it again).", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "generation_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "export_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "file_name", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Name the download (without its extension)."}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "security": [{"apiKey": []}], "x-required-scope": "artifacts:read", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\nexport = client.exports.get(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n    \"d51fd816be75bc302ecc3def3da4f22d\",\n    file_name=\"interview mix\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst rendered = await client.exports.get(\n  \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n  \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n  \"d51fd816be75bc302ecc3def3da4f22d\",\n  { file_name: \"interview mix\" },\n)\n"}, {"lang": "Shell", "label": "cURL", "source": "curl \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/exports/d51fd816be75bc302ecc3def3da4f22d?file_name=interview%20mix\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\""}]}}, "/projects/{project_id}/share": {"put": {"operationId": "publishProjectShare", "summary": "Publish a project's share", "tags": ["Shares"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProjectShare"}, "example": {"object": "project_share", "id": "Hq7cTnWm3RkZpY2vB", "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f", "file_name": "interview.mp3", "content_type": "audio/mpeg", "created_at": "2026-11-13T00:34:06.463210Z", "has_video": false, "duration_seconds": 31.9, "preview_seconds": null, "base_url": "https://media.diffio.io/s/v1.REDACTED/", "files": {"audio": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/restored.mp3", "audio_mixed": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/mixed.mp3", "hls_master": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/master.m3u8", "hls_original": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/noisy/index.m3u8", "hls_restored": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/clean/index.m3u8", "metadata": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/metadata.json", "stems_manifest": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/stems/4014a8c299444bbb866971bbb7b657ca/manifest.v2.json", "transcript": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/word_timestamps.json", "waveform_original": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/visualizations/hls_waveform_noisy.json", "waveform_restored": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/visualizations/hls_waveform_clean.json"}}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Publish a project's share, or change what a published share plays.  ``generation_id`` pins the share to one generation; without it the share plays the project's newest finished generation. A pinned generation must have finished: one still running is refused (409 ``not_ready``; publish again once it is complete) and a failed one is refused (409 ``not_available``). ``preview_seconds`` limits playback to the start of the recording, and the share then names only the files a preview plays (no full-length ``audio`` or ``video``). Publishing again keeps the same share id. Publishing again with the same ``generation_id`` and ``preview_seconds`` keeps every URL the share gave working; changing either (or publishing a share revoked earlier) gives it a new version, so every URL it gave before stops working within a minute and only the URLs of a new read play. Of two publications (or a publication and a revoke) at once, the one that started first is refused (409 ``conflict``); the later one stands. A project being deleted is 409 ``not_available``.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProjectSharePublish"}, "example": {}}}}, "security": [{"apiKey": []}], "x-required-scope": "projects:write", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\nshare = client.shares.publish(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst share =\n  await client.shares.publish(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl -X PUT \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/share\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"}]}, "get": {"operationId": "getProjectShare", "summary": "Get a project's share", "tags": ["Shares"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProjectShare"}, "example": {"object": "project_share", "id": "Hq7cTnWm3RkZpY2vB", "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f", "file_name": "interview.mp3", "content_type": "audio/mpeg", "created_at": "2026-11-13T00:34:06.463210Z", "has_video": false, "duration_seconds": 31.9, "preview_seconds": null, "base_url": "https://media.diffio.io/s/v1.REDACTED/", "files": {"audio": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/restored.mp3", "audio_mixed": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/mixed.mp3", "hls_master": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/master.m3u8", "hls_original": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/noisy/index.m3u8", "hls_restored": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/clean/index.m3u8", "metadata": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/metadata.json", "stems_manifest": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/stems/4014a8c299444bbb866971bbb7b657ca/manifest.v2.json", "transcript": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/word_timestamps.json", "waveform_original": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/visualizations/hls_waveform_noisy.json", "waveform_restored": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/visualizations/hls_waveform_clean.json"}}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "A project's published share.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "security": [{"apiKey": []}], "x-required-scope": "projects:read", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\nshare = client.shares.get(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst share = await client.shares.get(\n  \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n)\n"}, {"lang": "Shell", "label": "cURL", "source": "curl \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/share\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\""}]}, "delete": {"operationId": "revokeProjectShare", "summary": "Revoke a project's share", "tags": ["Shares"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProjectShareRevoked"}, "example": {"object": "project_share", "id": "Hq7cTnWm3RkZpY2vB", "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "deleted": true}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Revoke a project's share. Its links stop working within a minute and never work again. A publication that runs at the same time and reserves after the revoke wins (this revoke is then refused with 409 ``conflict``); one that reserved before it can no longer commit. A project being deleted is 409 ``not_available`` (the delete revokes its share itself).", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "security": [{"apiKey": []}], "x-required-scope": "projects:write", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\nrevoked = client.shares.revoke(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst revoked =\n  await client.shares.revoke(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl -X DELETE \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/share\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\""}]}}, "/shares/{share_id}": {"get": {"operationId": "getShare", "summary": "Get a share", "tags": ["Shares"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProjectShare"}, "example": {"object": "project_share", "id": "Hq7cTnWm3RkZpY2vB", "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f", "file_name": "interview.mp3", "content_type": "audio/mpeg", "created_at": "2026-11-13T00:34:06.463210Z", "has_video": false, "duration_seconds": 31.9, "preview_seconds": null, "base_url": "https://media.diffio.io/s/v1.REDACTED/", "files": {"audio": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/restored.mp3", "audio_mixed": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/mixed.mp3", "hls_master": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/master.m3u8", "hls_original": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/noisy/index.m3u8", "hls_restored": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/clean/index.m3u8", "metadata": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/metadata.json", "stems_manifest": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/stems/4014a8c299444bbb866971bbb7b657ca/manifest.v2.json", "transcript": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/word_timestamps.json", "waveform_original": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/visualizations/hls_waveform_noisy.json", "waveform_restored": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/visualizations/hls_waveform_clean.json"}}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "A share, for anyone who holds its id: what it plays and where to play it from. Needs no API key.", "parameters": [{"name": "share_id", "in": "path", "required": true, "schema": {"type": "string"}}], "security": [], "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "from diffio import DiffioClient\n\n# A public call: no API key needed.\nclient = DiffioClient()\n\nshare = client.shares.get_public(\n    \"Hq7cTnWm3RkZpY2vB\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\n// A public call: no API key needed.\nconst client = new DiffioClient()\n\nconst share =\n  await client.shares.getPublic(\n    \"Hq7cTnWm3RkZpY2vB\",\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl \"https://api.diffio.ai/v2/shares/Hq7cTnWm3RkZpY2vB\""}]}}, "/projects/{project_id}/generations/{generation_id}/transcript": {"get": {"operationId": "getTranscript", "summary": "Get a generation's transcript", "tags": ["Transcripts"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Transcript"}, "example": {"object": "transcript", "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f", "text": "For the lives of women have been more affected by its new horizons than those of any other group. Profound and stirring as have been accomplishments in the remoter fields of pure research, it is in the home that the applications of scientific achievement have perhaps been most far-reaching, and it is through changing conditions there that women have become the greatest beneficiaries in the modern scheme. Science has released them from much", "words": [{"id": "word-0", "text": "For", "start": 0.6, "end": 0.8, "probability": null, "language": "en", "label": "speech"}, {"id": "word-1", "text": "the", "start": 0.84, "end": 0.94, "probability": null, "language": "en", "label": "speech"}, {"id": "word-2", "text": "lives", "start": 1.04, "end": 1.32, "probability": null, "language": "en", "label": "speech"}], "preview_seconds": null, "truncated": false}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "A generation's word-timed transcript.  ``words`` are the transcript's words in order, each a ``TranscriptWord``: a stable ``id``, its ``text``, ``start`` and ``end`` in seconds on the recording (null when untimed), ``probability`` (the transcriber's confidence, 0 to 1, or null), and whatever else the transcriber recorded (``speaker``, ``language``). Send the words back as they are, with your changes (``text``, and ``changed``, ``regenerate`` or ``''`` as an editor marks them), to ``POST .../edits`` or the assistant. ``preview_seconds`` (4 to 3600, rounded up to whole 4 second segments, as playback is) keeps only the words that start inside the preview, each with its ``id``, ``text``, ``start``, ``end``, ``probability`` and ``language`` only, and ``truncated`` says whether any were left out.  Refusals follow the generation's ``transcription_status``, as the separated-track routes follow ``stems_status``: 409 ``not_ready`` while it is preparing (or, with no status reported, while the generation still runs): ask again shortly; 409 ``not_available`` when it failed (or the generation failed without one): this generation will never have a transcript. 404 ``transcript_not_found`` only for a finished generation that reports no transcription and has none stored (results made before transcripts were kept), or whose stored transcript is missing. Each refusal's ``details.transcription_status`` is the status it read.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "generation_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "preview_seconds", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 4, "maximum": 3600}, "description": "Keep only the words that start in the first seconds (rounded up to whole 4 second segments)."}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "security": [{"apiKey": []}], "x-required-scope": "generations:read", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\ntranscript = client.transcripts.get(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst transcript =\n  await client.transcripts.get(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/transcript\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\""}]}}, "/projects/{project_id}/generations/{generation_id}/transcript/draft": {"get": {"operationId": "getTranscriptDraft", "summary": "Get the transcript draft", "tags": ["Transcripts"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TranscriptDraft"}, "example": {"object": "transcript_draft", "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f", "revision": "0", "data": null, "created_at": null, "updated_at": null}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "The generation's saved transcript draft: ``data``, the JSON object last saved, exactly as it was sent.  A generation has one draft, shared by everyone who can reach its project. ``revision`` is an opaque string that changes with every save and delete and is never given twice; send it back to save or delete. When nothing is saved (never, or since a delete) ``data`` is null and ``revision`` is still the current one, so the first save sends it back like any other.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "generation_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "security": [{"apiKey": []}], "x-required-scope": "generations:read", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\ndraft = client.transcripts.get_draft(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst draft =\n  await client.transcripts.getDraft(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/transcript/draft\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\""}]}, "put": {"operationId": "saveTranscriptDraft", "summary": "Save the transcript draft", "tags": ["Transcripts"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TranscriptDraft"}, "example": {"object": "transcript_draft", "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f", "revision": "1", "data": {"cursor": 12, "removed": ["w3"]}, "created_at": "2026-11-13T00:33:51.366709Z", "updated_at": "2026-11-13T00:33:51.366709Z"}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Save the draft whole: ``data`` is any JSON object of at most 900,000 bytes, stored as sent.  Send the ``revision`` last read (GET answers with one even when nothing is saved): a save from any other revision is refused with ``revision_conflict`` and ``details.current_revision`` (a string), so two editors never silently overwrite each other; read the draft again, merge and retry. Without ``revision`` the save replaces whatever is there.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "generation_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TranscriptDraftSave"}, "example": {"data": {"cursor": 12, "removed": ["w3"]}, "revision": "0"}}}}, "security": [{"apiKey": []}], "x-required-scope": "generations:write", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\ndraft = client.transcripts.save_draft(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n    data={\"cursor\": 12, \"removed\": [\"w3\"]},\n    revision=\"0\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst draft =\n  await client.transcripts.saveDraft(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n    {\n      data: {\n        \"cursor\": 12,\n        \"removed\": [\"w3\"],\n      },\n      revision: \"0\",\n    },\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl -X PUT \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/transcript/draft\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"data\": {\n      \"cursor\": 12,\n      \"removed\": [\n        \"w3\"\n      ]\n    },\n    \"revision\": \"0\"\n  }'"}]}, "delete": {"operationId": "deleteTranscriptDraft", "summary": "Delete the transcript draft", "tags": ["Transcripts"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TranscriptDraftDeleted"}, "example": {"object": "transcript_draft", "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe", "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f", "deleted": true, "revision": "2"}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Delete the draft. With ``revision`` (the one last read) a draft saved since is kept and the delete is refused with ``revision_conflict``. The delete is a revision of its own (``revision`` in the answer, the one GET then gives), so a save from a revision read before it is refused, even once a new draft is saved. With nothing saved the delete succeeds as it is (like a share's): the answer gives the current revision, which does not change, and a stale ``revision`` is still refused.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "generation_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "revision", "in": "query", "required": false, "schema": {"type": "string"}, "description": "The revision last read (an opaque string); a draft saved since is kept."}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "security": [{"apiKey": []}], "x-required-scope": "generations:write", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\ndeleted = client.transcripts.delete_draft(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n    revision=\"1\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst deleted =\n  await client.transcripts.deleteDraft(\n    \"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe\",\n    \"ce832a32-a1ce-516a-b8bd-75457bd8517f\",\n    { revision: \"1\" },\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl -X DELETE \"https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/transcript/draft?revision=1\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\""}]}}, "/projects/{project_id}/generations/{generation_id}/transcript/assistant/turns": {"post": {"operationId": "createTranscriptAssistantTurn", "summary": "Ask the edit assistant", "tags": ["Transcripts"], "responses": {"202": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TranscriptAssistantTurn"}, "example": {"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}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Ask the edit assistant about a finished Pro generation's transcript: one chat turn, answered later.  Send the chat so far (``messages``, the last one the question) and the editor's words as they stand (``words``, each a ``TranscriptWord`` with its ``id``: the words of ``GET .../transcript`` as they are, with ``text`` changed for an edited word, ``''`` for a removed one, and ``changed`` and ``regenerate`` flags; the same array ``POST .../edits`` takes). Leave ``words`` out to ask about the stored transcript as it is: the same words, with the same ids, ``GET .../transcript`` gives. The turn is created ``processing``; read it with ``GET .../assistant/turns/{turn_id}`` every second or two until it is ``complete`` (with the answer) or ``failed`` (with ``error``). A turn may listen to the restored audio and can take a few minutes. The answer's ``reply`` is for the person; ``proposals`` are edits in those word ids that the person may accept into their words, and nothing changes the audio until an edit is created (``POST .../edits``). Limited per end user: a turn fails with ``rate_limited`` after many requests in a few minutes or a day's worth of use.  The request and the generation are checked before the turn is created (everything the assistant needs of the result: finished, Pro, its latents, its recorded duration, its original upload and its transcript), so these are answered at once and nothing is created: 400 ``missing_field`` or ``invalid_field`` (``details.field``: ``messages``, 1 to 40 ``{role, content}`` with the question last; ``words``, each with a unique ``id`` and its ``text``; ``selection``; ``playhead_seconds``); 409 ``not_ready`` while the generation is still queued or processing (``details.generation_status``) or its transcript is still being prepared; 409 ``not_available`` when it failed, its transcript failed or is missing, its duration or original upload is unknown, or its project is being deleted; 409 ``not_editable`` when it is not a finished Pro result that kept what an edit needs; 422 ``transcript_unreadable`` when ``words`` is left out and the stored transcript cannot be read. A turn that fails while it runs is ``failed`` with ``error.code`` (a ResourceError; every code is in its x-error-codes): ``rate_limited``, ``assistant_timeout``, ``assistant_unavailable``, ``not_editable``, ``invalid_field``, ``permission_denied``, ``unauthenticated``, ``project_not_found``, ``internal_error``.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "generation_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TranscriptAssistantTurnCreate"}, "example": {"messages": [{"role": "user", "content": "Remove the filler words."}], "source": "typed"}}}}, "security": [{"apiKey": []}], "x-required-scope": "generations:write", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\nturn = client.assistant.create_turn(\n    \"73118d99-36cf-4039-8005-b962d522fff7\",\n    \"73c84c4a-c1ca-5485-b396-171ab632d4b7\",\n    messages=[\n        {\n            \"role\": \"user\",\n            \"content\": \"Remove the filler words.\",\n        },\n    ],\n    source=\"typed\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst turn =\n  await client.assistant.createTurn(\n    \"73118d99-36cf-4039-8005-b962d522fff7\",\n    \"73c84c4a-c1ca-5485-b396-171ab632d4b7\",\n    {\n      messages: [\n        {\n          role: \"user\",\n          content: \"Remove the filler words.\",\n        },\n      ],\n      source: \"typed\",\n    },\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl -X POST \"https://api.diffio.ai/v2/projects/73118d99-36cf-4039-8005-b962d522fff7/generations/73c84c4a-c1ca-5485-b396-171ab632d4b7/transcript/assistant/turns\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"messages\": [\n      {\n        \"role\": \"user\",\n        \"content\": \"Remove the filler words.\"\n      }\n    ],\n    \"source\": \"typed\"\n  }'"}]}}, "/projects/{project_id}/generations/{generation_id}/transcript/assistant/turns/{turn_id}": {"get": {"operationId": "getTranscriptAssistantTurn", "summary": "Get an edit assistant turn", "tags": ["Transcripts"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TranscriptAssistantTurn"}, "example": {"object": "transcript_assistant_turn", "id": "8f14e45fceea4e6b9d2c7a1b3e5d9f02", "project_id": "73118d99-36cf-4039-8005-b962d522fff7", "generation_id": "73c84c4a-c1ca-5485-b396-171ab632d4b7", "status": "complete", "created_at": "2026-11-13T00:40:00.418207Z", "completed_at": "2026-11-13T00:40:06.902114Z", "error": null, "reply": "No filler words were found in this transcript.", "proposals": [], "moments": [], "unclear_word_ids": []}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "One assistant turn: ``processing`` until it is ``complete``, with the answer's ``reply``, ``proposals``, ``moments`` and the rest, or ``failed``, with ``error`` (``code`` and a ``message`` for the person).", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "generation_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "turn_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "security": [{"apiKey": []}], "x-required-scope": "generations:read", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\nturn = client.assistant.get_turn(\n    \"73118d99-36cf-4039-8005-b962d522fff7\",\n    \"73c84c4a-c1ca-5485-b396-171ab632d4b7\",\n    \"8f14e45fceea4e6b9d2c7a1b3e5d9f02\",\n)\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst turn =\n  await client.assistant.getTurn(\n    \"73118d99-36cf-4039-8005-b962d522fff7\",\n    \"73c84c4a-c1ca-5485-b396-171ab632d4b7\",\n    \"8f14e45fceea4e6b9d2c7a1b3e5d9f02\",\n  )\n"}, {"lang": "Shell", "label": "cURL", "source": "curl \"https://api.diffio.ai/v2/projects/73118d99-36cf-4039-8005-b962d522fff7/generations/73c84c4a-c1ca-5485-b396-171ab632d4b7/transcript/assistant/turns/8f14e45fceea4e6b9d2c7a1b3e5d9f02\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\""}]}}, "/projects/{project_id}/generations/{generation_id}/transcript/assistant/feedback": {"post": {"operationId": "createTranscriptAssistantFeedback", "summary": "Send feedback about the edit assistant", "tags": ["Transcripts"], "responses": {"201": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TranscriptAssistantFeedback"}, "example": {"object": "transcript_assistant_feedback", "project_id": "73118d99-36cf-4039-8005-b962d522fff7", "generation_id": "73c84c4a-c1ca-5485-b396-171ab632d4b7", "id": "kV2mR8sTq4LwZ1bN6yPd", "turn_id": "8f14e45fceea4e6b9d2c7a1b3e5d9f02", "emailed": true}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Send the Diffio team a bug report or an idea about the edit assistant, with the conversation if wanted.  ``kind`` is bug, feature or other; ``message`` is the person's note; ``turn_id`` names the turn it is about, if any. ``include_conversation`` attaches ``conversation``: the chat as shown, each turn's ``role`` and ``text`` and, for an answer, any ``error`` shown and what its proposals were (``title``, ``changes``, ``accepted``, ``skipped``, ``examples``). Limited to a few reports an hour per end user.", "parameters": [{"name": "project_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "generation_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TranscriptAssistantFeedbackCreate"}, "example": {"kind": "feature", "message": "I want to cut the intro down to ten seconds.", "turn_id": "8f14e45fceea4e6b9d2c7a1b3e5d9f02", "include_conversation": true, "conversation": [{"role": "user", "text": "Shorten the intro to ten seconds."}, {"role": "assistant", "text": "I can remove or replace words, but I cannot trim a passage to a set length."}], "source": "panel"}}}}, "security": [{"apiKey": []}], "x-required-scope": "generations:write", "x-codeSamples": [{"lang": "Shell", "label": "cURL", "source": "curl -X POST \"https://api.diffio.ai/v2/projects/73118d99-36cf-4039-8005-b962d522fff7/generations/73c84c4a-c1ca-5485-b396-171ab632d4b7/transcript/assistant/feedback\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"kind\": \"feature\",\n    \"message\": \"I want to cut the intro down to ten seconds.\",\n    \"turn_id\": \"8f14e45fceea4e6b9d2c7a1b3e5d9f02\",\n    \"include_conversation\": true,\n    \"conversation\": [\n      {\n        \"role\": \"user\",\n        \"text\": \"Shorten the intro to ten seconds.\"\n      },\n      {\n        \"role\": \"assistant\",\n        \"text\": \"I can remove or replace words, but I cannot trim a passage to a set length.\"\n      }\n    ],\n    \"source\": \"panel\"\n  }'"}]}}, "/usage": {"get": {"operationId": "getUsage", "summary": "Get usage", "tags": ["Usage"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Usage"}, "example": {"object": "usage", "start": "2026-11-01T00:00:00Z", "end": "2026-11-13T00:34:08.146003Z", "end_user": null, "generations": 2, "billable_seconds": 120, "list_price_usd": 0.25, "by_model": [{"model": "diffio-4.7-flash", "generations": 1, "billable_seconds": 60, "list_price_usd": 0.0833}, {"model": "diffio-4.7-pro", "generations": 1, "billable_seconds": 60, "list_price_usd": 0.1667}]}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "What the account's generations used in a period, in total and by model, at list price.  ``start`` and ``end`` bound the generations' creation time (default: this calendar month so far, UTC). The ``Diffio-End-User`` header narrows the report to one end user, which is how a product built on this API meters its own customers. Only finished generations use anything; failed ones are counted and cost nothing.", "parameters": [{"name": "start", "in": "query", "required": false, "schema": {"type": "string"}, "description": "ISO 8601 start of the period (default: the start of this month, UTC)."}, {"name": "end", "in": "query", "required": false, "schema": {"type": "string"}, "description": "ISO 8601 end of the period (default: now)."}, {"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "security": [{"apiKey": []}], "x-required-scope": "usage:read", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\nusage = client.usage.get()\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst usage = await client.usage.get()\n"}, {"lang": "Shell", "label": "cURL", "source": "curl \"https://api.diffio.ai/v2/usage\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\""}]}}, "/webhooks/portal": {"post": {"operationId": "openWebhookPortal", "summary": "Open the webhook portal", "tags": ["Webhooks"], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookPortal"}, "example": {"object": "webhook_portal", "url": "https://app.svix.com/login#key=REDACTED", "event_types": ["export.failed", "export.ready", "generation.completed", "generation.failed", "generation.stems_failed", "generation.stems_ready", "project.failed", "project.ready", "transcript_assistant_turn.completed", "transcript_assistant_turn.failed"]}}}}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Open the account's webhook portal, where endpoints are added, tested and their deliveries read.  The first call turns on the account's webhook events: from then on every state change of the account's projects is sent, whichever key or end user made them (``event_types`` lists them; each event's ``data`` names the resource, with its ``end_user``, so read it again with GET for the rest). Each event comes once, signed by Svix (verify the ``svix-signature`` header with the endpoint's secret); its ``id`` is the same on every retry, so a receiver can ignore one it already handled. The ``url`` is a short-lived login link to the portal: open it at once, and ask for a new one each time. The portal is the account's, so a request with Diffio-End-User is refused (403 ``permission_denied``); 503 ``unavailable`` when webhooks are not set up.", "parameters": [{"name": "Diffio-End-User", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Act for one end user: the request sees and changes only that end user's projects, and a project it creates belongs to them. Without it the request acts for the whole account."}], "security": [{"apiKey": []}], "x-required-scope": "webhooks:write", "x-codeSamples": [{"lang": "Python", "label": "Python", "source": "import os\nfrom diffio import DiffioClient\n\nkey = os.environ[\"DIFFIO_API_KEY\"]\nclient = DiffioClient(api_key=key)\n\nportal = client.webhooks.portal()\n"}, {"lang": "JavaScript", "label": "Node.js", "source": "import { DiffioClient } from \"diffio\"\n\nconst client = new DiffioClient({\n  apiKey: process.env.DIFFIO_API_KEY,\n})\n\nconst portal = await client.webhooks.portal()\n"}, {"lang": "Shell", "label": "cURL", "source": "curl -X POST \"https://api.diffio.ai/v2/webhooks/portal\" \\\n  -H \"Authorization: Bearer $DIFFIO_API_KEY\""}]}}, "/openapi.json": {"get": {"operationId": "getOpenApiDocument", "summary": "Get the API reference", "tags": ["Reference"], "responses": {"200": {"description": "Success."}, "default": {"description": "The request was refused.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "This API's reference as an OpenAPI 3.1 document.", "security": []}}}, "webhooks": {"export.failed": {"post": {"operationId": "webhook_export_failed", "summary": "export.failed", "tags": ["Webhooks"], "description": "An export failed to render. POST the same export again to render it again.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}}, "responses": {"2XX": {"description": "Received. Anything else is retried by Svix with backoff."}}}}, "export.ready": {"post": {"operationId": "webhook_export_ready", "summary": "export.ready", "tags": ["Webhooks"], "description": "An export finished rendering. GET it for its link.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}}, "responses": {"2XX": {"description": "Received. Anything else is retried by Svix with backoff."}}}}, "generation.completed": {"post": {"operationId": "webhook_generation_completed", "summary": "generation.completed", "tags": ["Webhooks"], "description": "A generation finished and its result is ready. data.kind is restore, or edit for a transcript edit.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}}, "responses": {"2XX": {"description": "Received. Anything else is retried by Svix with backoff."}}}}, "generation.failed": {"post": {"operationId": "webhook_generation_failed", "summary": "generation.failed", "tags": ["Webhooks"], "description": "A generation failed. data.error_code is its ResourceError code; GET it for the message.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}}, "responses": {"2XX": {"description": "Received. Anything else is retried by Svix with backoff."}}}}, "generation.stems_failed": {"post": {"operationId": "webhook_generation_stems_failed", "summary": "generation.stems_failed", "tags": ["Webhooks"], "description": "A finished generation's separated tracks could not be prepared (stems_status failed).", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}}, "responses": {"2XX": {"description": "Received. Anything else is retried by Svix with backoff."}}}}, "generation.stems_ready": {"post": {"operationId": "webhook_generation_stems_ready", "summary": "generation.stems_ready", "tags": ["Webhooks"], "description": "A finished generation's separated tracks are ready: its mix and exports can use them (stems_status ready).", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}}, "responses": {"2XX": {"description": "Received. Anything else is retried by Svix with backoff."}}}}, "project.failed": {"post": {"operationId": "webhook_project_failed", "summary": "project.failed", "tags": ["Webhooks"], "description": "A project's upload could not be prepared. GET it for the error.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}}, "responses": {"2XX": {"description": "Received. Anything else is retried by Svix with backoff."}}}}, "project.ready": {"post": {"operationId": "webhook_project_ready", "summary": "project.ready", "tags": ["Webhooks"], "description": "A project's upload was prepared; its generations start.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}}, "responses": {"2XX": {"description": "Received. Anything else is retried by Svix with backoff."}}}}, "transcript_assistant_turn.completed": {"post": {"operationId": "webhook_transcript_assistant_turn_completed", "summary": "transcript_assistant_turn.completed", "tags": ["Webhooks"], "description": "An assistant turn was answered. GET it for the answer.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}}, "responses": {"2XX": {"description": "Received. Anything else is retried by Svix with backoff."}}}}, "transcript_assistant_turn.failed": {"post": {"operationId": "webhook_transcript_assistant_turn_failed", "summary": "transcript_assistant_turn.failed", "tags": ["Webhooks"], "description": "An assistant turn failed. GET it for the error.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}}, "responses": {"2XX": {"description": "Received. Anything else is retried by Svix with backoff."}}}}}, "components": {"securitySchemes": {"apiKey": {"type": "http", "scheme": "bearer", "description": "A Diffio API key: Authorization: Bearer <key>."}}, "schemas": {"Error": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "Stable, snake_case; branch on this, not on the message. Every code, with its HTTP status, what it means and whether to retry (also as x-error-codes): assistant_unavailable (503): The edit assistant is unavailable. Retry with exponential backoff; quote request_id if it keeps happening. conflict (409): Another request changed or revoked the same share at the same time, and the later one won. Read the resource again, then retry with what it now says. edit_not_queued (503): The edit could not be queued; nothing was billed. Retry the same request shortly (after a second or more, backing off). export_not_found (404): No export of the generation has that id. Do not retry unchanged: fix the request first. generation_in_progress (409): A generation of the project is still running; details.generation_ids names them. Retry once they finish. generation_not_found (404): No generation of the project has that id. Do not retry unchanged: fix the request first. generation_start_failed (500): The generation was created but could not be started. Retry with exponential backoff; quote request_id if it keeps happening. generation_unavailable (409): The project or the API key was removed while it ran. Do not retry: this will not change. idempotency_key_conflict (409): The Idempotency-Key was used for a different request. Use a new key for a different request. insufficient_credit (402): The prepaid balance does not cover the most this could bill. Retry once the account can pay (add credit or a payment method in the dashboard). internal_error (500, 502): Diffio could not complete the request. Retry with exponential backoff; quote request_id if it keeps happening. invalid_api_key (401): The API key is not valid. Do not retry unchanged: fix the request first. invalid_field (400): A body field is not valid, details.field names it when it is one field (for an edit, words that change nothing are invalid_field with field words). Do not retry unchanged: fix the request first. invalid_header (400): A header (Idempotency-Key or Diffio-End-User) is too long. Do not retry unchanged: fix the request first. invalid_json (400): The body is not a JSON object. Do not retry unchanged: fix the request first. invalid_parameter (400): A query parameter is not valid; details.parameter names it. Do not retry unchanged: fix the request first. invalid_request (400): The request is malformed in a way no more specific code names. Do not retry unchanged: fix the request first. leveling_not_available (409): Leveling cannot be applied to this generation. Retry without leveling. method_not_allowed (405): The route does not take this method; Allow names those it does. Do not retry unchanged: fix the request first. missing_api_key (401): No API key was sent. Do not retry unchanged: fix the request first. missing_field (400): A required body field is missing; details.field names it. Do not retry unchanged: fix the request first. needs_payment_method (402): The free credit is used up and the account has no card. Retry once the account can pay (add credit or a payment method in the dashboard). not_available (409): Never, for this resource: it failed, it will never have what the request needs, or its project is being deleted. details.transcription_status says the transcript's state where it matters. Do not retry: this will not change. not_editable (409): This result's transcript cannot be edited: it is not a finished Pro result that kept what an edit needs, or shortening (tighten) was asked of a video project. Do not retry: this will not change. not_found (404): What the path names does not exist. Do not retry unchanged: fix the request first. not_ready (409): Not yet: what the request needs is still being made (a generation still running, separated tracks or a transcript still being prepared). details.generation_status or details.transcription_status says which. Retry the same request shortly (after a second or more, backing off). payload_too_large (413): The request is too large. Do not retry unchanged: fix the request first. payment_failed (402): The account's last payment failed. Retry once the account can pay (add credit or a payment method in the dashboard). payment_required (402): The account cannot start this work. Retry once the account can pay (add credit or a payment method in the dashboard). permission_denied (403): The key is not active, or lacks the scope or the read or write permission this route needs. Do not retry with this key: use a key with the right scope. project_exists (409): A project with that id already exists. Read the resource again, then retry with what it now says. project_not_found (404): No project of this account (and end user, with Diffio-End-User) has that id. Do not retry unchanged: fix the request first. rate_limited (429): Too many requests of this kind in a short time. Retry later, backing off. revision_conflict (409): A save named a revision that is no longer current; details.current_revision is the current one. Read the resource again, then retry with what it now says. route_not_found (404): No version-two route has that path. Do not retry unchanged: fix the request first. share_not_found (404): No share has that id, or it was revoked. Do not retry: this will not change. too_many_exports (409): Four exports of this generation are already rendering. Retry once one of them finishes. transcript_assistant_turn_not_found (404): No assistant turn has that id. Do not retry unchanged: fix the request first. transcript_draft_too_large (413): A draft's data is over 900,000 bytes as JSON. Do not retry unchanged: fix the request first. transcript_not_found (404): A finished generation has no stored transcript (results made before transcripts were kept). Do not retry: this will not change. transcript_unreadable (422): The generation's stored transcript cannot be read. Do not retry: this will not change. unauthenticated (401): The request could not be authenticated. Do not retry unchanged: fix the request first. unavailable (503): A service the request needs is unavailable. Retry with exponential backoff; quote request_id if it keeps happening. unknown_model (400): model names no Diffio model; details.models lists them. Do not retry unchanged: fix the request first. unsupported_media_type (415): The file type cannot be restored. Do not retry unchanged: fix the request first. upload_already_received (409): The project's file has already been uploaded. Do not retry: this will not change. upload_missing (409): The upload has not completed yet. Finish the upload, then retry. upload_too_large (413): The file is larger than the upload limit. Do not retry unchanged: fix the request first. usage_limit_reached (402): The account reached the monthly usage limit it set. Retry after raising the limit, or next month. usage_period_too_large (400): The usage period has too many generations for one report. Ask for a shorter period. video_not_available (409): An mp4 was asked for and the project has no video. Retry with an audio format."}, "message": {"type": "string"}, "request_id": {"type": ["string", "null"], "description": "Quote this when asking Diffio about a request."}, "details": {"type": "object", "properties": {"current_revision": {"type": "string", "description": "With revision_conflict: the revision to send now (always a string, like every revision)."}, "transcription_status": {"type": ["string", "null"], "description": "With a transcript refusal: the generation's transcription_status when it was read."}, "generation_status": {"type": "string", "description": "With not_ready or not_available from an edit or the assistant: the generation's status."}, "field": {"type": "string", "description": "With missing_field or invalid_field: the body field at fault."}, "parameter": {"type": "string", "description": "With invalid_parameter: the query parameter at fault."}}}}}}, "x-error-codes": [{"code": "assistant_unavailable", "status": [503], "meaning": "The edit assistant is unavailable.", "retry": "Retry with exponential backoff; quote request_id if it keeps happening."}, {"code": "conflict", "status": [409], "meaning": "Another request changed or revoked the same share at the same time, and the later one won.", "retry": "Read the resource again, then retry with what it now says."}, {"code": "edit_not_queued", "status": [503], "meaning": "The edit could not be queued; nothing was billed.", "retry": "Retry the same request shortly (after a second or more, backing off)."}, {"code": "export_not_found", "status": [404], "meaning": "No export of the generation has that id.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "generation_in_progress", "status": [409], "meaning": "A generation of the project is still running; details.generation_ids names them.", "retry": "Retry once they finish."}, {"code": "generation_not_found", "status": [404], "meaning": "No generation of the project has that id.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "generation_start_failed", "status": [500], "meaning": "The generation was created but could not be started.", "retry": "Retry with exponential backoff; quote request_id if it keeps happening."}, {"code": "generation_unavailable", "status": [409], "meaning": "The project or the API key was removed while it ran.", "retry": "Do not retry: this will not change."}, {"code": "idempotency_key_conflict", "status": [409], "meaning": "The Idempotency-Key was used for a different request.", "retry": "Use a new key for a different request."}, {"code": "insufficient_credit", "status": [402], "meaning": "The prepaid balance does not cover the most this could bill.", "retry": "Retry once the account can pay (add credit or a payment method in the dashboard)."}, {"code": "internal_error", "status": [500, 502], "meaning": "Diffio could not complete the request.", "retry": "Retry with exponential backoff; quote request_id if it keeps happening."}, {"code": "invalid_api_key", "status": [401], "meaning": "The API key is not valid.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "invalid_field", "status": [400], "meaning": "A body field is not valid, details.field names it when it is one field (for an edit, words that change nothing are invalid_field with field words).", "retry": "Do not retry unchanged: fix the request first."}, {"code": "invalid_header", "status": [400], "meaning": "A header (Idempotency-Key or Diffio-End-User) is too long.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "invalid_json", "status": [400], "meaning": "The body is not a JSON object.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "invalid_parameter", "status": [400], "meaning": "A query parameter is not valid; details.parameter names it.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "invalid_request", "status": [400], "meaning": "The request is malformed in a way no more specific code names.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "leveling_not_available", "status": [409], "meaning": "Leveling cannot be applied to this generation.", "retry": "Retry without leveling."}, {"code": "method_not_allowed", "status": [405], "meaning": "The route does not take this method; Allow names those it does.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "missing_api_key", "status": [401], "meaning": "No API key was sent.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "missing_field", "status": [400], "meaning": "A required body field is missing; details.field names it.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "needs_payment_method", "status": [402], "meaning": "The free credit is used up and the account has no card.", "retry": "Retry once the account can pay (add credit or a payment method in the dashboard)."}, {"code": "not_available", "status": [409], "meaning": "Never, for this resource: it failed, it will never have what the request needs, or its project is being deleted. details.transcription_status says the transcript's state where it matters.", "retry": "Do not retry: this will not change."}, {"code": "not_editable", "status": [409], "meaning": "This result's transcript cannot be edited: it is not a finished Pro result that kept what an edit needs, or shortening (tighten) was asked of a video project.", "retry": "Do not retry: this will not change."}, {"code": "not_found", "status": [404], "meaning": "What the path names does not exist.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "not_ready", "status": [409], "meaning": "Not yet: what the request needs is still being made (a generation still running, separated tracks or a transcript still being prepared). details.generation_status or details.transcription_status says which.", "retry": "Retry the same request shortly (after a second or more, backing off)."}, {"code": "payload_too_large", "status": [413], "meaning": "The request is too large.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "payment_failed", "status": [402], "meaning": "The account's last payment failed.", "retry": "Retry once the account can pay (add credit or a payment method in the dashboard)."}, {"code": "payment_required", "status": [402], "meaning": "The account cannot start this work.", "retry": "Retry once the account can pay (add credit or a payment method in the dashboard)."}, {"code": "permission_denied", "status": [403], "meaning": "The key is not active, or lacks the scope or the read or write permission this route needs.", "retry": "Do not retry with this key: use a key with the right scope."}, {"code": "project_exists", "status": [409], "meaning": "A project with that id already exists.", "retry": "Read the resource again, then retry with what it now says."}, {"code": "project_not_found", "status": [404], "meaning": "No project of this account (and end user, with Diffio-End-User) has that id.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "rate_limited", "status": [429], "meaning": "Too many requests of this kind in a short time.", "retry": "Retry later, backing off."}, {"code": "revision_conflict", "status": [409], "meaning": "A save named a revision that is no longer current; details.current_revision is the current one.", "retry": "Read the resource again, then retry with what it now says."}, {"code": "route_not_found", "status": [404], "meaning": "No version-two route has that path.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "share_not_found", "status": [404], "meaning": "No share has that id, or it was revoked.", "retry": "Do not retry: this will not change."}, {"code": "too_many_exports", "status": [409], "meaning": "Four exports of this generation are already rendering.", "retry": "Retry once one of them finishes."}, {"code": "transcript_assistant_turn_not_found", "status": [404], "meaning": "No assistant turn has that id.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "transcript_draft_too_large", "status": [413], "meaning": "A draft's data is over 900,000 bytes as JSON.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "transcript_not_found", "status": [404], "meaning": "A finished generation has no stored transcript (results made before transcripts were kept).", "retry": "Do not retry: this will not change."}, {"code": "transcript_unreadable", "status": [422], "meaning": "The generation's stored transcript cannot be read.", "retry": "Do not retry: this will not change."}, {"code": "unauthenticated", "status": [401], "meaning": "The request could not be authenticated.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "unavailable", "status": [503], "meaning": "A service the request needs is unavailable.", "retry": "Retry with exponential backoff; quote request_id if it keeps happening."}, {"code": "unknown_model", "status": [400], "meaning": "model names no Diffio model; details.models lists them.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "unsupported_media_type", "status": [415], "meaning": "The file type cannot be restored.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "upload_already_received", "status": [409], "meaning": "The project's file has already been uploaded.", "retry": "Do not retry: this will not change."}, {"code": "upload_missing", "status": [409], "meaning": "The upload has not completed yet.", "retry": "Finish the upload, then retry."}, {"code": "upload_too_large", "status": [413], "meaning": "The file is larger than the upload limit.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "usage_limit_reached", "status": [402], "meaning": "The account reached the monthly usage limit it set.", "retry": "Retry after raising the limit, or next month."}, {"code": "usage_period_too_large", "status": [400], "meaning": "The usage period has too many generations for one report.", "retry": "Ask for a shorter period."}, {"code": "video_not_available", "status": [409], "meaning": "An mp4 was asked for and the project has no video.", "retry": "Retry with an audio format."}]}, "ResourceError": {"type": "object", "required": ["code", "message"], "description": "Why a resource (a project, generation, export or assistant turn) failed: the error of every status resource.", "properties": {"code": {"type": "string", "description": "Stable and snake_case, always present: an unknown failure is generation_failed, project_failed, export_failed or internal_error. Every code, with the resources that report it, what it means and what to do (also as x-error-codes): assistant_timeout (transcript_assistant_turn): The assistant did not finish the turn. Ask again, perhaps something narrower. assistant_unavailable (transcript_assistant_turn): The assistant is unavailable. Ask again shortly. cancelled (generation): The generation was cancelled. Create a new generation. edit_not_queued (generation): The transcript edit could not be queued. Send the edit again (edited_transcript in a playback grant holds its words). expired (generation): The generation waited too long to start. Create a new generation. export_failed (export): Rendering the export failed. Ask for the export again (POST .../exports renders it again). generation_failed (generation): The generation failed for another reason. Create a new generation; quote its id if it keeps happening. generation_invalid (generation): The generation's request could not be started. Create a new generation. insufficient_credit (generation): The prepaid balance did not cover the recording. Retry once the account can pay (add credit or a payment method in the dashboard). internal_error (transcript_assistant_turn): The turn failed on Diffio's side. Ask again. invalid_field (transcript_assistant_turn): The assistant could not read the request. Do not retry unchanged: fix the request first. invalid_input (generation): The recording could not be read as it is. Do not retry this file: export the recording again. job_missing (generation): The generation's job was lost before it started. Create a new generation. media_processing_failed (project): The upload could not be prepared. Create a new project with another export of the recording. media_too_long (generation): The recording is longer than the length limit. Do not retry this file: upload a shorter one. needs_payment_method (generation): The account had no card once the recording's length was known. Retry once the account can pay (add credit or a payment method in the dashboard). no_speech_detected (generation): No speech was heard in the recording. Do not retry this file: it has no speech to restore. not_editable (transcript_assistant_turn): The result stopped being editable while the turn ran. Do not retry: this will not change. payment_failed (generation): The account's last payment failed. Retry once the account can pay (add credit or a payment method in the dashboard). permission_denied (transcript_assistant_turn): The account may not use the assistant. Do not retry: this will not change. preprocessing_failed (generation): The upload could not be prepared. Do not retry this file: upload another export of it. project_failed (project): The project failed for another reason. Create a new project. project_not_found (transcript_assistant_turn): The project went away while the turn ran. Do not retry: this will not change. rate_limited (transcript_assistant_turn): Too many assistant requests in a few minutes, or a day's worth of use. Ask again later. restoration_failed (generation): Restoring the audio failed. Create a new generation. restored_video_failed (generation): Making the restored video (mp4) failed. Create a new generation. start_failed (generation): The generation could not be started. Create a new generation. timed_out (generation): The generation did not finish in the time allowed. Create a new generation. transcription_failed (generation): Transcribing the recording failed on Diffio's side. Create a new generation (error.retryable is true). unauthenticated (transcript_assistant_turn): The turn's owner could not be named. Ask again. unsupported_model (generation): The model the generation named is not served. Create a new generation with a model from GET /v2/models. upload_missing (generation): The project's upload never arrived. Upload the file again (POST .../upload), then create a new generation. usage_limit_reached (generation): The account reached its monthly usage limit. Create a new generation after raising the limit."}, "message": {"type": "string", "description": "Words a person can be shown; never a code."}}, "x-error-codes": [{"code": "assistant_timeout", "resources": ["transcript_assistant_turn"], "meaning": "The assistant did not finish the turn.", "retry": "Ask again, perhaps something narrower."}, {"code": "assistant_unavailable", "resources": ["transcript_assistant_turn"], "meaning": "The assistant is unavailable.", "retry": "Ask again shortly."}, {"code": "cancelled", "resources": ["generation"], "meaning": "The generation was cancelled.", "retry": "Create a new generation."}, {"code": "edit_not_queued", "resources": ["generation"], "meaning": "The transcript edit could not be queued.", "retry": "Send the edit again (edited_transcript in a playback grant holds its words)."}, {"code": "expired", "resources": ["generation"], "meaning": "The generation waited too long to start.", "retry": "Create a new generation."}, {"code": "export_failed", "resources": ["export"], "meaning": "Rendering the export failed.", "retry": "Ask for the export again (POST .../exports renders it again)."}, {"code": "generation_failed", "resources": ["generation"], "meaning": "The generation failed for another reason.", "retry": "Create a new generation; quote its id if it keeps happening."}, {"code": "generation_invalid", "resources": ["generation"], "meaning": "The generation's request could not be started.", "retry": "Create a new generation."}, {"code": "insufficient_credit", "resources": ["generation"], "meaning": "The prepaid balance did not cover the recording.", "retry": "Retry once the account can pay (add credit or a payment method in the dashboard)."}, {"code": "internal_error", "resources": ["transcript_assistant_turn"], "meaning": "The turn failed on Diffio's side.", "retry": "Ask again."}, {"code": "invalid_field", "resources": ["transcript_assistant_turn"], "meaning": "The assistant could not read the request.", "retry": "Do not retry unchanged: fix the request first."}, {"code": "invalid_input", "resources": ["generation"], "meaning": "The recording could not be read as it is.", "retry": "Do not retry this file: export the recording again."}, {"code": "job_missing", "resources": ["generation"], "meaning": "The generation's job was lost before it started.", "retry": "Create a new generation."}, {"code": "media_processing_failed", "resources": ["project"], "meaning": "The upload could not be prepared.", "retry": "Create a new project with another export of the recording."}, {"code": "media_too_long", "resources": ["generation"], "meaning": "The recording is longer than the length limit.", "retry": "Do not retry this file: upload a shorter one."}, {"code": "needs_payment_method", "resources": ["generation"], "meaning": "The account had no card once the recording's length was known.", "retry": "Retry once the account can pay (add credit or a payment method in the dashboard)."}, {"code": "no_speech_detected", "resources": ["generation"], "meaning": "No speech was heard in the recording.", "retry": "Do not retry this file: it has no speech to restore."}, {"code": "not_editable", "resources": ["transcript_assistant_turn"], "meaning": "The result stopped being editable while the turn ran.", "retry": "Do not retry: this will not change."}, {"code": "payment_failed", "resources": ["generation"], "meaning": "The account's last payment failed.", "retry": "Retry once the account can pay (add credit or a payment method in the dashboard)."}, {"code": "permission_denied", "resources": ["transcript_assistant_turn"], "meaning": "The account may not use the assistant.", "retry": "Do not retry: this will not change."}, {"code": "preprocessing_failed", "resources": ["generation"], "meaning": "The upload could not be prepared.", "retry": "Do not retry this file: upload another export of it."}, {"code": "project_failed", "resources": ["project"], "meaning": "The project failed for another reason.", "retry": "Create a new project."}, {"code": "project_not_found", "resources": ["transcript_assistant_turn"], "meaning": "The project went away while the turn ran.", "retry": "Do not retry: this will not change."}, {"code": "rate_limited", "resources": ["transcript_assistant_turn"], "meaning": "Too many assistant requests in a few minutes, or a day's worth of use.", "retry": "Ask again later."}, {"code": "restoration_failed", "resources": ["generation"], "meaning": "Restoring the audio failed.", "retry": "Create a new generation."}, {"code": "restored_video_failed", "resources": ["generation"], "meaning": "Making the restored video (mp4) failed.", "retry": "Create a new generation."}, {"code": "start_failed", "resources": ["generation"], "meaning": "The generation could not be started.", "retry": "Create a new generation."}, {"code": "timed_out", "resources": ["generation"], "meaning": "The generation did not finish in the time allowed.", "retry": "Create a new generation."}, {"code": "transcription_failed", "resources": ["generation"], "meaning": "Transcribing the recording failed on Diffio's side.", "retry": "Create a new generation (error.retryable is true)."}, {"code": "unauthenticated", "resources": ["transcript_assistant_turn"], "meaning": "The turn's owner could not be named.", "retry": "Ask again."}, {"code": "unsupported_model", "resources": ["generation"], "meaning": "The model the generation named is not served.", "retry": "Create a new generation with a model from GET /v2/models."}, {"code": "upload_missing", "resources": ["generation"], "meaning": "The project's upload never arrived.", "retry": "Upload the file again (POST .../upload), then create a new generation."}, {"code": "usage_limit_reached", "resources": ["generation"], "meaning": "The account reached its monthly usage limit.", "retry": "Create a new generation after raising the limit."}]}, "Model": {"type": "object", "required": ["id", "object", "status", "label", "served_by", "price_per_hour_usd"], "properties": {"id": {"type": "string"}, "object": {"const": "model"}, "status": {"enum": ["hosted", "alias", "retired"], "description": "alias always means the current model of its tier; retired names still run."}, "label": {"type": ["string", "null"]}, "served_by": {"type": "string", "description": "The hosted model a request naming this model runs on."}, "price_per_hour_usd": {"type": "number"}}}, "ModelList": {"type": "object", "required": ["object", "data", "next_cursor"], "properties": {"object": {"const": "list"}, "data": {"type": "array", "items": {"$ref": "#/components/schemas/Model"}}, "next_cursor": {"type": ["string", "null"], "description": "Pass as cursor to read the next page; null on the last."}}}, "ProjectCreate": {"type": "object", "required": ["file_name"], "properties": {"file_name": {"type": "string", "description": "The recording's name, with an audio or video extension."}, "content_type": {"type": "string"}, "size_bytes": {"type": "integer", "description": "The file's size, when known."}, "metadata": {"type": "object", "additionalProperties": {"type": "string"}}, "generation": {"type": "object", "required": ["model"], "description": "Request the first restore now: it is created queued (latest_generation) and starts by itself once the upload is ready. Same fields as POST .../generations.", "properties": {"model": {"type": "string", "description": "A model id from GET /v2/models, for example diffio-flash."}, "sampling": {"type": "object", "description": "Advanced sampling overrides."}, "label": {"type": "string", "description": "Your own name for this generation, for example \"Take 2\"."}}}}}, "Project": {"type": "object", "required": ["content_type", "created_at", "duration_seconds", "end_user", "error", "file_name", "generation_count", "has_video", "id", "latest_generation", "metadata", "object", "share_id", "size_bytes", "status", "updated_at", "video_preview_status"], "properties": {"id": {"type": "string"}, "object": {"const": "project"}, "status": {"enum": ["awaiting_upload", "preparing", "ready", "failed"], "description": "awaiting_upload until the file arrives, preparing while it is probed, then ready."}, "file_name": {"type": ["string", "null"]}, "content_type": {"type": ["string", "null"]}, "size_bytes": {"type": ["integer", "null"]}, "duration_seconds": {"type": ["number", "null"], "description": "Known once the project is ready."}, "has_video": {"type": "boolean"}, "end_user": {"type": ["string", "null"], "description": "Your own id for the person this project belongs to: the Diffio-End-User header it was created with."}, "metadata": {"type": "object", "additionalProperties": {"type": "string"}}, "generation_count": {"type": "integer"}, "video_preview_status": {"enum": ["preparing", "ready", "failed", null], "description": "A video project's picture-only playback stream (video_hls in a playback grant); null for audio."}, "share_id": {"type": ["string", "null"], "description": "The id of the project's share link while it is published."}, "latest_generation": {"description": "The project's newest generation, or null when it has none.", "anyOf": [{"$ref": "#/components/schemas/Generation"}, {"type": "null"}]}, "created_at": {"type": ["string", "null"], "format": "date-time"}, "updated_at": {"type": ["string", "null"], "format": "date-time"}, "error": {"description": "Why the upload could not be prepared, once status is failed (code media_processing_failed, or project_failed when unknown); null otherwise.", "anyOf": [{"$ref": "#/components/schemas/ResourceError"}, {"type": "null"}]}}}, "ProjectWithUpload": {"type": "object", "required": ["content_type", "created_at", "duration_seconds", "end_user", "error", "file_name", "generation_count", "has_video", "id", "latest_generation", "metadata", "object", "share_id", "size_bytes", "status", "updated_at", "video_preview_status", "upload"], "properties": {"id": {"type": "string"}, "object": {"const": "project"}, "status": {"enum": ["awaiting_upload", "preparing", "ready", "failed"], "description": "awaiting_upload until the file arrives, preparing while it is probed, then ready."}, "file_name": {"type": ["string", "null"]}, "content_type": {"type": ["string", "null"]}, "size_bytes": {"type": ["integer", "null"]}, "duration_seconds": {"type": ["number", "null"], "description": "Known once the project is ready."}, "has_video": {"type": "boolean"}, "end_user": {"type": ["string", "null"], "description": "Your own id for the person this project belongs to: the Diffio-End-User header it was created with."}, "metadata": {"type": "object", "additionalProperties": {"type": "string"}}, "generation_count": {"type": "integer"}, "video_preview_status": {"enum": ["preparing", "ready", "failed", null], "description": "A video project's picture-only playback stream (video_hls in a playback grant); null for audio."}, "share_id": {"type": ["string", "null"], "description": "The id of the project's share link while it is published."}, "latest_generation": {"description": "The project's newest generation, or null when it has none.", "anyOf": [{"$ref": "#/components/schemas/Generation"}, {"type": "null"}]}, "created_at": {"type": ["string", "null"], "format": "date-time"}, "updated_at": {"type": ["string", "null"], "format": "date-time"}, "error": {"description": "Why the upload could not be prepared, once status is failed (code media_processing_failed, or project_failed when unknown); null otherwise.", "anyOf": [{"$ref": "#/components/schemas/ResourceError"}, {"type": "null"}]}, "upload": {"type": ["object", "null"], "description": "How to send the file: requests.start once, requests.part for each part, then requests.complete. Each request names its method, URL, headers and JSON body; values in braces are yours to fill in. The project then becomes ready by itself (the edge reports the upload); POST .../upload/complete is optional and only makes readiness immediate. Null on an Idempotency-Key repeat once the file arrived.", "required": ["upload_session_id", "edge_base_url", "upload_token", "part_size_bytes", "max_bytes", "expires_at", "requests"], "properties": {"upload_session_id": {"type": "string"}, "edge_base_url": {"type": "string"}, "upload_token": {"type": "string", "description": "Sent as Authorization: Bearer on every upload request."}, "part_size_bytes": {"type": "integer", "description": "Every part but the last is exactly this long."}, "max_bytes": {"type": "integer"}, "expires_at": {"type": "string", "description": "When upload_token stops working; POST .../upload renews it."}, "requests": {"type": "object", "required": ["start", "part", "complete", "abort"], "properties": {"start": {"$ref": "#/components/schemas/UploadRequest"}, "part": {"$ref": "#/components/schemas/UploadRequest"}, "complete": {"$ref": "#/components/schemas/UploadRequest"}, "abort": {"$ref": "#/components/schemas/UploadRequest"}}}}}}}, "UploadRequest": {"type": "object", "required": ["method", "url", "headers", "body", "returns", "description"], "properties": {"method": {"enum": ["POST", "PUT"]}, "url": {"type": "string", "description": "Absolute; part's has {part_number} (from 1) and {upload_id}."}, "headers": {"type": "object", "additionalProperties": {"type": "string"}}, "body": {"type": ["object", "null"], "description": "The JSON body, with {upload_id}, {part_number} and {etag} to fill in; null when the body is not JSON (a part's body is its raw bytes)."}, "returns": {"type": "array", "items": {"type": "string"}, "description": "Fields of the JSON answer to keep."}, "description": {"type": "string"}}}, "ProjectList": {"type": "object", "required": ["object", "data", "next_cursor"], "properties": {"object": {"const": "list"}, "data": {"type": "array", "items": {"$ref": "#/components/schemas/Project"}}, "next_cursor": {"type": ["string", "null"], "description": "Pass as cursor to read the next page; null on the last."}}}, "ProjectDeleted": {"type": "object", "required": ["id", "object", "deleted", "deleted_generations", "deleted_media_objects"], "properties": {"id": {"type": "string"}, "object": {"const": "project"}, "deleted": {"const": true}, "deleted_generations": {"type": "integer"}, "deleted_media_objects": {"type": "integer"}}}, "GenerationCreate": {"type": "object", "required": ["model"], "properties": {"model": {"type": "string", "description": "A model id from GET /v2/models, for example diffio-flash."}, "sampling": {"type": "object", "description": "Advanced sampling overrides."}, "label": {"type": "string", "description": "Your own name for this generation, for example \"Take 2\"."}}}, "TranscriptEditCreate": {"type": "object", "properties": {"words": {"type": "array", "description": "The whole transcript after editing, in order: the words of GET .../transcript as they are, with your changes. A kept word carries the start and end it has in the generation's transcript; a new word carries neither (or null). The editor's shape, which the assistant takes, is accepted as it is: a word with text '' is removed, and a word with changed or regenerate true is said again (its start and end are ignored). Left out, the stored transcript as it is: an edit that only shortens long pauses (tighten.max_pause_seconds); without it, words that change nothing are 400 invalid_field (field words).", "items": {"$ref": "#/components/schemas/TranscriptWordInput"}}, "tighten": {"type": "object", "description": "Cut the recording shorter (audio only).", "properties": {"close_removed_gaps": {"type": "boolean", "description": "Close the silence removed words leave."}, "max_pause_seconds": {"type": ["number", "null"], "description": "Shorten every longer pause to this length (0.25 to 3)."}}}, "request_id": {"type": "string", "description": "Your own id for this edit, returned as edit.request_id."}}}, "TranscriptEditEstimate": {"type": "object", "required": ["object", "project_id", "generation_id", "edit_count", "max_windows", "window_seconds", "max_billable_seconds"], "properties": {"object": {"const": "transcript_edit_estimate"}, "project_id": {"type": "string"}, "generation_id": {"type": "string"}, "edit_count": {"type": ["integer", "null"], "description": "Runs of changed words."}, "max_windows": {"type": ["integer", "null"], "description": "The most windows the edit may restore."}, "window_seconds": {"type": "integer", "description": "Seconds of audio each window restores (billed at most)."}, "max_billable_seconds": {"type": "integer", "description": "The most the edit could bill, with no minimum (0 when it only cuts): the credit held while it runs, 30 s a window and never more than the recording. It bills the audio its windows restore, which may be less."}}}, "Generation": {"type": "object", "required": ["created_at", "duration_seconds", "edit", "error", "files_available", "id", "kind", "label", "model", "object", "price_per_hour_usd", "project_id", "quality_score", "queue", "requested_model", "source_generation_id", "stage", "stage_progress", "status", "stems_status", "substituted", "transcript_editable", "transcription_status", "updated_at", "warnings"], "properties": {"id": {"type": "string"}, "object": {"const": "generation"}, "project_id": {"type": "string"}, "status": {"enum": ["queued", "processing", "complete", "failed"]}, "model": {"type": ["string", "null"], "description": "The model that ran."}, "requested_model": {"type": ["string", "null"], "description": "The model name the request gave."}, "substituted": {"type": "boolean", "description": "True when the requested model is retired and another model served it."}, "price_per_hour_usd": {"type": ["number", "null"], "description": "List price charged: the lower of the requested and served models'."}, "stage": {"type": ["string", "null"], "description": "Where a running generation is: pending, preparing, transcribing, queued, starting, downloading, decoding, restoring, finalizing, uploading; then complete or failed."}, "stage_progress": {"type": ["object", "null"], "description": "How far the current stage is, while running and once a worker reports it; null otherwise. Each field is present only once the worker has reported it.", "properties": {"overall_percent": {"type": "number", "minimum": 0, "maximum": 100, "description": "How far the whole generation is."}, "stage_percent": {"type": "number", "minimum": 0, "maximum": 100, "description": "How far this stage is."}, "bytes_done": {"type": "number", "description": "Bytes moved so far in a downloading or uploading stage."}, "bytes_total": {"type": "number", "description": "Bytes the stage moves in all."}, "available_through_seconds": {"type": "number", "description": "How much of the result can already be played (hls_master in a playback grant), in seconds."}, "duration_seconds": {"type": "number", "description": "The recording's length, in seconds."}}}, "queue": {"type": ["object", "null"], "description": "While the generation waits for a worker; null otherwise.", "required": ["position", "connected_workers", "idle_workers", "busy_workers", "wait_reason", "message"], "properties": {"position": {"type": ["integer", "null"], "description": "Jobs ahead of this one."}, "connected_workers": {"type": ["integer", "null"], "description": "Workers connected to the queue."}, "idle_workers": {"type": ["integer", "null"]}, "busy_workers": {"type": ["integer", "null"]}, "wait_reason": {"type": ["string", "null"], "description": "Why it waits: all_busy (every worker is busy), no_workers (none is connected) or next_in_line."}, "message": {"type": "string", "description": "Why it waits, in words a person can be shown."}}}, "warnings": {"type": "array", "description": "Things about the recording the caller should know; the generation still runs. code unsupported_language: the transcript has words in languages (ISO 639-1 codes, most words first) the model cannot restore.", "items": {"type": "object", "required": ["code", "message"], "properties": {"code": {"enum": ["unsupported_language"]}, "languages": {"type": "array", "items": {"type": "string"}}, "message": {"type": "string"}}}}, "label": {"type": ["string", "null"], "description": "The label given when the generation was created."}, "kind": {"enum": ["restore", "edit"], "description": "restore: the whole recording was restored. edit: a transcript edit of another generation, which restored again only the windows around the edited words."}, "source_generation_id": {"type": ["string", "null"], "description": "For an edit, the generation it edited."}, "edit": {"type": ["object", "null"], "description": "For an edit: what it asked for and how far it is.", "required": ["edit_count", "max_windows", "windows", "windows_done", "retry_windows", "ranges", "billable_seconds", "cut_seconds", "request_id", "language", "tighten"], "properties": {"edit_count": {"type": ["integer", "null"], "description": "Runs of changed words."}, "max_windows": {"type": ["integer", "null"], "description": "The most windows the edit may restore."}, "windows": {"type": ["integer", "null"], "description": "Windows the worker is restoring, or restored."}, "windows_done": {"type": ["integer", "null"]}, "retry_windows": {"type": ["integer", "null"], "description": "Windows that held only words said again unchanged after an earlier edit said them (Try again): not billed. Null until it finishes."}, "ranges": {"type": "array", "description": "The restored windows, in seconds on the recording.", "items": {"type": "object", "properties": {"start": {"type": "number"}, "end": {"type": "number"}}}}, "billable_seconds": {"type": ["integer", "null"], "description": "Seconds billed: the audio the windows restored again, each second once where windows overlap and never more than the recording (30 for each window at most, none for windows holding only Try again words). Null until it finishes."}, "cut_seconds": {"type": ["number", "null"], "description": "How much shorter tighten made the recording."}, "request_id": {"type": ["string", "null"]}, "language": {"type": ["string", "null"]}, "tighten": {"type": ["object", "null"], "description": "How the edit cut the recording shorter, as POST .../edits asked; null when it did not.", "required": ["close_removed_gaps", "max_pause_seconds"], "properties": {"close_removed_gaps": {"type": "boolean", "description": "Close the silence removed words leave."}, "max_pause_seconds": {"type": ["number", "null"], "description": "Every longer pause was shortened to this length; null when pauses were left as they were."}}}}}, "transcript_editable": {"type": "boolean", "description": "True once this result's transcript can be edited (POST .../edits): a finished result of a Pro model that kept what an edit needs."}, "duration_seconds": {"type": ["number", "null"]}, "quality_score": {"type": ["number", "null"], "description": "Estimated speech quality of the result, 1 to 5."}, "transcription_status": {"enum": ["preparing", "ready", "failed", null], "description": "The word-timed transcript (GET .../transcript), in the words of stems_status and video_preview_status: preparing (409 not_ready until it is ready), ready, or failed (it will never exist: 409 not_available); null when the generation reports no transcription."}, "files_available": {"type": "array", "items": {"type": "string"}, "description": "The names of the files that exist so far, sorted; GET .../media gives a URL for each (and for the project's original upload). hls_master is playable while the generation is still running; video (a video project's restored mp4) is listed once it has been made."}, "error": {"description": "Set when the generation failed; null otherwise. code is one of the generation codes of ResourceError (restoration_failed, no_speech_detected, media_too_long, transcription_failed, cancelled, timed_out, edit_not_queued, upload_missing, needs_payment_method, expired, restored_video_failed, ...; generation_failed when Diffio recorded no known cause); message is a sentence to show.", "anyOf": [{"allOf": [{"$ref": "#/components/schemas/ResourceError"}, {"type": "object", "required": ["retryable", "explanation"], "properties": {"retryable": {"type": "boolean", "description": "True when a new generation of the project may succeed."}, "explanation": {"type": ["string", "null"], "description": "A further sentence about the failure, when Diffio recorded one; never a code."}}}]}, {"type": "null"}]}, "stems_status": {"enum": ["preparing", "ready", "failed", null], "description": "Separated speech and background tracks, which arrive after the result: preparing (exports and the mix are 409 not_ready), ready, or failed (409 not_available: they never arrived in the time allowed, or the generation failed); null when the generation has none to report."}, "created_at": {"type": ["string", "null"], "format": "date-time"}, "updated_at": {"type": ["string", "null"], "format": "date-time"}}}, "GenerationList": {"type": "object", "required": ["object", "data", "next_cursor"], "properties": {"object": {"const": "list"}, "data": {"type": "array", "items": {"$ref": "#/components/schemas/Generation"}}, "next_cursor": {"type": ["string", "null"], "description": "Pass as cursor to read the next page; null on the last."}}}, "GenerationMedia": {"type": "object", "required": ["object", "project_id", "generation_id", "status", "files", "base_url", "expires_at", "preview_seconds"], "properties": {"object": {"const": "generation_media"}, "project_id": {"type": "string"}, "generation_id": {"type": "string"}, "status": {"enum": ["queued", "processing", "complete", "failed"]}, "files": {"type": "object", "additionalProperties": {"type": "string", "format": "uri"}, "description": "Name to URL, present once the file exists: original, audio (the restored audio), video (a video project's restored video, an mp4), audio_mixed, hls_master, hls_restored, hls_original, waveform_restored, waveform_original, transcript, stems_manifest, metadata, video_hls, edited_transcript. Add ?download=<file name> to a URL to have a browser save it under that name. With a preview, only the files a preview plays are named: never audio, video, audio_mixed, transcript, metadata or edited_transcript. hls_master is the adaptive stream; for a video project it carries the picture (video_hls) with the restored and original audio, and its picture plays once the project's video_preview_status is ready. Everything a playlist or stems_manifest names inside is a path relative to that file's own URL: the manifest's chunks (chunks/000000.flac), masters and picture stream (videoPlaybackKey, ../../../../video/hls/index.m3u8); the speech leveling curve, when the result has one, is leveling-v1.bin beside the manifest."}, "base_url": {"type": "string", "description": "The URL every entry in files starts with. A player needs nothing else from it: entries inside the HLS playlists are relative and resolve against each playlist's own URL."}, "expires_at": {"type": "string", "format": "date-time", "description": "When every URL in this grant stops working; ask again for new ones."}, "preview_seconds": {"type": ["integer", "null"], "description": "The playback limit this grant carries, or null for the whole recording."}}}, "GenerationMix": {"type": "object", "required": ["object", "project_id", "generation_id", "background_gain", "leveling", "revision", "stems_revision"], "properties": {"object": {"const": "generation_mix"}, "project_id": {"type": "string"}, "generation_id": {"type": "string"}, "background_gain": {"type": "number", "minimum": 0, "maximum": 1, "description": "How much of the background to keep: 0 is speech only, 1 is all of it."}, "leveling": {"type": "boolean", "description": "Boost quiet speech."}, "revision": {"type": "string", "description": "Opaque; changes with every save and when the separated tracks are prepared again. Send it back unchanged when saving to refuse a save over a newer mix; never take it apart."}, "stems_revision": {"type": ["string", "null"], "description": "The separated tracks this balance is for: the revision their manifest (files.stems_manifest) names. A player compares it with the manifest it plays to tell a balance of tracks prepared since."}}}, "GenerationMixSave": {"type": "object", "required": ["background_gain"], "properties": {"background_gain": {"type": "number", "minimum": 0, "maximum": 1}, "leveling": {"type": "boolean", "description": "Left out, the saved setting is kept."}, "revision": {"type": "string", "description": "The revision last read. With it a save over a newer mix is refused (409 revision_conflict, with details.current_revision); without it the save replaces whatever is saved."}}}, "GenerationExportCreate": {"type": "object", "required": ["artifact", "format"], "properties": {"artifact": {"enum": ["speech", "background", "mix", "both", "original"]}, "inline": {"type": "boolean", "description": "A file to play in a page instead of download: mp3 or mp4 only, and required for original."}, "format": {"enum": ["wav", "mp3", "m4a", "mp4", "zip"], "description": "both comes as zip; mp4 needs a project with video."}, "background_gain": {"type": "number", "minimum": 0, "maximum": 1, "description": "For a mix. Left out, the saved mix's balance and leveling are used."}, "leveling": {"type": "boolean"}, "file_name": {"type": "string", "description": "Name the download (without its extension)."}}}, "GenerationExport": {"type": "object", "required": ["object", "id", "project_id", "generation_id", "status", "artifact", "format", "background_gain", "leveling", "inline", "url", "error"], "properties": {"object": {"const": "generation_export"}, "id": {"type": "string"}, "project_id": {"type": "string"}, "generation_id": {"type": "string"}, "status": {"enum": ["queued", "processing", "ready", "failed"]}, "artifact": {"type": ["string", "null"]}, "format": {"type": ["string", "null"]}, "background_gain": {"type": ["number", "null"]}, "leveling": {"type": "boolean"}, "inline": {"type": "boolean", "description": "True for an export to play in a page: its url plays rather than downloads, and its id differs from the same render's download."}, "url": {"type": ["string", "null"], "description": "Once ready: a download link, or for an inline export a link to play in a page. It expires; GET the export for a new one."}, "error": {"description": "Why the export failed, once status is failed (code export_failed); null otherwise.", "anyOf": [{"$ref": "#/components/schemas/ResourceError"}, {"type": "null"}]}}}, "ProjectSharePublish": {"type": "object", "properties": {"generation_id": {"type": "string", "description": "Pin the share to one finished generation (default: the newest finished). One still running is 409 not_ready; a failed one is 409 not_available. Changing it on a published share stops every URL the share gave before, within a minute."}, "preview_seconds": {"type": "integer", "description": "Limit playback to the start of the recording. Changing it on a published share (or leaving it out after setting it) stops every URL the share gave before, within a minute. Two publications at once never both take effect: the one that started first is refused (409 conflict); the later one stands."}}}, "ProjectShare": {"type": "object", "required": ["object", "id", "project_id", "generation_id", "file_name", "content_type", "created_at", "has_video", "duration_seconds", "preview_seconds", "files", "base_url"], "properties": {"object": {"const": "project_share"}, "id": {"type": "string", "description": "Give this to whoever should listen."}, "project_id": {"type": "string"}, "generation_id": {"type": ["string", "null"]}, "file_name": {"type": ["string", "null"]}, "content_type": {"type": ["string", "null"]}, "created_at": {"type": ["string", "null"], "format": "date-time", "description": "When the share was first published."}, "has_video": {"type": "boolean"}, "duration_seconds": {"type": ["number", "null"]}, "preview_seconds": {"type": ["integer", "null"]}, "files": {"type": "object", "additionalProperties": {"type": "string", "format": "uri"}, "description": "The shared generation's playback files, name to URL, and for a video project its picture-only stream (video_hls); the uploaded original is never shared. The URLs work until the share is revoked or its generation_id or preview_seconds changes; read the share again for current ones. With preview_seconds only the files a preview plays are named. Empty until the project has a finished generation."}, "base_url": {"type": ["string", "null"], "description": "The URL every entry in files starts with. It reaches only the shared generation and, for a video project, its picture stream, so hls_master plays picture and sound in a standard HLS player. Null until the project has a finished generation."}}}, "ProjectShareRevoked": {"type": "object", "required": ["object", "id", "project_id", "deleted"], "properties": {"object": {"const": "project_share"}, "id": {"type": ["string", "null"]}, "project_id": {"type": "string"}, "deleted": {"const": true}}}, "Usage": {"type": "object", "required": ["object", "start", "end", "end_user", "generations", "billable_seconds", "list_price_usd", "by_model"], "properties": {"object": {"const": "usage"}, "start": {"type": ["string", "null"], "format": "date-time"}, "end": {"type": ["string", "null"], "format": "date-time"}, "end_user": {"type": ["string", "null"]}, "generations": {"type": "integer"}, "billable_seconds": {"type": "integer", "description": "Whole seconds billed. A restore bills the recording's length, at least 60 seconds; a transcript edit bills 30 seconds for each window it restored again, with no minimum (nothing for an edit that only cut)."}, "list_price_usd": {"type": "number"}, "by_model": {"type": "array", "items": {"type": "object", "required": ["model", "generations", "billable_seconds", "list_price_usd"], "properties": {"model": {"type": "string"}, "generations": {"type": "integer"}, "billable_seconds": {"type": "integer"}, "list_price_usd": {"type": "number"}}}}}}, "WebhookPortal": {"type": "object", "required": ["object", "url", "event_types"], "properties": {"object": {"const": "webhook_portal"}, "url": {"type": "string", "format": "uri", "description": "A short-lived login link to the account's webhook portal."}, "event_types": {"type": "array", "items": {"type": "string"}, "description": "Every event type the account is sent."}}}, "WebhookEvent": {"type": "object", "required": ["type", "id", "created_at", "data"], "description": "One state change, signed by Svix (svix-id, svix-timestamp and svix-signature headers). It names the resource that changed; read it again with GET for the rest. id is the same on every retry of the event.", "properties": {"type": {"enum": ["export.failed", "export.ready", "generation.completed", "generation.failed", "generation.stems_failed", "generation.stems_ready", "project.failed", "project.ready", "transcript_assistant_turn.completed", "transcript_assistant_turn.failed"]}, "id": {"type": "string", "description": "The event's id: the same however often the event is delivered."}, "created_at": {"type": "string", "format": "date-time"}, "data": {"type": "object", "required": ["object", "id", "project_id", "end_user", "status"], "properties": {"object": {"enum": ["generation", "generation_export", "transcript_assistant_turn", "project"]}, "id": {"type": "string", "description": "The resource's id."}, "project_id": {"type": "string", "description": "Its project (the project's own id for a project event)."}, "generation_id": {"type": "string", "description": "Its generation, for an export or an assistant turn."}, "end_user": {"type": ["string", "null"], "description": "The end user the project belongs to (Diffio-End-User)."}, "status": {"type": "string", "description": "The resource's status now: complete or failed (a generation), ready or failed (an export, a project), complete or failed (an assistant turn)."}, "kind": {"enum": ["restore", "edit"], "description": "A generation's kind (generation events only)."}, "stems_status": {"enum": ["ready", "failed"], "description": "On generation.stems_* only."}, "error_code": {"type": "string", "description": "On generation.failed only: the generation's ResourceError code."}}}}}, "TranscriptWord": {"type": "object", "required": ["id", "text", "start", "end", "probability"], "additionalProperties": true, "description": "One word as GET .../transcript gives it: always its id, text, start, end and probability (null where unknown or untimed), and whatever else the transcriber recorded (speaker, language). One word array goes from GET .../transcript through an editor and the assistant to POST .../edits (and .../edits/estimate) unchanged: send the words back as they are, with your changes (TranscriptWordInput).", "properties": {"id": {"type": "string", "description": "Stable for the transcript: the stored id, else word-{index}."}, "text": {"type": "string", "description": "The word; in a request, '' for a removed word."}, "start": {"type": ["number", "null"], "description": "Seconds on the recording; null for an untimed word."}, "end": {"type": ["number", "null"]}, "probability": {"type": ["number", "null"], "description": "The transcriber's confidence, 0 to 1; null when unknown."}, "speaker": {"type": "string"}, "language": {"type": "string", "description": "The word's language code, when known."}}}, "TranscriptWordInput": {"type": "object", "additionalProperties": true, "anyOf": [{"required": ["text"]}, {"required": ["word"]}], "description": "One word as POST .../edits, .../edits/estimate and the assistant take it: a TranscriptWord as GET .../transcript gave it, with your changes. It needs text (or word, as older clients name it); start and end are optional. text '' marks a removed word (left out of the edit), and changed or regenerate true marks a word to be said again (its start and end are then ignored); any other word with the start and end it has in the transcript is kept as it was, and a word without them is new. Fields the edit does not read are ignored.", "properties": {"id": {"type": "string", "description": "Stable for the transcript: the stored id, else word-{index}."}, "text": {"type": "string", "description": "The word; in a request, '' for a removed word."}, "start": {"type": ["number", "null"], "description": "Seconds on the recording; null for an untimed word."}, "end": {"type": ["number", "null"]}, "probability": {"type": ["number", "null"], "description": "The transcriber's confidence, 0 to 1; null when unknown."}, "speaker": {"type": "string"}, "language": {"type": "string", "description": "The word's language code, when known."}, "word": {"type": "string", "description": "The text, as older clients name it; text wins when both are sent."}, "changed": {"type": "boolean", "description": "True when the word's text was edited, so it is said again as text says."}, "regenerate": {"type": "boolean", "description": "True to say the word again as it is."}}}, "Transcript": {"type": "object", "required": ["object", "project_id", "generation_id", "text", "words", "preview_seconds", "truncated"], "description": "Every word is in the one TranscriptWord shape, whichever format the transcript was stored in.", "properties": {"object": {"const": "transcript"}, "project_id": {"type": "string"}, "generation_id": {"type": "string"}, "text": {"type": "string", "description": "The words as one text: the transcript's stored text, else its words joined by spaces (a preview's words, joined)."}, "words": {"type": "array", "description": "The words in order.", "items": {"$ref": "#/components/schemas/TranscriptWord"}}, "preview_seconds": {"type": ["integer", "null"], "description": "The preview applied (rounded up to whole 4 second segments), or null for the whole."}, "truncated": {"type": "boolean", "description": "True when words after the preview were left out."}}}, "TranscriptDraft": {"type": "object", "required": ["object", "project_id", "generation_id", "revision", "data", "created_at", "updated_at"], "properties": {"object": {"const": "transcript_draft"}, "project_id": {"type": "string"}, "generation_id": {"type": "string"}, "revision": {"type": "string", "description": "Opaque; changes with every save and delete and is never given twice. Present when nothing is saved too: send it back to save or delete."}, "data": {"type": ["object", "null"], "additionalProperties": true, "description": "The JSON object last saved, exactly as it was sent; null when nothing is saved."}, "created_at": {"type": ["string", "null"], "format": "date-time"}, "updated_at": {"type": ["string", "null"], "format": "date-time"}}}, "TranscriptDraftSave": {"type": "object", "required": ["data"], "properties": {"data": {"type": "object", "additionalProperties": true, "description": "Any JSON object: your editor's state. At most 900,000 bytes as JSON."}, "revision": {"type": "string", "description": "The revision last read (GET .../draft gives one even when nothing is saved). A save from another revision is refused (409 revision_conflict, with details.current_revision)."}}}, "TranscriptDraftDeleted": {"type": "object", "required": ["object", "project_id", "generation_id", "deleted", "revision"], "properties": {"object": {"const": "transcript_draft"}, "project_id": {"type": "string"}, "generation_id": {"type": "string"}, "deleted": {"const": true}, "revision": {"type": "string", "description": "The revision of no draft, as of this delete (the current one, unchanged, when nothing was saved): a first save sends it."}}}, "TranscriptAssistantTurnCreate": {"type": "object", "required": ["messages"], "properties": {"messages": {"type": "array", "minItems": 1, "maxItems": 40, "description": "The chat so far; the last is the question.", "items": {"type": "object", "required": ["role", "content"], "properties": {"role": {"enum": ["user", "assistant"]}, "content": {"type": "string", "maxLength": 4000}}}}, "words": {"type": "array", "minItems": 1, "description": "The editor's words as they stand, in order: GET .../transcript's words with your changes. Left out, the stored transcript as it is (the words and ids GET .../transcript gives).", "items": {"allOf": [{"$ref": "#/components/schemas/TranscriptWordInput"}, {"type": "object", "required": ["id"], "properties": {"id": {"type": "string", "maxLength": 128}}}]}}, "selection": {"type": ["object", "null"], "description": "The words the person selected.", "required": ["word_ids"], "properties": {"word_ids": {"type": "array", "items": {"type": "string"}}}}, "playhead_seconds": {"type": ["number", "null"], "description": "Where playback is."}, "source": {"type": "string", "description": "What started the turn, for your analytics (typed, starter:fillers)."}}}, "TranscriptAssistantTurn": {"type": "object", "required": ["object", "id", "project_id", "generation_id", "status", "created_at", "completed_at", "error"], "properties": {"object": {"const": "transcript_assistant_turn"}, "id": {"type": "string"}, "project_id": {"type": "string"}, "generation_id": {"type": "string"}, "status": {"enum": ["processing", "complete", "failed"], "description": "processing until the answer is ready; then complete with the answer fields, or failed with error."}, "created_at": {"type": ["string", "null"], "format": "date-time"}, "completed_at": {"type": ["string", "null"], "format": "date-time"}, "error": {"description": "Why a failed turn failed while it ran (a ResourceError, with a message to show the person); null otherwise. Its code is one of the codes ResourceError's x-error-codes lists for transcript_assistant_turn: rate_limited, assistant_timeout, assistant_unavailable, not_editable, invalid_field, permission_denied, unauthenticated, project_not_found, internal_error (not_editable, invalid_field or project_not_found only if the result changed while it ran: the request and the result are checked before the turn is created).", "anyOf": [{"$ref": "#/components/schemas/ResourceError"}, {"type": "null"}]}, "reply": {"type": "string", "description": "The answer to show the person."}, "proposals": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "title": {"type": "string"}, "icon": {"enum": ["filler", "replace", "rephrase", "mute", "regenerate", "grammar", "cleanup", "insert"]}, "changes": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "kind": {"enum": ["replace", "remove", "insert", "regenerate"]}, "word_ids": {"type": "array", "items": {"type": "string"}, "description": "The words the change covers, in order."}, "before": {"type": "string"}, "after": {"type": "string", "description": "The words after the change; empty for a removal."}, "reason": {"type": "string"}, "start_seconds": {"type": ["number", "null"]}, "end_seconds": {"type": ["number", "null"]}}}}, "windows": {"type": "integer", "description": "Windows this proposal adds to the edit."}, "restore_seconds": {"type": "number", "description": "Seconds of audio this proposal likely adds to what the edit restores again and bills (windows that overlap count once, never more than the recording)."}}}}, "moments": {"type": "array", "items": {"type": "object", "properties": {"start_seconds": {"type": "number"}, "end_seconds": {"type": ["number", "null"]}, "label": {"type": "string"}, "word_id": {"type": ["string", "null"]}}}}, "unclear_word_ids": {"type": "array", "items": {"type": "string"}, "description": "Words a listening pass found hard to understand."}, "speaker_turns": {"type": "array", "items": {"type": "object", "properties": {"word_id": {"type": "string"}, "speaker": {"type": "string"}}}}, "shortening": {"type": ["object", "null"], "description": "A suggested tighten for the edit (audio only).", "properties": {"close_removed_gaps": {"type": "boolean"}, "max_pause_seconds": {"type": ["number", "null"]}, "estimated_seconds": {"type": "number"}, "reason": {"type": "string"}}}, "feedback_offer": {"type": ["object", "null"], "description": "The assistant offers the feedback form.", "properties": {"kind": {"enum": ["bug", "feature", "other"]}, "summary": {"type": "string"}}}, "notices": {"type": "array", "items": {"type": "string"}}, "windows_total": {"type": "integer", "description": "Windows the draft plus every proposal would restore."}}}, "TranscriptAssistantFeedbackCreate": {"type": "object", "properties": {"kind": {"enum": ["bug", "feature", "other"]}, "message": {"type": "string", "maxLength": 4000}, "turn_id": {"type": "string", "description": "The assistant turn the report is about, if any."}, "include_conversation": {"type": "boolean"}, "conversation": {"type": "array", "maxItems": 80, "items": {"type": "object", "properties": {"role": {"enum": ["user", "assistant"]}, "text": {"type": "string"}, "error": {"type": "string"}, "moments": {"type": "integer"}, "proposals": {"type": "array", "items": {"type": "object"}}}}}, "page_url": {"type": "string"}, "user_agent": {"type": "string"}, "source": {"type": "string", "description": "Where the report was written, for example panel."}}}, "TranscriptAssistantFeedback": {"type": "object", "required": ["object", "project_id", "generation_id", "id", "turn_id", "emailed"], "properties": {"object": {"const": "transcript_assistant_feedback"}, "project_id": {"type": "string"}, "generation_id": {"type": "string"}, "id": {"type": "string"}, "turn_id": {"type": ["string", "null"]}, "emailed": {"type": "boolean"}}}}}}