Artifacts

Re-voice one line of a table read at a new speed or with a new acting direction (free; TWO CALLS, quote first).

Speaks line entryIndex again from its voice's provider with a new speed, a new actingDirection, or both (the line is spoken once). The speed is sent as that provider's OWN speed parameter (Cartesia generation_config.speed 0.6–1.5, ElevenLabs voice_settings.speed 0.7–1.2, Deepgram speed 0.7–1.5) — never a time-stretch — and brought inside the provider's range; the answer says the range (range) and whether it did (clamped). The direction is free text in the writer's words, sent through the provider's OWN expressive control: OpenAI instructions, ElevenLabs Eleven v3 and later as a leading audio tag, and Cartesia sonic-3 and newer as one emotion from the voice's list and a pace nudge, chosen from the direction's words by the mapping step when the line is spoken — GET /scripts/{scriptUploadId}/lines/{entryIndex} then shows it as sentAs (direction says which channel); an empty string or null takes it off. Every other line keeps its recording byte for byte, then the read is mixed again with its music and sound. FREE: a line's speed and direction cost no credits — nothing is held, charged or booked, and credits is always 0. Three outcomes (mode), all quoted first: revoice — the read has a finished recording, and the line is spoken again; restore_take — the line had a take with this speed and direction before (the take it has is kept whenever it is re-voiced), and it is brought back; save — the read has no recording yet: they are saved and the line is spoken that way when the read is recorded. TWO CALLS: sent without confirmed it QUOTES and changes nothing (quotedOnly: true, credits 0, mode, changes, speed, previousSpeed, range, actingDirection, previousActingDirection, keptLines, balanceAfter, sufficient, and a note to show the writer); sent again with confirmed: true it does it. Poll GET /artifacts/{artifactId} until manifest.audio.finalize.status is complete. Refused before the quote with 409 cast_voice_precondition_failed (details.reason): provider_has_no_speed (an OpenAI or Hume voice, or a model or voice with no speed setting — Eleven v3, Cartesia before sonic-3, a Deepgram Aura-1 voice or a Cartesia professional clone — named in details.model and details.noSpeed: recast the character first), provider_has_no_direction (a Deepgram, Hume, or OpenAI tts-1 voice, ElevenLabs before Eleven v3, or a Cartesia model before sonic-3 — none reads a written direction, and Cartesia before sonic-3 has no delivery controls at all — details.model, details.noDirection), same_speed, same_direction, nothing_spoken, no_voice, modified_take (the line plays a voice effect or a performance take), finalize_running, not_spliceable / not_in_recording (a recording that cannot be cut line by line), line_changed (the line was edited since it was priced). 409 voice_retired when the line's voice is one its provider retired. Requires Idempotency-Key. Scope: artifact:publish.

post/artifacts/{artifactId}/revoice-line

Request

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

Headers

Idempotency-Keystring required

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

Request body

entryIndexinteger required

The line: its index in the read (GET /artifacts/{artifactId}/script).

speednumber

A new speed. 1 is the voice's natural pace; 1.15 is 15% faster. Brought inside the line's provider's range (Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Deepgram 0.7–1.5). Omit to keep the line's speed.

actingDirectionstring nullable

A new acting direction: how the line is delivered, in the writer's words ("quiet, low-key storytelling tone"). Reaches OpenAI voices as instructions and ElevenLabs voices on Eleven v3 or later as a leading audio tag. An empty string or null takes it off. Omit to keep the line's direction.

confirmedboolean

Omit (or false) to get the quote (free: 0 credits) without changing anything. true does it, only after the writer has seen the quote and said go.

Response

The quote, 0 credits (no confirmed), or the queued re-voice / the saved speed and direction.

quotedOnlyboolean required

true when this call only QUOTED it.

artifactIdstring nullable required
entryIndexinteger required
characterstring required

Who speaks the line: its character cue, or NARRATOR.

textstring required

The words spoken.

changesstring[] required

What this changes: the line's speed, its acting direction, or both.

speednumber required

The speed the line is spoken at: the one asked for, inside the provider's range (its own, when the speed does not change).

requestedSpeednumber required
clampedboolean required

true when the speed asked for was outside the provider's range.

previousSpeednumber required

The speed the line has now. Setting it back to this brings its current take back.

actingDirectionstring nullable required

The acting direction the line is spoken with (its own, when the direction does not change). Null: none.

previousActingDirectionstring nullable required

The direction the line has now. Setting it back to this brings its current take back.

mode'revoice' | 'restore_take' | 'save' required

All free. revoice: spoken again. restore_take: a take it had with this speed and direction comes back. save: no recording yet, the speed and direction are saved.

keptLinesinteger required

Lines kept as they are in the current recording.

creditsinteger required

Always 0: a line's speed and direction are free.

costLabelstring nullable

Quote only.

balanceAfterinteger

Quote only. Studio Credits the writer would have left once this is spent: the balance available now (as Billing shows it) minus the price. Negative means they are that many short.

sufficientboolean

Quote only. True when the available balance covers the price. False means the writer must top up first (the note names the Billing link) — do not confirm; the reserve would refuse.

notestring required

What it would do, and that it is free (quote), or what happens next (confirmed). Show it to the writer.

status'queued' | 'saved'

Confirmed calls only. queued: poll GET /artifacts/{artifactId} until manifest.audio.finalize.status is complete. saved: the speed and direction are saved for the read's recording.

Changes

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