---
title: "Read the trailer's camera motion."
method: GET
path: "/trailers/{jobId}/camera"
tags: ["Trailer"]
---

# Read the trailer's camera motion.

`GET /trailers/{jobId}/camera`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/trailers/{jobId}/camera`
- Auth: HTTP bearer

Returns every beat's shots, numbered as its cut plays them, each with its camera (`held`, `moving`, `handheld`), who speaks on camera and who the call renders; the handheld strength; each beat's move; and, beat by beat, what the last master laid (`state`: on, waiting, partly with a `moveReason`, off) with the sentence the review shows. Camera motion gives the held shots an operator, the way a documentary camera moves: a handheld sway on the shots that were rendered still (off, subtle, medium; never on a shot whose camera already moves or was filmed handheld, and never so far that a speaking mouth leaves the frame), and at most one move per chapter or beat, on a held shot where nobody speaks on camera: a snap zoom onto a reaction (up to 1.5×, right after a line) or a slow reframe from one face to another already in the frame. It is free, and laid when the master is assembled, as the first step of the film finish and before any type. The sound and timing are never touched. Scope: `story:read`.

## Response `200`

The trailer's camera motion.

- CameraView: Camera motion gives the held shots an operator, the way a documentary camera moves: a handheld sway on the shots that were rendered still (off, subtle, medium; never on a shot whose camera already moves or was filmed handheld, and never so far that a speaking mouth leaves the frame), and at most one move per chapter or beat, on a held shot where nobody speaks on camera: a snap zoom onto a reaction (up to 1.5×, right after a line) or a slow reframe from one face to another already in the frame. It is free, and laid when the master is assembled, as the first step of the film finish and before any type. The sound and timing are never touched.
  - `handheld` 'off' | 'subtle' | 'medium', required: The handheld sway on the held shots (`off` when the camera is off).
  - `on` boolean, required: True when the camera does anything (a handheld strength or a move).
  - `units` object[], required: Every chapter (deck) or beat (trailer), in order.
    - `unit` integer, required: The chapter's `chapterIndex` or the beat's `beatIndex`: the key a set names it by.
    - `unitNumber` integer, required: Its place, 1-based: the number a writer sees.
    - `hasCut` boolean, required: It has a rendered cut (a move can be chosen only then).
    - `state` 'on' | 'waiting' | 'partly' | 'off', required: `on`: the last master laid it as chosen; `waiting`: chosen, not in a master yet; `partly`: the sway was laid but the move was left out (`moveReason`); `off`: the camera does nothing to it.
    - `move` CameraMove, nullable, required: A chapter's or beat's move, as chosen.
      - `move` 'snap' | 'reframe', required: `snap`: a snap zoom onto a reaction; `reframe`: a slow reframe from one face to another.
      - `shot` integer, required: The shot's number in the cut, 1-based.
      - `target` string, required: The face the move lands on.
      - `from` string, nullable, required: A reframe's first face.
      - `zoom` number, nullable, required: A snap zoom's zoom.
    - `moveState` 'applied' | 'dropped', nullable, required: What the last master made of the move, when laid for this choice.
    - `moveReason` 'moving' | 'speaks' | 'too_short' | 'not_found' | 'no_clean_framing' | 'letterboxed', nullable, required: Why a dropped move was left out.
    - `staleMove` boolean, required: The move named a shot a recompile removed: ignored until chosen again.
    - `sentence` string, nullable, required: What the review says for it.
    - `shots` object[], required
      - `number` integer, required: The shot's number, 1-based, as the cut plays them: what a set names.
      - `startSeconds` number, required
      - `endSeconds` number, required
      - `framing` string, required
      - `camera` 'held' | 'moving' | 'handheld', required: `held`: rendered still (it takes the sway and a move); `moving`: the camera already travels; `handheld`: filmed handheld (never swayed again).
      - `speaksOnCamera` boolean, required: Someone says a line on camera in it (no move goes on it; its sway keeps the speaker's mouth in frame).
      - `cast` string[], required: Who the call renders: who a move may aim at.
      - `action` string, required: What happens in it.
  - `handhelds` object[], required
    - `id` 'off' | 'subtle' | 'medium', required
    - `label` string, required
    - `description` string, required
  - `moves` object[], required
    - `id` 'snap' | 'reframe', required
    - `label` string, required
    - `description` string, required
  - `snapZoom` object, required
    - `min` number, required
    - `default` number, required
    - `max` number, required
  - `description` string, required

## Other responses

- `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/64c1102ccb2f?raw)