# Skill: effect/letter-cascade — "אות אחרי אות" (Letter cascade)

Letters drop, rise, slide or grow in one by one in reading order — and can keep bobbing in a wave.
אותיות נופלות, עולות, מחליקות או גדלות אחת אחרי השנייה בסדר הקריאה — ויכולות להמשיך להתנדנד בגל.

Category: Text animations · אנימציות טקסט · a real preview: https://media.gpt.org.il/lookbook/effects/letter-cascade.mp4?v=mv19exzc
Price: **60 credits per finished minute**: the render itself — 1 credit per second of 1080p output. Combined with captions, a hook or other effects: still one render, nothing more for combining.

Base URL: `https://apihub.co.il` · Auth: `Authorization: Bearer <API key>` · Docs: `/docs` (group "Video Effects")
Send `X-Tag: <job name>` on every call of one video; `GET /v1/usage?tag=<job name>` returns what it cost.
**Files are kept 24 hours** — download the finished video.

---

## 1. On its own — one call

```jsonc
POST /v1/effects/letter-cascade             // x-wait-ms: 110000
{
  "video_url": "https://media.gpt.org.il/samples/sample-he.mp4",
  "text": "בלי תוכנת עריכה",
  "start": 0.2,
  "duration": 3.6,
  "params": {
    "y": 22,
    "loop": "wave"
  }
}
```

A normal render: `status: processing` → poll `GET /v1/executions/{id}` until `completed`, then read `output.url`.
Leave out `video_url` and the effect is drawn on a plain black canvas (9:16 unless `output.aspect_ratio` says otherwise).

When it plays: a stretch: `start` + `duration` (seconds of the finished video), or `at` (a word id) + `duration`, or `during` { from, to } (word ids).

## 2. With captions, a hook and other effects — the same render

```jsonc
POST /v1/studio/edit               // x-wait-ms: 110000
{
  "video_url": "<the video>",
  "language_code": "he",
  "captions": {
    "style": "classic"
  },
  "effects": [
    {
      "id": "letter-cascade",
      "params": {
        "y": 22,
        "loop": "wave",
        "text": "בלי תוכנת עריכה"
      },
      "start": 0.2,
      "duration": 3.6
    }
  ],
  "audio": {
    "normalize": true
  },
  "output": {
    "aspect_ratio": "9:16",
    "resolution": "1080",
    "fit": "crop",
    "quality": "high"
  }
}
```

`effects` is a list: add more entries for more effects. The engine applies them by pipeline stage (cuts and time →
camera → grade and looks → overlays → text and captions → sound), never by their order in the list. An edit has one
`transition`, one `color` grade, one `music` bed, one `speed` and one caption style: two effects that set the same
one are refused with a message that names them.

## 3. Params

| param | default | range / options | what it does |
|---|---|---|---|
| `text` | **required** | string | The words |
| `size` | `8` | 2–30 | Letter size, % of the frame height |
| `color` | `"#FFFFFF"` | string | Text colour |
| `font` | `"Heebo"` | string | Font family — GET /v1/studio/fonts |
| `bold` | `true` | boolean | Bold |
| `y` | `30` | 2–98 | Height of the text's centre, % from the top |
| `outline` | `0` | 0–20 | An outline round the letters, % of the letter size (0 = none) |
| `outline_color` | `"#000000"` | string | The outline's colour |
| `shadow` | `true` | boolean | A soft shadow under the letters |
| `from` | `"down"` | `down` · `up` · `left` · `right` · `scale` · `blur` | Where each letter comes from |
| `stagger_ms` | `40` | 10–200 | Between one letter and the next, ms |
| `in_ms` | `220` | 80–1000 | How long one letter takes to land, ms |
| `distance` | `0.7` | 0.1–3 | How far it travels, × the letter size |
| `ease` | `"back-out"` | `back-out` · `out` | back-out = a small overshoot |
| `loop` | `"none"` | `none` · `wave` | wave = the letters keep bobbing after they land |
| `wave_amplitude` | `0.12` | 0.02–0.5 | wave: how high, × the letter size |
| `wave_period_ms` | `1200` | 300–4000 | wave: one bob, ms |

GET `/v1/effects/letter-cascade` returns the same as JSON (with the full body schema). Every field has a default; numbers
outside their range are refused with the field's name.