Stories

A Story is a multi-track timeline that arranges your generated clips into a single piece of audio. Each story is made up of story items — references to generations placed at a start time on a track, with optional trimming, per-clip volume, and a pinned effect version (take). When you are happy with the arrangement you can export the whole story as one mixed WAV file. These endpoints back the Stories tab in PeachDesk Voice Studio. All paths are proxied by PeachDesk under the /api/voice base path and require your PeachDesk API key in the X-API-Key header.

Audio rendering and mixing run on PeachDesk’s GPU infrastructure. You arrange clips by referencing generation IDs — there are no local files or models to manage. Select engines, voices, and effects from the Voice Studio UI; everything is served from PeachDesk’s servers.

Authentication

Every request must include your PeachDesk API key in the X-API-Key header (an interactive session token in Authorization: Bearer also works — see Authentication):

X-API-Key: bibha_your_api_key

Data shapes

object

Show properties

string

required

Unique story identifier.

string

required

Story name.

string | null

required

Optional description.

string (date-time)

required

Creation timestamp.

string (date-time)

required

Last update timestamp.

integer

default:"0"

Number of items in the story.

object

Show properties

string

required

Story item identifier.

string

required

Parent story ID.

string

required

The generation this clip references.

string | null

Pinned generation version (take), if any.

integer

required

Clip start position on the timeline, in milliseconds.

integer

default:"0"

Track index the clip sits on.

integer

default:"0"

Milliseconds trimmed from the start of the clip.

integer

default:"0"

Milliseconds trimmed from the end of the clip.

number

default:"1.0"

Per-clip linear gain (0.0 = silent, 1.0 = original, max 2.0).

string

required

Voice profile ID used by the generation.

string

required

Voice profile display name.

string

required

Source text of the generation.

string

required

Language code.

string

required

Path to the rendered audio served by PeachDesk.

number

required

Clip duration in seconds.

integer | null

required

Generation seed.

string | null

required

Instruction/style prompt, if used.

string | null

Engine used for the generation.

string (date-time)

required

Item creation timestamp.

string (date-time)

required

Underlying generation timestamp.

GenerationVersionResponse[] | null

Available versions (takes) for this generation.

string | null

The version currently used for playback/export.

List stories

List all stories, ordered for the Stories tab. Returns an array of StoryResponse objects (with item_count).

curl https://app.peachdeskai.com/api/voice/stories \
  -H "X-API-Key: $PEACHDESK_API_KEY"

[
  {
    "id": "story_a1b2c3",
    "name": "Episode 1 — Intro",
    "description": "Cold open and theme",
    "created_at": "2026-06-20T10:00:00Z",
    "updated_at": "2026-06-21T14:30:00Z",
    "item_count": 4
  }
]

Create a story

Create a new, empty story.

string

required

Story name (1–100 characters).

string | null

Optional description (up to 500 characters).

Returns the created StoryResponse. Invalid input returns 400.

curl -X POST https://app.peachdeskai.com/api/voice/stories \
  -H "X-API-Key: $PEACHDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Episode 1 — Intro", "description": "Cold open and theme"}'

{
  "id": "story_a1b2c3",
  "name": "Episode 1 — Intro",
  "description": "Cold open and theme",
  "created_at": "2026-06-20T10:00:00Z",
  "updated_at": "2026-06-20T10:00:00Z",
  "item_count": 0
}

Get a story

Fetch a single story with all of its items expanded.

string

required

The story to retrieve.

Returns a StoryDetailResponse (the story fields plus an items array of StoryItemDetail). Returns 404 if the story does not exist.

curl https://app.peachdeskai.com/api/voice/stories/story_a1b2c3 \
  -H "X-API-Key: $PEACHDESK_API_KEY"

{
  "id": "story_a1b2c3",
  "name": "Episode 1 — Intro",
  "description": "Cold open and theme",
  "created_at": "2026-06-20T10:00:00Z",
  "updated_at": "2026-06-21T14:30:00Z",
  "items": [
    {
      "id": "item_001",
      "story_id": "story_a1b2c3",
      "generation_id": "gen_xyz",
      "version_id": null,
      "start_time_ms": 0,
      "track": 0,
      "trim_start_ms": 0,
      "trim_end_ms": 0,
      "volume": 1.0,
      "profile_id": "voice_nova",
      "profile_name": "Nova",
      "text": "Welcome back to the show.",
      "language": "en",
      "audio_path": "/audio/gen_xyz.wav",
      "duration": 2.4,
      "seed": 42,
      "instruct": null,
      "engine": "studio-tts",
      "created_at": "2026-06-20T10:05:00Z",
      "generation_created_at": "2026-06-20T09:50:00Z",
      "versions": [],
      "active_version_id": null
    }
  ]
}

Update a story

Update a story’s name and/or description.

string

required

The story to update.

string

required

New name (1–100 characters).

string | null

New description (up to 500 characters).

Returns the updated StoryResponse. Returns 404 if the story does not exist.

curl

curl -X PUT https://app.peachdeskai.com/api/voice/stories/story_a1b2c3 \
  -H "X-API-Key: $PEACHDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Episode 1 — Final", "description": "Locked cut"}'

Delete a story

Permanently delete a story and its item arrangement. The underlying generations are not deleted.

string

required

The story to delete.

Returns {"message": "Story deleted successfully"}. Returns 404 if the story does not exist.

curl

curl -X DELETE https://app.peachdeskai.com/api/voice/stories/story_a1b2c3 \
  -H "X-API-Key: $PEACHDESK_API_KEY"

Story items

Story items are individual clips placed on the timeline. Each item references a generation and carries its own position, track, trim, volume, and pinned version.

Add an item

Add a generation to a story as a new clip.

string

required

The story to add to.

string

required

The generation to place on the timeline.

integer | null

Start position in milliseconds. If omitted, the clip is appended after the existing items.

integer | null

default:"0"

Track index for the clip.

Returns the created StoryItemDetail. Returns 404 if the story or generation is not found.

curl

curl -X POST https://app.peachdeskai.com/api/voice/stories/story_a1b2c3/items \
  -H "X-API-Key: $PEACHDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"generation_id": "gen_xyz", "start_time_ms": 0, "track": 0}'

Remove an item

Remove a clip from the story. The underlying generation is not deleted.

string

required

The parent story.

string

required

The story item to remove.

Returns {"message": "Item removed successfully"}. Returns 404 if the item is not found.

curl

curl -X DELETE https://app.peachdeskai.com/api/voice/stories/story_a1b2c3/items/item_001 \
  -H "X-API-Key: $PEACHDESK_API_KEY"

Update item timecodes (batch)

Update the start time of multiple items at once — used when dragging several clips on the timeline.

string

required

The parent story.

array

required

A list of timecode updates. Each entry has:

Show StoryItemUpdateTime

string

required

The generation whose item is being moved.

integer

required

New start position in milliseconds (≥ 0).

Returns {"message": "Item timecodes updated successfully"}. Returns 400 on an invalid update request.

curl

curl -X PUT https://app.peachdeskai.com/api/voice/stories/story_a1b2c3/items/times \
  -H "X-API-Key: $PEACHDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "updates": [
          {"generation_id": "gen_xyz", "start_time_ms": 0},
          {"generation_id": "gen_abc", "start_time_ms": 2500}
        ]
      }'

Reorder items

Reorder items by generation ID and recalculate their timecodes so clips sit back-to-back in the given order.

string

required

The parent story.

string[]

required

The generation IDs in their new order (at least one). All IDs must belong to this story.

Returns the reordered array of StoryItemDetail. Returns 400 if any generation ID does not belong to the story.

curl

curl -X PUT https://app.peachdeskai.com/api/voice/stories/story_a1b2c3/items/reorder \
  -H "X-API-Key: $PEACHDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"generation_ids": ["gen_abc", "gen_xyz"]}'

Move an item

Move a single clip to a new position and/or track.

string

required

The parent story.

string

required

The story item to move.

integer

required

New start position in milliseconds (≥ 0).

integer

default:"0"

Destination track index.

Returns the updated StoryItemDetail. Returns 404 if the item is not found.

curl

curl -X PUT https://app.peachdeskai.com/api/voice/stories/story_a1b2c3/items/item_001/move \
  -H "X-API-Key: $PEACHDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_time_ms": 5000, "track": 1}'

Trim an item

Trim audio from the start and/or end of a clip without changing the underlying generation.

string

required

The parent story.

string

required

The story item to trim.

integer

required

Milliseconds to remove from the start (≥ 0).

integer

required

Milliseconds to remove from the end (≥ 0).

Returns the updated StoryItemDetail. Returns 404 if the item is missing or the trim values are invalid.

curl

curl -X PUT https://app.peachdeskai.com/api/voice/stories/story_a1b2c3/items/item_001/trim \
  -H "X-API-Key: $PEACHDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trim_start_ms": 200, "trim_end_ms": 150}'

Set item volume

Set a clip’s per-clip volume as a linear gain.

string

required

The parent story.

string

required

The story item to adjust.

number

required

Linear gain between 0.0 (silent) and 2.0. 1.0 is the original level.

Gain is capped at 2.0 so an over-aggressive boost can’t clip the mix or blow out the exported file. Use small increments and listen back.

Returns the updated StoryItemDetail. Returns 404 if the item is not found.

curl

curl -X PUT https://app.peachdeskai.com/api/voice/stories/story_a1b2c3/items/item_001/volume \
  -H "X-API-Key: $PEACHDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"volume": 0.8}'

Split an item

Split a clip at a given time, producing two adjacent clips on the same track.

string

required

The parent story.

string

required

The story item to split.

integer

required

The split point in milliseconds, relative to the timeline (≥ 0).

Returns an array of StoryItemDetail (the two resulting clips). Returns 404 if the item is not found or the split point is invalid.

curl

curl -X POST https://app.peachdeskai.com/api/voice/stories/story_a1b2c3/items/item_001/split \
  -H "X-API-Key: $PEACHDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"split_time_ms": 1200}'

Duplicate an item

Duplicate a clip, copying its trim, volume, and version settings.

string

required

The parent story.

string

required

The story item to duplicate.

Returns the new StoryItemDetail. Returns 404 if the item is not found.

curl

curl -X POST https://app.peachdeskai.com/api/voice/stories/story_a1b2c3/items/item_001/duplicate \
  -H "X-API-Key: $PEACHDESK_API_KEY"

Pin an item to a version

Pin a clip to a specific generation version (take). Each take is a versioned render of the generation — for example after applying Effects. Pinning controls which audio is used for playback and export.

string

required

The parent story.

string

required

The story item to pin.

string | null

The version (take) to pin. Pass null to revert to the generation’s default take.

Returns the updated StoryItemDetail. Returns 404 if the item or version is not found.

curl

curl -X PUT https://app.peachdeskai.com/api/voice/stories/story_a1b2c3/items/item_001/version \
  -H "X-API-Key: $PEACHDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version_id": "ver_reverb_01"}'

Export

Export story audio

Mix all of the story’s items down to a single WAV file, honoring each clip’s start time, track, trim, volume, and pinned version. Mixing runs on PeachDesk’s infrastructure.

string

required

The story to export.

Response: a streaming audio/wav download. The Content-Disposition header sets the filename from the story name (e.g. Episode 1 — Final.wav).

Status	Meaning
`200`	WAV file stream.
`404`	Story not found.
`400`	Story has no audio items to mix.
`500`	Mixing failed.

curl

curl https://app.peachdeskai.com/api/voice/stories/story_a1b2c3/export-audio \
  -H "X-API-Key: $PEACHDESK_API_KEY" \
  --output story.wav

Need the full Voice Studio walkthrough? See the Stories tab guide in the PeachDesk documentation at docs.peachdeskai.com.

Resources

Authentication & Errors

Voice Engine API

Bibha BRAHMA LLM

Bibha VAANI TTS

Bibha LIPI STT

Stories

Authentication

Data shapes

Stories

List stories

Create a story

Get a story

Update a story

Delete a story

Story items

Add an item

Remove an item

Update item timecodes (batch)

Reorder items

Move an item

Trim an item

Set item volume

Split an item

Duplicate an item

Pin an item to a version

Export

Export story audio

​Authentication

​Data shapes

​Stories

​List stories

​Create a story

​Get a story

​Update a story

​Delete a story

​Story items

​Add an item

​Remove an item

​Update item timecodes (batch)

​Reorder items

​Move an item

​Trim an item

​Set item volume

​Split an item

​Duplicate an item

​Pin an item to a version

​Export

​Export story audio

Authentication

Data shapes

Stories

List stories

Create a story

Get a story

Update a story

Delete a story

Story items

Add an item

Remove an item

Update item timecodes (batch)

Reorder items

Move an item

Trim an item

Set item volume

Split an item

Duplicate an item

Pin an item to a version

Export

Export story audio