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

  1. Your server → Diffio API: PUT /projects/{id}/share, API key
  2. Diffio API → Your server: share id, and playback files
  3. Your server → Listener: link with the share id, your page, your domain
  4. Listener → Diffio API: GET /shares/{share_id}, no API key
  5. Diffio API → Listener: files.audio, files.hls_master, current URLs
  6. Your server → Diffio API: DELETE /projects/{id}/share, URLs stop within a minute
The share id is the only thing a listener holds; your API key never leaves your server.

Build it

  1. 1

    Publish the share

    The share plays the project's newest finished generation, or the one you pin with generation_id. preview_seconds limits it to the start of the recording. Publishing again keeps the same share id.

  2. 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. 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.

What you get

What the share link plays (files.audio)

A listener with the link hears the restored recording; the uploaded original is never part of a share. How this recording was restored.
  • A share id you can put in any link, such as https://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-…
Terminal
share id Hq7cTnWm3RkZpY2vB
plays https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/restored.mp3
after revoke 404 share_not_found

API 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.

Report an issue with this page