Skip to content

For AI agents: every API docs page in one plain-text file is at /docs/llms-full.txt, and the documentation index is at /llms.txt. This page is available as Markdown at https://diffio.ai/docs/api-reference/publish-project-share.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

Publish a project's share

Publishes a project's public playback share (or updates what an existing share plays), returning a 17-character share id readable without an API key at Get a share.

PUT https://api.diffio.ai/v2/projects/{project_id}/share

  • Key scope: projects:write
  • Auth header:Authorization: Bearer <apiKey>
  • Body: JSON

Request

Send {} to share the project's newest finished generation in full, or pass optional generation_id and preview_seconds.

Path parameters

FieldTypeRequiredDescription
#project_idstringRequired: YesUnique identifier of the project.

Headers

FieldTypeRequiredDescription
#Diffio-End-UserstringRequired: NoOptional end-user identifier (up to 128 characters). Scopes the request to that end user's projects; omit to act across the whole account.

Body fields

FieldTypeRequiredDescription
#generation_idstringRequired: NoOptional finished generation ID to pin the share to; omit to follow the project's newest finished generation automatically.
#preview_secondsintegerRequired: NoOptional playback limit in seconds, from 4 to 3600 (rounded up to whole 4-second segments); omits full-length download files from files.

Request

import os
from diffio import DiffioClient

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

share = client.shares.publish(
    "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
)

Response

Returns the published project_share with its public id and playback files.

Success: 200OK.

Response fields

FieldTypePresentDescription
#objectstringAlwaysResource type, always "project_share".project_share
#idstringAlwaysPublic 17-character share identifier passed to GET /shares/{share_id}.
#generation_idstring | nullAlwaysIdentifier of the shared generation, or null until the project has a finished generation.
#filesobjectAlwaysMap of shared playback artifact names to signed media URLs (never includes original); {} until a generation finishes.
#base_urlstring | nullAlwaysURL prefix shared by every entry in files (plays hls_master in standard HLS players), or null until a generation finishes.
Other response fields7 fields
FieldTypePresentDescription
#project_idstringAlwaysIdentifier of the shared project.
#file_namestring | nullAlwaysRecording filename on the project, or null.
#content_typestring | nullAlwaysRecording MIME type, or null.
#created_atstring | nullAlwaysISO 8601 UTC timestamp when the share was first published, or null.
#has_videobooleanAlwaysTrue when the project contains video.
#duration_secondsnumber | nullAlwaysDuration of the shared recording in seconds, or null.
#preview_secondsinteger | nullAlwaysPlayback cap in seconds (rounded up to whole 4-second segments), or null when the full recording is shared.

Response 200OK.

Response: key fields
{
  "object": "project_share",
  "id": "Hq7cTnWm3RkZpY2vB",
  "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f",
  "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"
  }
}

Return codes

  • 200OK.Share published or updated and returned with playback URLs.
  • 400Bad request.
    Malformed JSON, or 2 more causes
    • Malformed JSON
    • Invalid generation_id or preview_seconds outside 4 to 3600
    • Oversized header
    invalid_jsoninvalid_fieldinvalid_header
  • 403Forbidden: the key lacks permission.Key is inactive or lacks projects:write. permission_denied
  • 404Not found.Project not found, or pinned generation_id not found on this project. project_not_foundgeneration_not_found
  • 409Conflict: see error.code for which one.
    Pinned generation_id is still running, or 2 more causes
    • Pinned generation_id is still running
    • Pinned generation failed or project is being deleted
    • A concurrent publish or revoke won (code conflict)
    not_readynot_available
  • 401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint
    • 401Unauthorized: the API key is missing or invalid. Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).
    • 405Client error. HTTP method not supported on this path; check the Allow header (code method_not_allowed).

Example error response

Errors are JSON: an error object with code, message and request_id. An unrecognized key returns 401Unauthorized: the API key is missing or invalid.:

Error response
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "request_id": "dead773b60e148fd9e22d680a22fa701"
  }
}

Notes

  • A share never exposes the uploaded original recording or the project's other generations; with preview_seconds set, full-length audio, audio_mixed, video, transcript, and metadata are omitted too.
  • Republishing with identical generation_id and preview_seconds keeps existing URLs working; changing either (or republishing after a revoke) invalidates old URLs within about 60 seconds while keeping the same share id.
  • Publishing and serving shares is free.

Report an issue with this page