Projects

Pin one designed candidate voice to the cast canon.

Keeps candidate candidate (1-based) of design designId: clones its take into the provider that speaks every designed voice (Cartesia), adds it to your voice library as voiceName (default "<project> - <character>") with where it came from (the description, the take's preview id, the new voice), pins it on the cast canon person (so every new episode, deck, trailer and showcase speaks with it), and lists in reads the finished reads that still speak this character with another voice — re-voice them with POST /artifacts/{artifactId}/revoice (priced). Free; choosing another candidate of the same design later is free too, and choosing one already chosen reuses its voice. A candidate drawn before the designer changed cannot be chosen (409 cast_voice_precondition_failed, details.missing take): design again. A candidate its casting coverage FAILED (GET .../cast-voice/designs/{designId}/coverage, failingCandidates) is refused with 409 cast_voice_casting_coverage_failed unless acknowledgeCastingCoverage: true, sent only once the writer has heard it and chosen it anyway; coverage still running or one that could not run never holds a choice (castingCoverageWarning says so). Requires Idempotency-Key. Scope: story:write.

post/story-projects/{projectId}/cast-voice/choose

Request

  • Base URL: https://docs.sleeperhit.studio/api/v1
  • URL: https://docs.sleeperhit.studio/api/v1/story-projects/{projectId}/cast-voice/choose
  • Auth: HTTP bearer

Headers

Idempotency-Keystring required

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

Request body

designIdstring required
candidateinteger required

1-based candidate number from the design.

voiceNamestring

Name in your voice library. Default "<project> - <character>".

acknowledgeCastingCoverageboolean

Choose a candidate its casting coverage FAILED (otherwise refused with 409 cast_voice_casting_coverage_failed, details.castingCoverage carrying the score, the bar, why and the candidate it recommends). Send true ONLY after the writer has heard it and chosen it anyway — never on your own.

Response

The voice pinned, and the reads still on another voice.

projectIdstring required
designIdstring required
characterstring required
castingCoverageWarningstring nullable

What casting coverage said about this choice: still running, could not run, another candidate recommended, or chosen past a failure.

notestring required

Changes

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