---
title: "Plan a documentary-style story with data graphics"
method: POST
path: "/v1/studio/story"
tags: ["Edit"]
---

# Plan a documentary-style story with data graphics

`POST /v1/studio/story`

## Request

- Base URL: `https://apihub.co.il`
- URL: `https://apihub.co.il/v1/studio/story`
- Auth: HTTP bearer

Turns a talking-head video that tells a story into ONE ready body for POST /v1/studio/edit in the documentary look: the speaker in a vivid grade with dark corners and a jump-cut punch-zoom rhythm, captions of 2–3 heavy words with the spoken word in yellow (green for numbers and key words), and data cards on the story's facts — a year counting up, view counts that stay tiny, a wall of videos filling, a count against the clock with a progress bar, money raining, a line chart shooting up, a fortune counting to billions, a black title card — each on a white flash; a black-and-white chapter for the hard years; the ending held on a blurred frame with the questions that turn the story on the viewer; a driving music bed and a sound kit (CC0 by default). Every element is anchored to the words of the video's transcript. You send the picks (which card on which words); the answer carries the picker call — POST /v1/ai/text with the video as `media` returns them. Nothing is rendered here. Recipe: /skills/full-docu.md

**Billing:** Read request — the plan is free; the render is POST /v1/studio/edit · **Rate limit:** 60/min

## Headers

- `Idempotency-Key` string
- `X-Tag` string

## Request body

- object
  - `dark` object: The hard chapter in black and white
    - `to` integer, required
    - `from` integer, required
  - `cards` union[]: The data cards, each on the words that speak of it
    - union
      - object
        - `sub` string: The coloured line under the value ("0 חשיפה")
        - `kind` 'stat', required
        - `word` integer, required: The word the card appears on (its number)
        - `label` string: Small line above the value ("שנה")
        - `until` integer, required: The last word it stays for
        - `value` string, required: The big value ("2017", "0", "$3B")
        - `count_ms` number
        - `count_from` number: Count up (or down) to `value` from this number when it appears — e.g. 2012 for the year 2017
      - object
        - `to` number, required
        - `bar` boolean: A progress bar filling with the count
        - `sub` string: A line that lands when the count ends ("3 מיליארד דולר")
        - `ease` 'in' | 'out' | 'linear': in = slow then racing (a count to 100,000); out = racing then settling (a fortune)
        - `from` number, required
        - `kind` 'counter', required
        - `word` integer, required: The word the card appears on (its number)
        - `label` string: Small line above the number ("סופר עד", "שווי מוערך")
        - `timer` object: A clock running with the count ("00:00:00" → "24:00:00")
          - `to` string, required
          - `from` string, required
        - `until` integer, required: The last word it stays for
        - `prefix` string: "$"
        - `suffix` string
        - `count_ms` number: How long the count runs (default: 90% of the card)
      - object
        - `kind` 'views', required
        - `word` integer, required: The word the card appears on (its number)
        - `label` string
        - `until` integer, required: The last word it stays for
        - `values` integer[], required: The view counts shown one after another
        - `squiggle` boolean
        - `thumbnail_at` number: Second of the SOURCE video the thumbnail is taken from (default: the moment the card starts)
      - object
        - `bw` 'alternate' | 'none' | 'all': Which stills are black and white
        - `to` integer, required
        - `from` integer
        - `kind` 'wall', required
        - `rows` integer
        - `word` integer, required: The word the card appears on (its number)
        - `label` string
        - `until` integer, required: The last word it stays for
        - `columns` integer
        - `fill_ms` number: How long the wall takes to fill (default: 85% of the card)
        - `sources` number[]: Seconds of the SOURCE the stills come from (default: spread over the video)
      - object
        - `kind` 'chart', required
        - `word` integer, required: The word the card appears on (its number)
        - `curve` 'exponential' | 'linear' | 's'
        - `label` string: Lands at the top of the line when it is drawn ("#1 בעולם")
        - `title` string: Small line at the top ("5 שנים בלי כלום... ואז")
        - `until` integer, required: The last word it stays for
        - `values` number[]: Your own points, left to right (scaled to the chart); replaces `curve`
        - `draw_ms` number: How long the line takes to draw (default: 80% of the card)
        - `label_ms` number: When the label lands, ms after the card starts (default: when the line is drawn)
        - `x_labels` string[]
      - object
        - `kind` 'title', required
        - `text` string, required: One or two lines (\n); *word* = accent — "יש נוסחה\n*להצלחה*"
        - `word` integer, required: The word the card appears on (its number)
        - `until` integer, required: The last word it stays for
      - object
        - `kind` 'money', required
        - `text` string, required: One or two lines (\n); *word* = the accent colour — "עשרות\n*אלפי $*"
        - `word` integer, required: The word the card appears on (its number)
        - `until` integer, required: The last word it stays for
        - `symbol` string
  - `music` union: The bed (default: a CC0 driving track at 0.15, dipping 9 dB under the voice — the voice stays ≈ 17 dB over it); false for none
    - false
    - object
      - `url` string, uri, required
      - `volume` number
  - `words` object[]: Or the video's timed words yourself (ms, the video's clock)
    - `id` string
    - `end` number, required: ms
    - `text` string, required
    - `start` number, required: ms
    - `spoken` string
    - `speaker` string, nullable
  - `banner` object: The opening line in a dark box at the top ("5 שנים. 0 תוצאות." / "ואז זה קרה...")
    - `sub` string
    - `text` string, required
    - `until_word` integer: It stays until this word is said (default: ≈ 4 s)
  - `ending` object: The last frame held, blurred and dimmed, the questions landing one by one
    - `hold` number
    - `lines` string[], required: *line* = the accented last question
  - `sounds` object: Your own sound kit (default: the CC0 library)
    - `hit` string, uri
    - `pop` string, uri
    - `bell` string, uri
    - `boom` string, uri
    - `riser` string, uri
    - `slomo` string, uri
    - `swish` string, uri
    - `glitch` string, uri
    - `scroll` string, uri
    - `whoosh` string, uri
  - `source` object: The video's length and frame rate. The endpoint fills it (a probe of the video)
    - `fps` number, required
    - `duration` number, required: seconds
  - `flashes` integer[]: Extra white flashes with a punch zoom, at these words
  - `captions` boolean
  - `keywords` integer[]: Words that turn green when spoken (numbers do it on their own)
  - `video_url` string, uri, required: The source video (a public link or an upload's url)
  - `resolution` '720' | '1080' | 'auto': auto: 1080 up to 100 s of video, 720 above (a long story at 1080 would outlast the render's time limit)
  - `corrections` object[]: Fix a misheard word by its number; "" hides a word from the captions (a filler the story skips)
    - `text` string, required
    - `word` integer, required
  - `transcript_id` string: The transcript of the video itself (POST /v1/speech/transcripts on its url)

## Response `200`

Completed

- object
  - `id` string: Execution id — stable across internal retries; use it with GET /v1/executions/{id}
  - `status` 'pending' | 'processing' | 'completed' | 'partial' | 'failed' | 'cancelled' | 'timeout'
  - `operation` string
  - `tag` string, nullable: Your X-Tag, if sent
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `output` object: Operation result (see each operation). While a Studio render is processing: `stage` (queued · transcribing · downloading · preparing · cleaning_voice · mixing_audio · rendering · finishing), `phase` (the engine's: download · prepare · voice · audio · encode · qa · upload, or null), `progress` (a percent, 0–100) and `progress_fraction` (0–1), `eta_seconds` (seconds left, never below 0) and `estimate_seconds`
  - `error` string, nullable
  - `usage` object
    - `credits_charged` number, nullable
    - `credits_reserved` number
    - `estimated_credits` number
    - `cost_source` 'provider_reported' | 'calculated' | 'estimated' | 'null', nullable
    - `provider_usage` object, nullable: Normalised consumption, e.g. { VIDEO_SECOND: 22.4 }
  - `balance` object
    - `available` number
    - `reserved` number

## Other responses

- `400`: Invalid input
- `402`: Insufficient credits / project budget
- `404`: Resource not found (or not yours)
- `429`: Rate limited
- `503`: Service temporarily paused

---

[API](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai.md) · [All operations](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/llms.txt) · [OpenAPI document](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/revisions/a8caa42835ce?raw)