# Skill: hook/box — "קופסה" (Hook title with an effect)

An animated headline for the first three seconds of a short — and the same effect anywhere in the video,
on a dramatic beat or the main message. Burned into the same render as the captions, so it costs nothing
extra: **61–125 credits per finished minute** for the whole render.

Example line: `שווה 30 שניות`

> **Given a captions skill AND a hook skill?** They are one job, not two. Put `captions` (from the captions
> skill) and `hook` (from the hook skill) in the **same** `POST /v1/studio/edit` call — one render, the price
> of captions alone. Do not render twice, and never send a video that already has burned-in captions back with
> `captions` again (it gets two sets). The ready-made combination:
> `https://apihub.co.il/skills/captions-<style>+hook-box.md`

Base URL: `https://apihub.co.il` · Auth: `Authorization: Bearer <API key>` · Docs: `/docs`
Send the same `X-Tag: <job name>` header on every call of one video; `GET /v1/usage?tag=<job name>` then
returns exactly what it cost. Times in request bodies are **seconds on the edited (output) timeline**.
Unknown fields are rejected with the name of the right field — read the error instead of guessing.
**Files are kept 24 hours** (renders, uploads, generated clips/images/music) — download the finished video.

---

## 1. Write the line

A short label, 2–4 words ("שווה 30 שניות"): the box wipes in first, then the text pops onto it.

Marks you can use in any hook or text: `*word*` = accent colour (`accent_color`, now `#FFD600`),
`~word~` = struck through, `\n` = a smaller second line. Write in the video's language; Hebrew is shaped and
ordered correctly (no need for any RTL tricks).

## 2. The opening hook

```jsonc
POST /v1/studio/edit               // x-wait-ms: 110000
{
  "video_url": "<source>",
  "language_code": "he",
  "hook": { "text": "שווה 30 שניות", "start": 0, "duration": 3, "style": "box" },
  "captions": { "style": "classic" },        // the style from your captions skill if you have one · false = no captions · same price
  "audio": { "normalize": true },
  "output": { "aspect_ratio": "9:16", "resolution": "1080", "fit": "crop", "quality": "high" }
}
```

Send `x-wait-ms: 110000` to wait for the render in the same call; if the response is still
`processing`, poll `GET /v1/executions/{id}` until `status` is `completed` and read `output.url`.

`"style": "box"` expands to this; send `{ "preset": "box", ...overrides }` to change any field —
the preset is only a starting point. `size` is % of the frame height; `position` + `margin` place it, or
`x`/`y` (% of the frame) put it exactly where you want; `font`, `weight`, `color`, `background`
(a box), `outline`/`outline_color`, `shadow`/`shadow_color`, `letter_spacing`, `rotate`,
`accent_color` and `max_chars_per_line` are all yours:

```json
{
  "font": "Heebo",
  "weight": 900,
  "size": 7,
  "color": "#000000",
  "background": "#FFFFFF",
  "outline_color": "#000000",
  "outline": 0,
  "shadow": 0,
  "uppercase": false,
  "position": "top",
  "margin": 12,
  "max_chars_per_line": 16,
  "animation": "box",
  "rotate": 0,
  "accent_color": "#FFD600",
  "letter_spacing": 0,
  "shadow_color": "#00000099",
  "side_margin": 5
}
```

## 3. The same effect mid-video (drama, the main message)

Any text element takes the effect, at any second, anywhere in the frame:

```jsonc
"texts": [
  { "text": "שווה 30 שניות", "start": 12.4, "duration": 1.8,
    "effect": "box", "preset": "hero",
    "style": { "size": 7, "position": "center", "y": 42, "background": "#FFFFFF", "color": "#000000" } }
]
```

Where to put them — from the transcript, not from guesswork:

| In the sentence | Effect |
|---|---|
| the thesis, the one line the video exists for | `punch` or `rise` |
| a number, a sum, a percentage | `counter` (put the number in the text) |
| "אבל…", a contradiction, a mistake | `glitch` or `shake` |
| a before → after | `strike` (`~old~ *new*`) |
| a list opener | `marker` |
| a whispered aside, a reveal | `blur` or `words` |
| an interruption, "wait" | `flash` or `box` |

Rules: one effect per 6–10 seconds, never two at once, never over the punchline of a caption, nothing in the
last 3 seconds except the closing line. Keep `duration` 1.2–2.2 s for a beat, 3 s for the opening hook.
Sound helps: `"sounds": [{ "url": "<whoosh from /v1/ai/sound-effects>", "start": 12.1, "volume": 0.5 }]`.

`GET /v1/studio/hook-styles` lists all 13 effects; `GET /v1/studio/text-styles` the text presets (`hero`,
`mega`, `pill`, `outline`…) an effect can be applied to.

## Rules that keep captions readable on every platform

- **Safe zone.** Keep text inside the middle 80% of the frame: `side_margin` ≥ 6 handles the sides; `margin`
  ≥ 12 keeps the bottom clear of the platform UI (username, buttons, progress bar).
- **A line never leaves the frame** — a line too wide for the side margins is set smaller automatically. Do
  not shrink the size yourself, wrap instead (`max_chars_per_line`).
- **Hebrew has no capitals** — keep `uppercase: false`; it only breaks Latin words mixed into a sentence.
- **Fonts.** `GET /v1/studio/fonts` lists the bundled families and which scripts they draw. A font that
  cannot draw the caption's language is swapped and reported in `warnings`.
- The customer's transcript wins: to fix a word, `GET /v1/speech/transcripts/{id}/captions`, edit the text,
  and send the list back as `captions.captions` — timing is kept when the word count is unchanged.

## What it costs

The hook is part of the captions render: ≈ 1 credit per second of output plus ≈ 1 per minute of transcription
— 61–125 credits per finished minute. Text effects mid-video are in the same render too. Only *generated*
assets (a whoosh ≈ 1 credit, music ≈ 0.8 per second) add to that.