Create a video
kleo_create_videoStep 3. ASK FIRST, THEN CALL. Do not call this until the user has said, in their own words, what the video should be about. If the subject is YOUR idea and not theirs — you suggested a topic, or you filled a vague request in with your own guess — stop and ask them, and wait for the answer. A render spends a credit they cannot get back once it starts and takes about twenty minutes, so a video nobody asked for is not a fast answer, it is a wasted one. When their request is short but clear ("a Short about pirates"), that is enough: do not interrogate them. When it is missing the subject entirely, ask for the subject and nothing else. Starts rendering, in the chosen look (realistic or animation), either the FILM — every shot generated as moving footage from its own frame, narrated, 4K 60 fps; for accounts that have bought a credit pack (kleo_account → has_paid) — or the ANIMATIC of the same storyboard (product: "animatic": the drawn frames with the camera moving over each one, same narrator and layer, no generated clip; 5 credits up to 20 seconds, 10 up to 60 seconds, every account) — from a prompt, a length, a format and the user's two answers about music and subtitles (plus your storyboard from kleo_storyboard_guide, if you wrote one). The price follows the length for a film (1 credit buys 1.5 seconds of film, 10 credits minimum: 10 credits for a 15-second film, 20 for a 30-second Short, 40 for a minute, 200 for five minutes; an animatic of the same storyboard (the drawn frames with camera moves and the narration, no generated clip, up to 60 seconds) costs 5 credits up to 20 seconds, 10 up to 60 seconds); the tool answers with the exact credits before anything is charged, and a render takes 25-35 minutes on a rented GPU (an animatic fifteen to twenty). Returns at once with the video number (job_id), the estimated minutes (eta_min) and the credits used; the render runs on a GPU in the background. Tell the user the number and the estimate, then offer to check progress with kleo_get_job. Pass the "spec" and the "treatment" the user approved, the handles of their reference pictures as "references", their must_keep / audience / tone answers, and their "corrections" after the read-back in their own words when they gave any: the film is planned under the spec and every picture is checked against it. If the tool returns an error, nothing was charged: fix what it says and call again.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| spec | No | The SPEC you wrote under kleo_adapt_prompt's spec method (or the one it returned), corrected as the user asked: {v:1, mode, summary, cast, items, refs, open, narration, script}. Every item's "quote" must be the user's own words from the prompt, from their must_keep/audience/tone answers, or from their "corrections" after the read-back (pass those too). Checked before anything is charged; the film is planned under it and every picture is checked against it. | |
| tone | No | The tone the user asked for. | |
| music | No | The user's answer about music, exactly as you passed it to kleo_adapt_prompt: "no" (or null) for none; "yes" or the kind they want for an instrumental track under the narration (the treatment's "music" brief is used when it has one). Kleo has the track composed by Suno and ducks it under the voice. | |
| style | No | The look: "realistic" (cinematic live action) or "animation" (a 2D animated film); both narrated; every shot starts as one frame drawn in that look — a generated clip in the film, a camera move over the frame in the animatic. Pass the treatment's "look"; when omitted the treatment decides, and realistic when nothing says. | |
| voice | No | Voice id from kleo_list_templates (narrator-en-m, narrator-en-f, narrator-it-m, narrator-it-f). The engine ids used inside a storyboard (am_michael, af_heart, bf_emma, im_nicola, if_sara) are accepted too. Optional. | |
| format | Yes | 16:9 for YouTube/landscape, 9:16 for a Short/TikTok/Reel, as the user said or answered it. Required: Kleo never picks a frame for the user. | |
| prompt | Yes | What the video is about, IN THE USER'S OWN WORDS (8 to 4000 characters): topic, angle, facts, names, tone, anything that must appear on screen. If you are about to write this field out of an idea of your own, that is the sign to ask them instead: the credit and the twenty minutes are theirs, so the subject has to be theirs too. | |
| product | No | The product the user chose in the intake (kleo_adapt_prompt asks it, with the prices): pass it. What to make from the storyboard: "film" (default; every shot a generated clip, priced by length, for accounts that have bought a credit pack) or "animatic" (the same drawn frames with the camera moving over each one, the same narrator and layer, 4K 60 fps, no generated clip; 5 credits up to 20 seconds, 10 up to 60 seconds, every account). Say which one you are ordering to the user before you call. | |
| audience | No | Who the film is for, as the user said it. | |
| language | No | Voice and caption language: the narration language the user chose, as kleo_adapt_prompt's "language" returned it (the intake asks it; never the language of the chat). A storyboard you pass must declare this same language. | en |
| template | No | Optional; the only one is "film" (realistic or animated, 16:9 for YouTube or 9:16 for Shorts; 15 to 300 seconds for a film, 15 to 60 for an animatic). Omit it. | |
| must_keep | No | The user's answer to "what must appear, or must not", as passed to kleo_adapt_prompt. | |
| subtitles | No | The user's answer about burned-in subtitles: true/"yes" for thin cinema subtitles in the picture, false/"no" for none. An .srt file is delivered either way. | |
| treatment | No | The treatment object kleo_adapt_prompt returned for this request, unchanged or edited as the user asked (logline, angle, device, opening, ending, acts, visual, pacing, narrator, motifs, decisions, prose, variation). Kleo plans the direction and every scene under it. Checked before anything is charged; on error the tool lists the problems. Omit it and Kleo writes a treatment itself while planning — the user just never sees it first. | |
| ai_upscale | No | The user's answer to the AI upscale question kleo_adapt_prompt asked (film only): "yes" for Real-ESRGAN + RIFE on every shot, at the extra credits the intake quoted (refunded automatically if the finish cannot apply it); "no", or omitted, for the classic 4K 60 fps finish. | |
| duration_s | Yes | Length in seconds, as the user said or answered it (kleo_adapt_prompt asks when the request does not say). Required: Kleo never picks a length for the user. | |
| references | No | The user's reference pictures: the handles (kref_…) kleo_adapt_prompt returned, or the token of a kleo_upload_link link they uploaded through. Kleo draws the characters from them. | |
| storyboard | No | Optional but recommended: the storyboard you wrote following kleo_storyboard_guide (a Keou project object without id, script_file, music_quiet or image scenes). IT MUST INCLUDE THE "direction" BLOCK the guide asks for first — a storyboard without one is refused, because the direction is what keeps a character the same person across shots and gives every scene the colour of its section. Its format and language must equal the ones you pass here, and its voice must belong to that language. When omitted entirely, Kleo plans the whole storyboard, direction included, from the prompt. Checked before anything is charged; on error the tool lists the problems so you can fix them and call again. | |
| corrections | No | The user's corrections after you read back what Kleo understood, IN THEIR OWN WORDS ("add my dog Pepe with a red collar", "she has red hair, not blonde"). The prompt stays their first request, unchanged; a spec item added by a correction quotes these words. Omit it when they simply said yes. | |
| notify_email | No | Optional: email the download links when the render finishes. |