# Skill: full/explainer — "סרטון הסבר" (Complete video)

A list or a process: a box hook, news-bar captions, one free icon card per step and a calm music bed.

**Includes:** hook · captions · icons · music
**Built on:** hook `box` ("קופסה", `/skills/hook-box.md`) + captions `news` ("חדשות", `/skills/captions-news.md`)
**Price:** 165–180 credits per finished minute · 30 s ≈ 85–95 credits
**Uses:** `/v1/studio/remove-silence` · `/v1/stock/icon` · `/v1/ai/music` · `/v1/studio/edit`

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.

**Models.** This template runs on the newest models: `quality: "best"` on every AI call — Veo 3.1 for clips,
Nano Banana Pro for images, ElevenLabs v3 for Hebrew voice. Each is priced per asset, so a 30-second video
costs almost as much as a 60-second one. `quality: "balanced"` is the cheaper cut of the same recipe.

---

## 1. Cut and transcribe

```jsonc
POST /v1/studio/remove-silence     // x-wait-ms: 110000
{ "video_url": "<source>", "language_code": "he", "min_pause_ms": 350, "padding_ms": 70, "remove_fillers": true,
  "output": { "resolution": "source", "aspect_ratio": "original", "quality": "high" } }
POST /v1/speech/transcripts        { "audio_url": "<cut url>", "language_code": "he" }   → transcript_id
GET  /v1/speech/transcripts/{id}/sentences                                              → the edit map (ms)
```

**Check the words against the speech before you use them.** Now and then the default model loses a phrase of
Hebrew: a second or more of talking with no words in the sentences, or words squeezed to zero length (`start` = `end`).
Transcribe the same cut again with `"speech_models": ["universal-2"]` (≈ 1 credit a minute), take its words for that
stretch, fix a misheard name (a brand, a product), and send the list as `"words": [{ "text", "start", "end" }]` (ms) in
the render instead of `transcript_id` — the captions are built from your words in the style's own rhythm.

**Everything below is timed on the cut video's clock.**

## 2. Assets (in parallel)

```jsonc
POST /v1/stock/icon { "icon": "mdi:rocket-launch", "color": "#111111", "size": 512, "background": "#FFFFFF", "padding": 16 }  // free (search ids with GET /v1/stock/search?kind=icon&q=…)
POST /v1/ai/music   { "prompt": "<mood, instruments, tempo — no vocals>", "duration": <video seconds + 2>, "instrumental": true }   // ≈ 0.8 credits/second
```

One icon per step (3–6). Search first: `GET /v1/stock/search?kind=icon&q=delivery` gives ids like
`mdi:truck-fast` with the set's licence.

## 3. Render

Each step gets its icon as a floating card and a label under it, timed to the sentence that names the step:

```jsonc
POST /v1/studio/edit               // x-wait-ms: 110000
{
  "video_url": "<cut url>", "transcript_id": "<id>",
  "hook": { "text": "<the list title, e.g. 3 שלבים ל…>", "duration": 3, "style": "box" },
  "captions": { "style": "news" },
  "overlays": [ { "url": "<icon png>", "type": "image", "start": 4.0, "duration": 2.6, "mode": "pip", "x": 50, "y": 28, "size": 26, "rotate": -3, "float": 1.2, "shadow": true, "fade_ms": 160 } ],
  "texts":    [ { "text": "שלב 1 — *הגדרה*", "start": 4.1, "duration": 2.4, "effect": "rise", "preset": "pill", "style": { "y": 44 } } ],
  "music": { "url": "<music>", "volume": 0.3, "duck": false },
  "audio": { "normalize": true },
  "output": { "aspect_ratio": "9:16", "resolution": "1080", "fit": "crop", "quality": "high" }
}
```

Keep the cards off the face: on a selfie video put the icon over the chest (`y` ≈ 56) and the label under it (`y` ≈ 70),
above the news bar. **The example on /skills** (a 58-second phone video, six steps, 27.9.2026): **169 credits** — the cut and
its transcripts 65, a 60-second track 46, the icons free, the render 58.

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`.

## Check the bill

`GET /v1/usage?tag=<job name>` — per call, per operation and the total, in credits. Quote that to the
customer, not the estimate above.

## 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.