---
title: "Add or refine a motion-graphics beat in a theater scene."
method: POST
path: "/artifacts/{artifactId}/theater-motion"
tags: ["Artifacts"]
---

# Add or refine a motion-graphics beat in a theater scene.

`POST /artifacts/{artifactId}/theater-motion`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/artifacts/{artifactId}/theater-motion`
- Auth: HTTP bearer

Authors or refines a single MOTION BEAT (kinetic on-screen text, a lower-third, or a title card) anchored to one spoken line and baked into the durable theater video. Returns `shareUrl` — a watchable link to the enhanced theater video. Requires `Idempotency-Key`. Scope: `artifact:publish`.

## Headers

- `Idempotency-Key` string, required

## Request body

- TheaterMotionBeatRequest: A single motion-graphics beat for a table-read theater scene.
  - `sceneIndex` integer, required: Zero-based scene index.
  - `entryIndex` integer, required: Zero-based script entry (spoken line) this beat occupies.
  - `compositionKind` 'motion-only' | 'motion-over-clip' | 'performance-motion-overlay', required: How the motion graphic composites.
  - `captionText` string: On-screen copy the motion layer renders.
  - `direction` string: Natural-language motion direction.
  - `durationSeconds` number: Motion timeline length in seconds.
  - `backgroundClipPrompt` string: Look for the background clip (for a motion-over-clip beat; generated separately).

## Response `200`

The motion beat + a shareable theater video link.

- TheaterMotionResult: The committed motion beat plus a shareable link to the enhanced theater video.
  - `artifactId` string, required
  - `shareUrl` string: Watchable link to the enhanced theater video.

## 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 story artifact 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)