---
title: "Save episode character direction without generating or spending credits."
method: PATCH
path: "/story-projects/{projectId}/cast"
tags: ["Projects"]
---

# Save episode character direction without generating or spending credits.

`PATCH /story-projects/{projectId}/cast`

## Request

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

Existing images and voices remain unchanged. avatarPrompt guides headshots and sheets; figurePrompt guides body shots. signatureItems (what only this person wears or carries) is saved on the project cast canon for every episode. A person on the project cast canon whom the episode does not name (a deck or trailer draws them from the canon) takes `signatureItems` alone, saved on their canon entry (`projectCast: true` in the answer); any other field sent for them is refused by name. When the canon cannot tell who the character is, nothing is saved and a 409 names the `candidates`; the writer answers with `sameAs` (the character IS that canon person, so the script name becomes their alias) or `newPersonName` (someone else, saved under that full name). A separate quote and confirmation are required to replace assets.

## Request body

- EpisodeCharacterDirectionRequest: Provide at least one direction field. Narrator direction must not include image prompts, signature items or an identity answer. When the cast canon cannot tell who the character is, nothing is saved: the 409 `cast_precondition_failed` carries `details.reason` (`cast_identity_unresolved` or `cast_identity_declaration_refused`), `details.character`, `details.candidates` and `details.suggestedName`; ask the writer and send `sameAs` or `newPersonName` with their answer.
  - `scriptUploadId` string, required
  - `character` string, required
  - `avatarPrompt` string
  - `figurePrompt` string
  - `age` string
  - `gender` string
  - `personality` string
  - `speechStyle` string
  - `backstory` string
  - `relationships` string
  - `signatureItems` string[]: What only this person wears or carries ("round wire spectacles"). Saved on the project cast canon for every episode, not on this episode; replaces the saved list, and an empty list clears it.
  - `sameAs` string: The writer says this character IS this cast canon person (a candidate id or name: "IVAN is Ivan Karamazov"). The script name becomes their alias, and a stray canon row named by the script name is folded into them, their art standing. Send only on the writer's answer. Not with `newPersonName`.
  - `newPersonName` string: The writer says this character is someone else: saved in the cast canon under this full name, with the script name as an alias. Not with `sameAs`.

## Response `200`

Saved direction; generated is always false.

- EpisodeCharacterDirectionResult
  - `saved` unknown, required
  - `character` string, required
  - `direction` object, required
    - `signatureItems` string[]
  - `generated` unknown, required
  - `canonPerson` object: The cast canon person written to, present when signature items or an identity answer were saved.
    - `id` string, nullable, required
    - `name` string, required
    - `aliases` string[], required
  - `declared` object: What the writer's `sameAs` / `newPersonName` answer changed.
    - `kind` 'same_as' | 'new_person', required
    - `absorbed` string[], required: Stray canon rows folded into the person; their names are now its aliases.
    - `releasedFrom` string[], required: People who listed the script name as an alias and no longer do.

## Other responses

- `400`: Request payload failed validation. The error message names the offending field.
- `401`: Missing, malformed, revoked, or expired API key.
- `403`: API key is valid but lacks the scope, is blocked by IP allowlist, or the account is disabled.
- `404`: The named project or source does not exist or is owned by another account.
- `429`: Rate limit for this API key + IP + route family was exceeded.
- `500`: The API failed unexpectedly. Safe to retry with the same Idempotency-Key.

---

[API](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api.md) · [All operations](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/revisions/86e084144cef?raw)