---
title: "Choose how we see a story film's screen."
method: PUT
path: "/story-projects/{projectId}/story-films/{storyId}/screen-view"
tags: ["Story Films"]
---

# Choose how we see a story film's screen.

`PUT /story-projects/{projectId}/story-films/{storyId}/screen-view`

## Request

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

How we see the screen is set for each product moment, by Slug unless the writer picks; the first time a film shows the screen it is always over the shoulder, and only later moments may cut straight to it: full screen cuts straight to the real recording filling the frame, with a slow push in; over the shoulder opens behind the person at the laptop with the real recording on its screen (at most 6 s), then pushes into full screen; hands, then full screen (a preview) leads in with one short shot of the person's hands, never the screen. An over-the-shoulder shot that cannot be placed opens the moment on the hands instead, never on the flat screen; a shot that renders unusable is left out by itself. The next cut planned from the script uses it; a cut already planned keeps how it was planned. `{ kind }` sets every moment's view (`full-screen`, `over-the-shoulder` or `hands-then-full-screen`); `{ momentId, kind }` sets one moment's, and `kind: null` hands it back to Slug's choice. `setBy` is `writer` (the default) or `slug`; `reason` is one optional line. `screen-in-room` and `over-the-shoulder-on-phone` are not offered yet (400 `validation_failed`). Free. Scope: `story:write`.

## Request body

- SetStoryFilmScreenViewRequest: How we see the screen is set for each product moment, by Slug unless the writer picks; the first time a film shows the screen it is always over the shoulder, and only later moments may cut straight to it: full screen cuts straight to the real recording filling the frame, with a slow push in; over the shoulder opens behind the person at the laptop with the real recording on its screen (at most 6 s), then pushes into full screen; hands, then full screen (a preview) leads in with one short shot of the person's hands, never the screen. An over-the-shoulder shot that cannot be placed opens the moment on the hands instead, never on the flat screen; a shot that renders unusable is left out by itself. The next cut planned from the script uses it; a cut already planned keeps how it was planned. `{ kind }` sets every moment's view; `{ momentId, kind }` one moment's, and `kind: null` hands it back to Slug's choice.
  - `kind` 'full-screen' | 'hands-then-full-screen' | 'over-the-shoulder' | 'null', nullable, required
  - `momentId` string: One product moment of the film. Omitted: every moment.
  - `setBy` 'slug' | 'writer': `writer` (the default) for the writer's own pick; `slug` when Slug applies its own taste.
  - `reason` string: Why, in one line.

## Response `200`

Every moment's view, who chose it and why, and a note.

- StoryFilmScreenView: How we see the screen is set for each product moment, by Slug unless the writer picks; the first time a film shows the screen it is always over the shoulder, and only later moments may cut straight to it: full screen cuts straight to the real recording filling the frame, with a slow push in; over the shoulder opens behind the person at the laptop with the real recording on its screen (at most 6 s), then pushes into full screen; hands, then full screen (a preview) leads in with one short shot of the person's hands, never the screen. An over-the-shoulder shot that cannot be placed opens the moment on the hands instead, never on the flat screen; a shot that renders unusable is left out by itself. The next cut planned from the script uses it; a cut already planned keeps how it was planned.
  - `projectId` string, required
  - `storyId` string, required
  - `moments` object[], required
    - `id` string, required
    - `mustShowMoment` string, required
    - `screenView` StoryFilmMomentScreenView, required: How we see one product moment's screen, who chose it (Slug's taste or the writer's pick) and why.
      - `kind` 'full-screen' | 'hands-then-full-screen' | 'over-the-shoulder', required
      - `setBy` 'slug' | 'writer', required
      - `reason` string, required: Why, in one line.
  - `note` string, required: What changed and when it applies, to read out.

## 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/4534f5d25540?raw)