Artifacts

Refine the delivery of all of one character's lines on a table read artifact.

Adjusts the performance — speed, volume, and cadence — across ALL of one character's lines on the live read backing a table_read artifact. How lines feel is their written acting directions (there are no emotion tags; on a Cartesia voice a direction is sent as one emotion from the voice's list): change one with POST /artifacts/{artifactId}/revoice-line. emotions and overrideExisting are refused with 400 validation_failed. Set character to a name, "NARRATOR" (all narration lines), or "ALL" (every voiced line). Speed and volume accept either an absolute value (speed, 1 the natural pace; volume 0.5–2.0) or a relative per-line multiplier (speedFactor/volumeFactor, e.g. 1.2 for +20%). Each line's speed is brought inside the range of the provider that speaks it (Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Deepgram 0.7–1.5), and a line whose voice takes no speed setting (OpenAI, Hume, Eleven v3, Cartesia before sonic-3, Deepgram Aura-1, a Cartesia professional clone) keeps its pace — speedUnsupportedLines counts them and speedNote says why. Volume clamps to 0.5–2.0. Provide at most one of each pair. There is no separate cadence field — express cadence as speed plus pauseAfterMs (breathing room after each line). No new revision — the artifact id and share URLs stay stable, like a voice recast. Durable media is invalidated; update the recording (POST /artifacts/{artifactId}/update-recording, free) to hear the change — only the lines it changed are spoken again. Requires Idempotency-Key. Scope: artifact:publish.

post/artifacts/{artifactId}/performance

Request

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

Headers

Idempotency-Keystring required

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

Request body

characterstring required

Character name, "NARRATOR", or "ALL".

speednumber

Absolute speed (1 is the voice's natural pace). Each line is brought inside the range of the provider that speaks it (Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Deepgram 0.7–1.5); a line whose voice takes no speed setting keeps its pace (speedUnsupportedLines). Mutually exclusive with speedFactor.

speedFactornumber

Relative per-line speed multiplier (1.2 = +20%); each line is brought inside its own provider's range, and a voice with no speed setting keeps its pace. Mutually exclusive with speed.

volumenumber

Absolute volume slider. Mutually exclusive with volumeFactor.

volumeFactornumber

Relative per-line volume multiplier; each line clamps to 0.5–2.0. Mutually exclusive with volume.

pauseAfterMsinteger

Pause after each matched line, in ms (cadence/breathing room).

instructionstring

Optional natural-language note recorded in the per-line audit trail.

Response

Performance directive applied.

artifactIdstring required
status'ready' required
characterstring required

Resolved target ("ALL" when targeting every voiced line).

matchedLinesinteger required
linesUpdatedinteger required
speednumber nullable
speedFactornumber nullable
volumenumber nullable
volumeFactornumber nullable
pauseAfterMsinteger nullable
speedUnsupportedLinesinteger

Matched lines whose voice takes no speed setting (OpenAI, Hume, Eleven v3, Cartesia before sonic-3, Deepgram Aura-1, a Cartesia professional clone): they keep their pace.

speedNotestring nullable

Why a line kept its pace, and what to do. Null when every matched line took the speed.

Changes

No recorded changes to this operation across all 1 revision of this API.