Artifacts

Conversationally revise a table read artifact in place.

Submits a free-form instruction that rewrites the screenplay and/or re-grounds the StoryPlan, producing a NEW REVISION of the SAME artifact. The artifact id, share token, and all three player URLs (theaterUrl / theaterFullscreenUrl / audio.liveUrl) remain STABLE — no re-embed, no new links. scope controls the rewrite strategy: - "auto" (default) — the model self-routes; most instructions hit screenplay. - "screenplay" — rewrites the screenplay and recasts voices in place; faster. - "plan" — re-grounds the StoryPlan against sources then re-adapts; use for major structural changes. TWO CALLS: a price and a spend are two tools. Sent without confirmed it returns the QUOTE and reserves and enqueues NOTHING — { quotedOnly: true, credits, lines, balanceAfter, sufficient, note }; the same request with confirmed: true reserves exactly the quoted amount and returns { storyJob }. Sent confirmed, poll GET /story-jobs/{jobId} until terminal (READY / FAILED), exactly like a standard artifact generation job. Once complete, GET /artifacts/{id} returns the updated currentVersion and refineCount. Fetch a prior revision with GET /artifacts/{id}?revision=N (v1 = initial generation). Reserves TABLE_READ_REFINE (8 Studio Credits) only when confirmed: true. Every precondition is refused BEFORE the quote. Requires Idempotency-Key.

post/artifacts/{artifactId}/refine

Request

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

Headers

Idempotency-Keystring required

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

Request body

instructionstring required

Free-form revision instruction (e.g. "rename the host to Dana and drop the narrator; make the skeptic warmer").

scope'auto' | 'screenplay' | 'plan'

auto (default) lets the model self-route. screenplay rewrites cast + screenplay only. plan re-grounds against sources first.

narrationPolicy'include' | 'suppress'

Optional narration-posture override for this revision. Omit to keep the read's current posture.

confirmedboolean

Omit (or false) to get the price without spending anything. true reserves exactly the quoted TABLE_READ_REFINE and creates the refine job, only after the writer has seen the price.

Response

Without confirmed: the price (quotedOnly: true), nothing reserved or enqueued. With confirmed: true: the refine job to poll until terminal.

quotedOnlyboolean required

true when this call only PRICED the revision. false (or absent) when it created the job.

creditsinteger

Quote only: the TABLE_READ_REFINE price.

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

Quote only: the price and what it would leave, and that nothing has been spent. Show it to the writer.

Changes

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