> For the complete documentation index, see [llms.txt](https://diffio.ai/llms.txt). This page is also available as HTML at https://diffio.ai/docs/developers/guides/share-a-result/.

# 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. 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. 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)**

```html
<!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 `404` `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.

**share.py**

```python
"""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)
```

**share.mjs**

```javascript
// Publish a share of a finished project, read it the way a public page does, then revoke it.
// node share.mjs PROJECT_ID
import { DiffioApiError, DiffioClient } from "diffio";

const projectId = process.argv[2];
const client = new DiffioClient(); // reads DIFFIO_API_KEY

// 1. Publish: plays the project's newest finished generation.
const share = await client.shares.publish(projectId);
console.log("share id", share.id);

// 2. The public read: GET /shares/{share_id}, sent without the API key.
const shown = await client.shares.getPublic(share.id);
console.log("plays", shown.files.audio);

// 3. Revoke, then the share id no longer resolves.
await client.shares.revoke(projectId);
try {
  await client.shares.getPublic(share.id);
} catch (error) {
  if (!(error instanceof DiffioApiError)) throw error;
  console.log("after revoke", error.status, error.code);
}
```

**cURL: share.sh**

```bash
API="https://api.diffio.ai/v2"
PROJECT_ID="$1"
CURL="curl -sS --connect-timeout 10 --max-time 60"

# 1. Publish (with your key).
SHARE_ID=$($CURL -X PUT "$API/projects/$PROJECT_ID/share" \
  -H "Authorization: Bearer $DIFFIO_API_KEY" \
  -H "Content-Type: application/json" -d '{}' | jq -r .id)

# 2. The public read: no Authorization header.
$CURL "$API/shares/$SHARE_ID" | jq -r .files.audio

# 3. Revoke (with your key).
$CURL -X DELETE "$API/projects/$PROJECT_ID/share" \
  -H "Authorization: Bearer $DIFFIO_API_KEY"
```

## What you get

Uploaded

[Uploaded (MP3)](https://diffio.ai/media/recording-rescue/original.mp3)

What the share link plays (files.audio)

[What the share link plays (files.audio) (MP3)](https://diffio.ai/media/recording-rescue/flash.mp3)

**A listener with the link hears the restored recording; the uploaded original is never part of a share. [How this recording was restored](https://diffio.ai/recording-rescue/).**

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

```bash
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

- PUT [Publish a project's share](https://diffio.ai/docs/api-reference/publish-project-share/) (`/projects/{project_id}/share`): Pin a generation or a preview length.
- GET [Get a share](https://diffio.ai/docs/api-reference/get-share/) (`/shares/{share_id}`): The public read: fields and files.
- GET [Get a project's share](https://diffio.ai/docs/api-reference/get-project-share/) (`/projects/{project_id}/share`): The project's share, with your key.
- DELETE [Revoke a project's share](https://diffio.ai/docs/api-reference/revoke-project-share/) (`/projects/{project_id}/share`): Stop sharing.

## Related pages

- Previous: [Separate speech and background](https://diffio.ai/docs/developers/guides/separate-speech-and-background/): Stems → mix → export
- Next: [Restore a video and stream it](https://diffio.ai/docs/developers/guides/restore-video-and-stream/): Video upload → HLS stream
