# Skill: Kinetic short-form editor (APIhub)

Turn one vertical talking-head video into a fast, modern short (Reels / TikTok / Shorts) in the kinetic
style: big typography, acid-yellow accents, quick scene changes, metaphor visuals, split screens,
punch-ins, and word-level captions.

You need nothing but this API and the video URL. Plan from the **transcript only** — do not send frames to a
vision model unless the user asks. The render is deterministic: you build one JSON body, the API renders it.

Base URL: `https://apihub.co.il` · Auth: `Authorization: Bearer <API key>` · Docs: `/docs`
Tag every call of one video with the same `X-Tag: <job name>` header, then `GET /v1/usage?tag=<job name>`
returns what the whole video cost.

---

## 1. The pipeline (6 calls + assets)

1. `POST /v1/studio/remove-silence` — jump cuts. Body: `{video_url, language_code, min_pause_ms: 350,
   padding_ms: 70, remove_fillers: true, output: {resolution: "source", aspect_ratio: "original", quality: "high"}}`.
   Returns the cut video. **Everything after this is timed on the CUT video's clock.**
2. `POST /v1/speech/transcripts` on the cut video → `transcript_id`.
3. `GET /v1/speech/transcripts/{id}/sentences` → sentences with start/end in ms. This is your edit map.
4. Decide the plan (section 2) — which sentence gets which visual, text, zoom and sound.
5. Generate the assets you planned, in parallel:
   - `POST /v1/ai/image` `{prompt, aspect_ratio: "9:16", resolution: "1K"}`
   - `POST /v1/ai/video` `{prompt, aspect_ratio: "9:16", resolution: "720p", duration: "4"}` (~60–180 s, send `x-wait-ms: 110000`)
   - `POST /v1/ai/music` `{prompt, duration: <video seconds + 2>, instrumental: true}`
   - `POST /v1/ai/sound-effects` `{text: "short whoosh", duration: 1}`
6. `POST /v1/studio/edit` with the full body (section 3) and `x-wait-ms: 110000`. Poll
   `GET /v1/executions/{id}` while `status` is `processing`: `output.eta_seconds` says about how long is
   left (tell the user "about N min"), `output.progress` (a percent, 0–100) moves once `output.stage` is `rendering`.

**Model quality.** Every AI endpoint takes `quality`: `fast` · `balanced` (the default) · `best`, or an
explicit `model`. Use `balanced` unless the user asked for the best; `best` on video is Veo 3.1, which
costs about 4× the Fast one (≈ 800 credits for a 4 s clip instead of 200). Ask before spending that.
A shot where someone speaks on camera, or with text that must be readable in the frame: `model:
"gemini-omni-1.1-flash"` (Gemini Omni, Google's newest video model — native sound and speech: write the line in
quotes, e.g. `says in Hebrew: "…"`; `image_url` is the start frame, or up to 3 `reference_images` named
<IMAGE_REF_0>… in the prompt). It picks the length itself (3–10 s, usually 10) and bills what it made: ≈ 310
credits at 720p, ≈ 460 at 1080p. For a silent 3 s insert, Veo Fast stays the cheaper choice.

Never build visuals yourself as text on a black background — that is what the generators are for.
Unknown fields are rejected with the name of the right field, so read the error instead of guessing.

---

## 2. Planning rules (from the transcript)

**Beats.** Split at punctuation and pauses of 250–500 ms. A beat is 0.4–1.4 s. Mark one keyword per beat.
Change the layout every 2–4 beats; one big metaphor visual per 6–10 s. Never start two hero effects at once.

**Semantic triggers**

| In the sentence | Do this |
|---|---|
| a number, sum or percentage | `texts` with preset `mega`, on a `panels` colour card |
| "אבל" / a contrast | white flash (`panels`, 0.12 s, `#FFFFFF`) then a black card |
| a question | short `zoom` push-in + a `pill` text |
| surprise / punchline | `marker` text (the yellow highlight wipes in) |
| a concrete object (eye, money, phone, hook, fire) | `overlays` image from `/v1/ai/image`, `mode: "full"` or `"split"` |
| audience, likes, views, comments | 2–3 small `pip` overlays, tilted (`rotate: ±4`), `float: 1.2`, `shadow: true` |
| a process, product or demo | `/v1/ai/video` clip, `mode: "full"`, 2.2–3 s |
| the closing CTA | black `panels` + `hero` text + `accent` text |

**Timing rules**

- First visual after 3 s; visuals at least 5 s apart; nothing in the last 3 s except the CTA.
- A full-screen visual hides the speaker: keep each to 2.2–3 s, and never over the punchline.
- A zoom must not overlap a full-screen overlay.
- Sound effects: a whoosh 0.3 s before each visual, a pop on a text entrance, a hit on a mega number.

---

## 3. The request body

```jsonc
{
  "video_url": "<cut video url>",
  "transcript_id": "<from step 2>",
  "captions": { "style": { "preset": "classic", "font": "Heebo", "weight": 900, "size": 7,
    "color": "#FFFFFF", "active_color": "#D0F808", "active_background": null,
    "outline": 10, "shadow": 4, "animation": "pop",
    "position": "bottom", "margin": 20, "side_margin": 6, "max_words": 3, "max_lines": 1 } },
  "hook": { "text": "<6 words, from the content>", "duration": 3.2,
    "style": { "preset": "yellow", "font": "Rubik", "weight": 900, "size": 6.4, "margin": 10 } },
  "panels": [ { "start": 8.0, "duration": 0.12, "color": "#FFFFFF", "fade_ms": 30 },
              { "start": 8.12, "duration": 2.4, "color": "#FFFFFF", "fade_ms": 60 } ],
  "texts":  [ { "text": "2,400 סרטונים", "start": 8.3, "duration": 1.0, "preset": "mega",
                "style": { "color": "#111111", "y": 38 } },
              { "text": "בלי עורך אנושי", "start": 9.4, "duration": 1.1, "preset": "marker",
                "style": { "y": 55, "rotate": -2 } } ],
  "overlays": [ { "url": "<ai image/clip>", "type": "image", "start": 12.5, "duration": 2.5,
                  "mode": "split", "split_side": "top", "split_ratio": 0.55, "speaker_focus": 0.3, "fade_ms": 180 } ],
  "zoom":   [ { "start": 5.6, "end": 7.0, "to": 1.2, "ease": "punch", "y": 0.35 } ],
  "color":  { "preset": "cinematic", "sharpen": 0.3 },
  "sounds": [ { "url": "<sfx>", "start": 12.2, "volume": 0.5 } ],
  "music":  { "url": "<music>", "volume": 0.3, "duck": false, "fade_in_ms": 700, "fade_out_ms": 2200 },
  "watermark": { "url": "<logo>", "position": "top-left", "size": 10, "opacity": 0.9, "margin": 4 },
  "audio":  { "normalize": true },
  "output": { "aspect_ratio": "9:16", "resolution": "1080", "fit": "crop", "quality": "high" }
}
```

All times are **seconds on the edited (output) timeline**. Every block is optional.

### texts — the kinetic typography

`GET /v1/studio/text-styles` lists the presets with their full settings.

| preset | what it is |
|---|---|
| `hero` | big white headline |
| `mega` | huge number (14% of the height) |
| `accent` | one word in the accent colour |
| `pill` / `pill-accent` | word inside a white / yellow box |
| `marker` | the box wipes in behind the word from the reading side |
| `outline` | hollow letters (coloured stroke, transparent fill) |
| `small` | small supporting line |
| `script` | handwritten (Amatic SC) |
| `type` | typewriter, word by word |

`style` overrides any field: `font, weight, size, color, background, outline, outline_color, hollow,
shadow, letter_spacing, uppercase, rotate, max_chars_per_line, position, x, y, align, side_margin`.
`x`/`y` are percentages of the frame. `effect`: `pop` · `blur_in` · `slide_up` · `typewriter` ·
`highlight` · `fade` · `none`. `exit`: `fade` · `smear` · `blur` · `none`.

A line that would run past the side margins is set smaller automatically — never shrink it yourself.

### panels — colour scenes and flashes

`{start, duration, color, opacity, fade_ms, rect?}`. A white card of 0.1–0.2 s is a flash; a card of
2–3 s with `texts` on top is a full typography scene; `rect` (`{x, y, width, height}` in %) dims part of
the frame behind text. `opacity` 0.9 keeps a ghost of the speaker.

### overlays — visuals

`mode`: `full` (cut-away) · `split` (visual on one band, the speaker re-framed into the other:
`split_side`, `split_ratio`, `speaker_focus`) · `pip` (a card: `x`, `y`, `size`, `rotate`,
`float`, `float_period_ms`, `shadow`).

### inserts — clips placed into the video (with their own in-point and sound)

`{url, start | at | during, duration?, from, mode, audio, transition?}`. An overlay always plays a clip from its
start, silent; an insert starts where you say inside the clip (`from`, seconds) and brings its sound:
`mode` `cut` (the clip replaces the picture; with `audio: "keep"` the sound too — the captions of the words
it covers are left out) · `overlay` (full frame over the video, dissolving; the speaker is still heard) · `pip`
(a box: `position` or `x`/`y`, `size`). `audio`: `keep` · `duck` (under the speech, `duck_db`) ·
`mute` (default). `transition`: `{type: "cut" | "crossfade" | "dip", ms}`. Without `duration` it shows the
rest of the clip; it never runs past the clip or the video (`warnings` says so). Every insert lands on whole
frames and is reported in `elements` (kind `insert`).

---

## 4. Palette and type

Black `#050505` · white `#FFFFFF` · accent `#D0F808` (acid yellow) · dark card `#292929`.
Fonts for Hebrew: Heebo / Rubik (900 for headlines), Amatic SC for handwriting, Secular One for display.
Hero 8–10% of the height, mega 12–15%, body 3.5–4.5%, captions 6.5–7.5%.
Keep the accent colour under ~30% of the frame, and do not cover the face more than ~20% of the time.

## 5. Before you send

- The hook comes from the content, never invented clickbait.
- Every visual matches the sentence spoken at that second.
- Something changes on screen every 1–2 s; the layout changes every 3–5 s.
- The CTA stays on screen at least 0.7 s.
- Captions: 2–5 words, the spoken word in the accent colour.
- Output: 9:16, 1080, `quality: "high"`, `audio.normalize: true`.

## 6. Costs (credits)

Render ≈ 1 credit/second · AI image ≈ 48 · Veo clip 4 s ≈ 200 · music ≈ 1.5/second · sound effect ≈ 2 ·
transcription ≈ 1/minute. A 35 s short with 2 clips, 2 images, music and effects ≈ 650 credits.
Veo is most of it: drop to images only and the same video is ≈ 250 credits.