{"id":"captions-scale","kind":"captions","name":{"he":"גודל","en":"Scale"},"one_line":{"he":"המילה הנאמרת גדלה פי 1.4 ונצבעת בצהוב","en":"Captions synced to the speech in the Scale look — Heebo 900, highlight animation, 5 words at a time."},"listed":true,"version":"1.0","updated":"2026-10-09","when_to_use":["A person talks to the camera and the video needs captions people can read with the sound off.","Captions only — no title, no cut, nothing generated: the cheapest finished video (one render)."],"when_not_to_use":["The video already has burned-in captions (they would be doubled).","There is no speech to caption (music only, silent footage): use an effect or a complete video.","A title is wanted too: add a hook in the SAME render — /skills/captions-<style>+hook-<effect>.md."],"example":null,"preview":{"clip_url":"https://media.gpt.org.il/lookbook/captions-scale-mv19hwb0.mp4","poster_url":"https://media.gpt.org.il/lookbook/captions-scale-mv19hwb0.jpg"},"price":{"unit":"minute","from":61,"to":125,"note":"per finished minute: one render; a silence cut first is a second render (the top of the range)"},"inputs":[{"name":"video_url","type":"video","required":true,"limits":"a public link, or the original recording uploaded (POST /v1/studio/uploads), up to 2 GB","notes":"upload the original as it is (a phone's MOV / HEVC / 4K is fine), never a resized copy"},{"name":"language_code","type":"language","required":false,"limits":null,"notes":"the language spoken in the video: he unless it is another (en, ar, ru…)"}],"outputs":[{"name":"output.url","type":"video","required":true,"limits":"mp4, 9:16 1080p unless the request says otherwise","notes":"the file is deleted 24 hours after it is made: download it and tell the customer"},{"name":"cost","type":"number","required":true,"limits":null,"notes":"GET /v1/usage?tag=<job name> → totals.credits: quote this, not the estimate"}],"steps":[{"method":"POST","path":"/v1/studio/uploads","what":"Only for a file (not a link): get an upload URL, PUT the bytes to output.upload_url with output.headers, use output.url as the video","body":{"filename":"clip.mp4"},"async":false,"optional":true},{"method":"POST","path":"/v1/studio/edit/estimate","what":"The price of the render (the same body)","body":{"video_url":"<the video>","language_code":"he","captions":{"style":"scale"},"audio":{"normalize":true},"output":{"aspect_ratio":"9:16","resolution":"1080","fit":"crop","quality":"high"}},"async":false,"optional":false},{"method":"POST","path":"/v1/studio/edit","what":"One render: the speech is transcribed and the captions burned in, style scale","body":{"video_url":"<the video>","language_code":"he","captions":{"style":"scale"},"audio":{"normalize":true},"output":{"aspect_ratio":"9:16","resolution":"1080","fit":"crop","quality":"high"}},"async":true,"optional":false},{"method":"GET","path":"/v1/executions/{id}","what":"Poll a call that answered processing until it is completed (the file is output.url)","body":null,"async":false,"optional":false},{"method":"GET","path":"/v1/usage","what":"?tag=<job name>: what the whole job cost — quote it to the customer","body":null,"async":false,"optional":false}],"rules":["Show the customer the price (POST <path>/estimate with the same body, or the price above) and wait for their OK before any paid call.","Send Idempotency-Key: <job>-<step> on every POST. After a timeout send the same call with the SAME key — you get the same job back, never a second charge.","A long call answers status processing: poll GET /v1/executions/{id} every 5–10 s (or send x-wait-ms, up to 90000). Never send the job again to see whether it finished.","Send the same X-Tag: <job name> on every call of one job; GET /v1/usage?tag=<job name> is then what it really cost.","A caption style, a hook and effects are ONE job: put them in the same POST /v1/studio/edit (one render, the price of captions alone). Never render twice, and never caption a video that already has burned-in captions.","Hebrew has no capitals: keep uppercase false (it only breaks the Latin words inside a Hebrew line).","Keep text inside the middle 80% of the frame: side_margin ≥ 6, margin ≥ 12 — the platform's buttons cover the rest.","Check the words against the speech before burning them in: a phrase lost by the speech model is transcribed again with speech_models [\"universal-2\"] and the words sent as `words`."],"common_errors":[{"code":"invalid_input","why":"400: a field is missing, misspelled or out of range — the message names it","fix":"Fix exactly that field and send again; send only the fields the recipe or the docs show."},{"code":"unauthorized","why":"401: the API key is missing, wrong or revoked","fix":"Ask the customer for a valid key (keys are made at /api-keys); never print it back."},{"code":"insufficient_credits","why":"402: the balance does not cover the estimate (details.required_credits)","fix":"Tell the customer the price and that the balance is short; do not retry until they top up."},{"code":"rate_limited","why":"429: too many calls a minute","fix":"Wait the retry-after seconds, then send the same call with the same Idempotency-Key."},{"code":"failed","why":"the execution's status is failed or timeout — nothing is charged for failed work","fix":"Read error.message, fix the input, and start again with a NEW Idempotency-Key."},{"code":"upload_too_large","why":"413: the file is bigger than the call takes","fix":"Upload the original through POST /v1/studio/uploads and send its output.url; never shrink the picture's shape."}],"quality_check":["The captions follow the speech word by word, from the first word to the last, and no line leaves the frame.","Names, brands and numbers read as they were said — fix a word with captions.captions (GET /v1/speech/transcripts/{id}/captions) and render again only if one is wrong.","Watch the start, the middle and the end of the result before handing it over — not only its status.","Read `warnings` in the answer (a font swapped for the language, a picture that had to be enlarged) and tell the customer what they mean."],"tags":{"domain":"edit","level":"basic","hebrew":true,"recommended":false,"new":false,"creator":false,"topics":["captions","highlight"]},"links":{"recipe":"/skills/captions-scale.md","docs":"/docs?tool=captions","run":null}}