Artifacts

Recast a single character's voice on a table read artifact.

Reassigns one character's voice on the table read backing this artifact, in place. The artifact id, share token, and all player URLs remain STABLE — no new revision, no charge. Body: { character, voiceId, voiceName, gender?, provider?, pinToCanon? }. provider is the TTS provider for the voice (e.g. cartesia, openai); omit to infer it (your library voice's own, else the read's, else the configured table-read provider). A voice whose provider retired it is refused (409 voice_retired). THE CAST CANON FOLLOWS: renders (decks, trailers, showcases) prefer the canon voice, so the recast also pins it on the canon person the character names (by name or alias) unless pinToCanon: false. canon names the person pinned. NOTHING IS LOST: when the voice actually changes on a read that has a recording, the previous voice, the voices-only track and the finished mix are kept before the recording is invalidated, and POST /artifacts/{artifactId}/voice/restore puts them back (restore describes what it would restore). A recast to the voice the character already has changes nothing (changed: false). To keep every other line and re-voice only this character in a finished read, use POST /artifacts/{artifactId}/revoice instead. Returns the updated voiceMap (character → voice). The current cast is also readable on manifest.audio.voiceMap via GET /artifacts/{id}. Requires Idempotency-Key. Scope: artifact:publish.

post/artifacts/{artifactId}/voice

Request

  • Base URL: https://docs.sleeperhit.studio/api/v1
  • URL: https://docs.sleeperhit.studio/api/v1/artifacts/{artifactId}/voice
  • Auth: HTTP bearer

Headers

Idempotency-Keystring required

Customer-generated stable identifier for safe retries of idempotent POST requests.

Request body

characterstring required

Character name as it appears in the cast (e.g. "NARRATOR").

voiceIdstring required

Provider voice id to assign.

voiceNamestring required

Human-readable voice name (shown in the cast).

genderstring

Optional voice gender hint. Preserves the existing value when omitted.

provider'cartesia' | 'elevenlabs' | 'openai' | 'deepgram' | 'hume'

Optional TTS provider for this voice. Inferred when omitted (your library voice's own, else the read's, else the configured table-read provider).

pinToCanonboolean

Also pin this voice on the cast canon person (default true), so decks, trailers and showcases speak with it too. false changes this read only.

Response

Voice recast. Returns the updated cast as voiceMap.

artifactIdstring required
characterstring required
voiceMapobject required

Full updated cast: character → { voiceId, voiceName, gender, provider }.

changedboolean required

false when the character already had this voice: nothing was invalidated or remembered.

Changes

No recorded changes to this operation across all 2 revisions of this API.