# Skill: full/docu — "סיפור עם גרפיקה" (Complete video)

The documentary short: the speaker tells a story and the engine draws its facts — a year that counts up, view counts that stay tiny, a wall of videos filling, a count against the clock with a progress bar, a line chart shooting up, a fortune counting to billions, money raining over him — each on a white flash; the hard years in black and white, a punch-zoom rhythm, captions whose numbers turn green, and an ending held on a blurred frame with the questions that turn the story on the viewer. Gemini watches once and picks the moments; one render.

**Includes:** data cards on the story's facts: a year counting up, view counts, a wall of videos, a count against the clock, a line chart, a fortune in billions, money raining · a black-and-white chapter · a punch-zoom rhythm · two-colour captions (numbers and key words green) · white flashes with a glitch · an ending on a blurred frame with questions · a music bed and a sound kit
**Built on:** the engine's `graphics` cards, `looks`, a punch-zoom rhythm and captions (`hormozi` with a two-colour highlight), laid out by `POST /v1/studio/story`
**Price:** 88–100 credits per finished minute · 30 s ≈ 46–54 credits
**Uses:** `/v1/speech/transcripts` · `/v1/studio/story` · `/v1/ai/text` · `/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.** AssemblyAI transcribes once, Gemini 3.5 Flash (`quality: "balanced"`) watches the video once and picks
the cards; the graphics are drawn by the engine itself (no AI images or video), the sounds and the bed come from the CC0
library. Everything is priced by the video's length.

---

## 1. Transcribe the video (once)

```jsonc
POST /v1/studio/uploads { "filename": "clip.mp4", "content_type": "video/mp4", "size_bytes": <bytes> }   // a local file → output.url (skip for a public link) · the original file, never a resized copy
POST /v1/speech/transcripts { "audio_url": "<video url>", "language_code": "he" }                      // → T0, the video's words
```

**No silence cut.** The story keeps the speaker's own pace — the pauses are where the cards land. Every element the
planner writes is anchored to a word (`at` a word's id, `during` a stretch of them); the render reports where each
one landed (`elements`).



## 2. The first plan — free: the numbered words and the picker call

```jsonc
POST /v1/studio/story
{ "video_url": "<video url>", "transcript_id": "<T0>" }
// → output.words   [ { "i": 0, "id": "w0001", "text": "סרטון", "start": 0.09, "end": 0.52 }, … ]   the numbered words (the video's clock)
//   output.picker  { "system": "…", "prompt": "The video is 95.93 s. Numbered words: 0:סרטון 1:טיפה …" }
```

A read request (1 credit), it answers at once. Without picks the plan is the speaker with the story look only — the
zoom rhythm, the captions, the grade, the music and nothing else.

## 3. Gemini watches the video and picks the moments

```jsonc
POST /v1/ai/text                           // Gemini 3.5 Flash ≈ 15 credits for 1½ minutes of video, ~40 s
{ "quality": "balanced", "json": true, "max_tokens": 6000, "temperature": 0.4,
  "system": "<output.picker.system — verbatim, below>",
  "prompt": "<output.picker.prompt>",
  "media": [ { "url": "<video url>", "type": "video", "fps": 1 } ] }
```

```text
You plan a vertical documentary-style short ("the story of…") over a talking-head video. You WATCH and HEAR the attached video and get its transcript as numbered words (number:word). You choose WHAT goes on screen and WHEN — word numbers and short texts from the speech, never timings. Return JSON only:
{
 "banner": {"text": "short hook (≤ 22 chars)", "sub": "a teaser line (≤ 22 chars)", "until_word": n},
 "cards": [ one per fact the speaker gives, on the words that say it (word = where it appears, until = the last word it stays for, 1.5–5 s):
   {"kind":"stat","word":n,"until":n,"label":"שנה","value":"2017","count_from":2012,"sub":"0 חשיפה"}          — a year / a single number; count_from makes it count up
   {"kind":"views","word":n,"until":n,"values":[187,241,203,298,176,263,44,212],"label":"צפיות"}              — small view counts that keep changing (failure, no audience)
   {"kind":"wall","word":n,"until":n,"from":11,"to":999,"label":"סרטון #"}                                   — doing something every day, many attempts
   {"kind":"counter","word":n,"until":n,"label":"סופר עד","from":0,"to":100000,"ease":"in","timer":{"from":"00:00:00","to":"24:00:00"},"bar":true}   — a count, a challenge against the clock
   {"kind":"counter","word":n,"until":n,"label":"שווי מוערך","from":290111111,"to":3000000000,"prefix":"$","ease":"out","sub":"3 מיליארד דולר"}    — a fortune, a result
   {"kind":"chart","word":n,"until":n,"title":"5 שנים בלי כלום... ואז","x_labels":["2012","2015","2018","2021","2024"],"label":"#1 בעולם"}   — the breakthrough, growth
   {"kind":"money","word":n,"until":n,"text":"עשרות\n*אלפי $*"}                                                    — money coming in (rains over the speaker)
   {"kind":"title","word":n,"until":n,"text":"יש נוסחה\n*להצלחה*"}                                                 — the thesis in two lines, the second accented
 ],
 "dark": {"from": n, "to": n},            — the hard, empty years in black and white (8–20 s), or omit
 "ending": {"lines": ["5 שנים?", "10 שנים?", "*אתה מוכן?*"]},   — 2–3 questions that turn the story on the viewer
 "keywords": [n, …],                      — the words that matter (numbers, years, money, emotional words): they turn green when spoken
 "flashes": [n, …],                       — 1–3 more beats worth a flash and a punch (a turn in the story)
 "corrections": [{"word": n, "text": "fixed"}]   — misheard words; "" for a filler not worth a caption
}
The values above are EXAMPLES of the shape — use the speaker's own facts. Rules: 4–9 cards spread over the video, each 1.5–5 s of speech, never two cards on the same words, never a card in the first 5 s; use only facts the speaker says (numbers from the speech); texts in the speaker's language; keep the cards short (a label ≤ 16 chars); a false start at the very beginning ("the video is a bit off…") → corrections "" for those words.
```

The example's real answer (the owner's 96-second video about MrBeast):

```json
{
 "banner": {
  "text": "איך הוא עשה את זה?",
  "sub": "הסיפור של מיסטר ביסט",
  "until_word": 16
 },
 "cards": [
  {
   "kind": "stat",
   "word": 20,
   "until": 25,
   "label": "גיל התחלה",
   "value": "13",
   "count_from": 1
  },
  {
   "kind": "views",
   "word": 33,
   "until": 44,
   "values": [
    100,
    200,
    300,
    150,
    250,
    180,
    90,
    310
   ],
   "label": "צפיות לסרטון"
  },
  {
   "kind": "wall",
   "word": 45,
   "until": 53,
   "from": 1,
   "to": 1825,
   "label": "סרטונים שהעלה"
  },
  {
   "kind": "counter",
   "word": 148,
   "until": 160,
   "label": "ספר עד",
   "from": 0,
   "to": 100000,
   "ease": "in",
   "timer": {
    "from": "00:00:00",
    "to": "24:00:00"
   },
   "bar": true
  },
  {
   "kind": "chart",
   "word": 161,
   "until": 187,
   "title": "5 שנים בלי כלום... ואז",
   "x_labels": [
    "2012",
    "2015",
    "2017",
    "2020",
    "2023"
   ],
   "label": "#1 בעולם"
  },
  {
   "kind": "counter",
   "word": 188,
   "until": 198,
   "label": "שווי מוערך",
   "from": 100000000,
   "to": 3000000000,
   "prefix": "$",
   "ease": "out",
   "sub": "3 מיליארד דולר"
  },
  {
   "kind": "title",
   "word": 200,
   "until": 203,
   "text": "יש נוסחה\\n*להצלחה*"
  }
 ],
 "dark": {
  "from": 85,
  "to": 126
 },
 "ending": {
  "lines": [
   "5 שנים?",
   "10 שנים?",
   "*אתה מוכן?*"
  ]
 },
 "keywords": [
  13,
  25,
  26,
  27,
  35,
  36,
  37,
  38
 ],
 "flashes": [
  130,
  163,
  200
 ]
}
```

## 4. The plan with the picks — free

```jsonc
POST /v1/studio/story
{ "video_url": "<video url>", "transcript_id": "<T0>", ...the picks }
// → output.edit     ONE body for POST /v1/studio/edit — every card, zoom, flash and sound anchored to its words
//   output.summary  { "cards": 7, "zooms": 30, "flashes": 3, "sounds": 27, "dark_seconds": 15.2, "ending": true, … }
//   output.timeline [ { "t": 7.24, "what": "stat card until 10.14 s" }, … ]   output.warnings (a card over 6 s is shortened, overlaps dropped)
```

What the plan writes (all of it engine features you can also send yourself — `GET /v1/studio/graphic-kinds`):

- **`graphics`** — each card on its words, entering on a white flash with a chromatic glitch of its main line:
  `stat` (a value counting up, red glow), `views` (a still of the video as a thumbnail, view counts that keep
  changing, a red squiggle drawn under them), `wall` (stills of the video filling a wall behind a counting pill),
  `counter` (a number from → to, a clock and a progress bar; a line that lands when the count ends), `chart` (a line
  drawn left to right with a dot riding the tip and a label that lands at the top), `money` (symbols raining over the
  blurred, green-tinted speaker), `title` (a black card, the second line accented and underlined; the captions step
  aside), `banner` (the opening line in a dark box), `questions` (the ending: the last frame held, blurred and
  dimmed, the lines landing one by one).
- **`looks`** — the dark chapter in black and white (a flash back to colour at its end).
- **`zoom`** — a jump-cut punch rhythm: a new level every 2–4 s on a word (1.0 → 1.3), a short punch on each flash.
- **captions** — 2–3 heavy white words at 73 % of the height; the spoken word yellow, green when it is a number or a
  key word (`keyword_active_color`).
- **`color`** `vivid` with dark corners (`vignette` 0.83) · **`hold_end`** 1.8 s for the ending.
- **sound** — whooshes, hits, ticks and a bell on the cards, a boom into the dark chapter (the CC0 library by default;
  your own kit in `sounds`, each ≈ 4 dB under the voice's peaks), and a driving bed at 0.15 that dips 9 dB whenever the
  speaker talks — the voice stays ≈ 17 dB over it (default pushing-ahead-push_ahead_0.ogg, CC0 — or `music.url` from
  `POST /v1/ai/music`).

## 5. Render

```jsonc
POST /v1/studio/edit   <output.edit>        // x-wait-ms: 90000, then poll GET /v1/executions/{id} · 1080p
```

The answer's `qa` passes on the planned stills (the cards, the held ending) and `elements` lists where every card,
zoom and sound landed. The one gap to know: the cards are drawn by the engine, so a card needs numbers the speaker says —
a story without facts gets the look without the cards.

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.