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.
Request
- Base URL: https://docs.sleeperhit.studio/api/v1
- URL: https://docs.sleeperhit.studio/api/v1/artifacts/{artifactId}/refine
- Auth: HTTP bearer
Headers
Customer-generated stable identifier for safe retries of idempotent POST requests.
Request body
Response
Without confirmed: the price (quotedOnly: true), nothing reserved or enqueued. With confirmed: true: the refine job to poll until terminal.
Changes
No recorded changes to this operation across all 1 revision of this API.