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/developers/guides/share-a-result.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

Share a restored result with a public link
Give anyone a link that plays a restored recording, read it from a public page without an API key, and turn it off when you are done.
How it works
- Your server → Diffio API:
PUT /projects/{id}/share, API key - Diffio API → Your server:
share id, and playback files - Your server → Listener:
link with the share id, your page, your domain - Listener → Diffio API:
GET /shares/{share_id}, no API key - Diffio API → Listener:
files.audio, files.hls_master, current URLs - Your server → Diffio API:
DELETE /projects/{id}/share, URLs stop within a minute
Build it
- 1
Publish the share
The share plays the project's newest finished generation, or the one you pin with
generation_id.preview_secondslimits it to the start of the recording. Publishing again keeps the same shareid. - 2
Read it with no API key
GET /shares/{share_id}needs no key and allows any origin, so a public page can call it directly. Read it each time a listener opens the page; it answers with current URLs. It never includes the uploaded original.listen.html (public page)<!doctype html> <title>Listen</title> <audio id="player" controls></audio> <script type="module"> // listen.html?share=<share id>: no API key on this page; the share id is the only credential. const shareId = new URLSearchParams(location.search).get("share"); const response = await fetch(`https://api.diffio.ai/v2/shares/${encodeURIComponent(shareId)}`); if (response.ok) { const share = await response.json(); document.querySelector("#player").src = share.files.audio; } else { document.body.textContent = "This recording is no longer shared."; } </script> - 3
Revoke it
After a revoke the share id answers
404Not found.share_not_found, and URLs it gave out stop working within about a minute. Publishing again later never revives an old URL.
The complete script
Pass the id of a project with a finished generation.
"""Publish a share of a finished project, read it the way a public page does, then revoke it.
python share.py PROJECT_ID
"""
import sys
from diffio import DiffioApiError, DiffioClient
project_id = sys.argv[1]
client = DiffioClient() # reads DIFFIO_API_KEY
# 1. Publish: plays the project's newest finished generation.
share = client.shares.publish(project_id)
print("share id", share.id)
# 2. The public read: GET /shares/{share_id}, sent without the API key.
public = client.shares.get_public(share.id)
print("plays", public.files["audio"])
# 3. Revoke, then the share id no longer resolves.
client.shares.revoke(project_id)
try:
client.shares.get_public(share.id)
except DiffioApiError as error:
print("after revoke", error.status, error.code)What you get
Uploaded
What the share link plays (files.audio)
- A share
idyou can put in any link, such ashttps://your-app.example/listen.html?share=Hq7cTnWm3RkZpY2vB. - A page that plays the restored audio for anyone with the link, without your API key.
- One call that turns it off.
Output of python share.py 62f62565-…
share id Hq7cTnWm3RkZpY2vB
plays https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/restored.mp3
after revoke 404 share_not_foundAPI reference
- PUTPublish a project's share (
/projects/{project_id}/share): Pin a generation or a preview length. - GETGet a share (
/shares/{share_id}): The public read: fields and files. - GETGet a project's share (
/projects/{project_id}/share): The project's share, with your key. - DELETERevoke a project's share (
/projects/{project_id}/share): Stop sharing.