Projects

Draw headshot candidates for one cast member (metered — TWO CALLS, price first).

Draws N headshot candidates (candidates, default 3, at most 4) for one named cast member (character, by canon name, alias, cue or Series Bible name), so the writer chooses a face instead of taking the only one the cast draws. Each is drawn from the Series Bible's appearance and wardrobe for them with their LOOK after it: direction when given, else their look direction on the cast canon (PATCH /story-projects/{projectId}/cast-look), and age likewise. The look outranks the Bible where they differ. TWO CALLS: sent without confirmed it PRICES the candidates and draws nothing (quotedOnly: true, credits — one cast headshot per candidate — balanceAfter, sufficient, note, and the direction it will draw from); sent again with confirmed: true it reserves them, records the design and queues the draw (designId, status: queued). Poll GET .../cast-portraits/designs?designId= until status is complete. EVERY CANDIDATE DRAWN IS CHARGED, chosen or not; a candidate that cannot be drawn is released; choosing is free. RESTYLE KEEPING THE FACE: with keepFace: true each candidate is the person's CURRENT HEADSHOT on the cast canon, edited to the look (direction, else their saved look) on the model that keeps a face, so their hair, grooming, wardrobe or styling change and the person stays the same (restyledFrom names the headshot). Same price per candidate; casting coverage judges them and choosing works the same. Refused before the price: 404 character_not_found when nobody in the cast canon or Series Bible answers to the name; 409 cast_precondition_failed when there is nothing to draw them from, no image model is bound, or (with keepFace) they have no headshot yet (reason cast_face_missing) or no bound model keeps a face; 409 project_precondition_failed when the project has not reached casting. Requires Idempotency-Key. Scope: artifact:publish (billable).

post/story-projects/{projectId}/cast-portraits/design

Request

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

Headers

Idempotency-Keystring required

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

Request body

characterstring required

The cast member: canon name, alias, script cue or Series Bible name.

directionstring

How they should look, in the writer's words. Omitted: their look direction on the cast canon, else the Series Bible alone.

agestring

The age they are played at. Omitted: their cast canon age.

candidatesinteger

Headshot candidates to draw (default 3). Each is charged.

keepFaceboolean

Restyle the person KEEPING THEIR FACE: each candidate is their current headshot on the cast canon, edited to the look (direction, else their saved look) on the model that keeps a face, so the hair, grooming, wardrobe or styling change and the person stays. Same price per candidate, judged by casting coverage and chosen like any headshot. Refused (409 cast_precondition_failed, reason cast_face_missing) when they have no headshot yet. Omit (or false) for new faces.

confirmedboolean

Omit (or false) to get the price without spending anything. true reserves and queues the draw, only after the writer has seen the price.

Response

The price (no confirmed) or the queued design.

quotedOnlyboolean required
queuedboolean

Confirmed only.

creditsinteger required
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

Show it to the writer. The quote says every candidate drawn is charged, chosen or not.

characterstring required
castPersonIdstring nullable
directionstring required
directionSource'request' | 'cast_canon' | 'series_bible' required
agestring nullable
candidatesinteger required

How many candidates will be (or are being) drawn.

restyledFromstring nullable

A restyle that keeps the face (keepFace): the current headshot each candidate is edited from. Null for new faces.

designIdstring

Confirmed only.

status'queued' | 'drawing' | 'complete' | 'failed'

Confirmed only.

Changes

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