Calliope Best Practices
Last update: October 24, 2026.
This guide is for users and AI assistants preparing videos, scripts, narrations, templates, Motion Graphics or API calls for Calliope.
Public version: https://calliopelabs.co/best-practices
1) Content Planning
In Content Planning, choose the video's base format:
1.A Short: vertical video from 20 seconds to 3 minutes. 1.B Long-Form Video: horizontal video from 1 to 60 minutes. 1.C B-Roll on your own video: not a separate format anymore. Upload the video (usually talking-head) in the Editor and use Add B-roll > AI B-Roll: Calliope picks the moments from what is said and adds AI images or animations over them (Stock video B-roll adds free stock clips instead). Avoid long silent sections; a continuous, already-edited video is recommended.
- Template: the visual format that inherits visual style, references, captions, music, SFX, Motion Graphics and models saved in the project/template.
Narration Source
In Content Planning, start with Content Instructions: the global brief or storyboard from which Calliope can create the full video.
Optionally, if you already have a final narration, use a narration source:
- AI Writer: specific instructions for Calliope to write or refine the narration.
- Manual Script: the user already has the exact text that must be narrated.
- Uploaded Narration: the user already has an MP3/WAV audio and wants to use it as-is.
Do not mix narration sources; Content Instructions can accompany any of them as global context.
With No Voiceover (characters speak on camera) there is no narration source: Content Instructions is the storyboard and the only input. Only text in straight "double quotes" is spoken, by the character named before it; unquoted text is a silent scene. Calliope keeps a storyboard that follows these conventions, polishes one that doesn't, or writes one from an idea. Write the dialogue you want: Calliope only adds dialogue when the brief implies a conversation, never in silent formats (ASMR, silent film, timelapse, ambience).
Content Instructions
Can contain visual instructions or others. It is 'general context' about the video.
The textarea can include the topic and general instructions about what the scenes should contain: places, objects, actions, characters, eras or shot types. These instructions help Calliope write a more aligned script and then generate more coherent visual scenes.
They are not an exact editing contract: they do not guarantee 1:1 timestamps, transitions, effects, captions/text overlays, template changes or exact B-Roll position. The final number of scenes is controlled by Calliope according to duration, template, cost/models and selected visual frequency (with No Voiceover, by the storyboard).
AI Writer
Use AI Writer when the user has an idea, but not a final narration script. For +15 min videos, we recommend Manual Script.
Example (the more specific and detailed, the better):
Create a 5-minute video about why Roman roads are the foundation of modern roads.
The first sentence must be exactly: "What would have happened if Roman roads had never existed?"
Structure: Hook + 3 fast points, no long intro: Marcus Aurelius, Roman engineering, drainage + conclusion + CTA.
Tone: curiosity-driven, fast, "what if?" style.
Ending: CTA: "Buy my E-Book! Link in BIO."Manual Script
Use Manual Script when the narration text is already final. For +15 min videos, we recommend this mode.
Write only the words that must be spoken. Do not include:
- Scene numbers.
- Durations.
- Camera instructions.
- Storyboard notes.
- Instructions like "Create a 360-second video".
- Lines like "Scene 1: show a man walking", unless you want those words to be narrated.
Good Manual Script:
What would have happened if Roman roads had never existed? Roman roads are the foundation of modern roads. First, Emperor Marcus Aurelius built a road network to connect his empire... Second, Roman engineering made it possible to build durable roads with several layers of materials... Third, the Roman drainage system prevented flooding and kept roads usable. Without Roman roads, transport and trade would have been much harder, and the modern world would be very different. Buy my E-Book! Link in BIO.To control visuals with precision, generate a first version and then edit the prompts for specific scenes in the Editor.
Uploaded Narration
Use Uploaded Narration when the audio already exists.
Rules:
- Upload MP3 or WAV.
- Shorts: approximately 20 seconds to 3 minutes.
- Videos: approximately 2 to 15 minutes.
- Let Calliope transcribe the audio and align visuals with the real audio.
- Use Content Instructions, the template, visual references, visual frequency and later prompt editing to direct the visuals.
Do not tell the user to paste a long storyboard in the main textarea if they also upload audio. That text is not a separate visual direction field: the real narration source will be the uploaded audio.
Other Settings
From the UI, the user can choose voice, voice quality, preview voices, upload narration, generate script, generate voiceover, regenerate voiceover and select background music once the audio/script has been generated.
Style Instructions: (Enhanced Expressions, High/v4 voices): optional prompt that guides Eleven v4 expressive tags; the final result varies depending on the selected voice. To use custom ElevenLabs V4 tags, turn this option off and add the tags directly in your script. Eleven v4 sliders: Stability and Similarity accept values from 0 to 1, including 0. Video generation uses narration.voice_settings; audio tools use voice_settings. Omit to inherit settings where available; otherwise defaults are 0.5 and 0.75.
Visuals Quality: the user can change image quality, enable/disable animation, choose video quality, choose how often images become animated clips and move the visual frequency slider (hidden with No Voiceover, where the storyboard sets the scenes). Visual frequency is configured with that control, not by writing "generate 22 scenes" in the textarea.
Auto Accept: if enabled, Calliope will generate assets immediately after audio, without script/audio review. If disabled, the user can review before continuing.
We recommend not enabling animation (I2V) unless the template is already optimized for it. It is usually better to click "Animate" in the Editor after checking that the scenes are good. This saves cost if regenerations are needed.
2) Editor
assets, timeline and render
In the Editor, the user reviews the generated content before the final render.
Code-video templates use the prepared narration and create their complete video after Generate. Edit these videos through the chat; their timeline is currently read-only. The individual asset controls below apply to classic videos.
From the UI, the user can:
- Preview the video and select clips in the timeline.
- Edit the prompt of a completed or failed clip and regenerate only that clip.
- Change the image/video model for a regeneration when the UI allows it.
- Animate available image clips.
- Generate a new clip in empty V2 spaces with a custom prompt.
- Upload their own images or videos to the timeline.
- Adjust timing, split clips and move/trim their own assets.
- Edit captions, effects, Motion Graphics, music, SFX, narration volume and music volume from the sidebars.
- Move or delete Motion Graphics and SFX badges in the timeline.
- Replace uploaded narration when the UI allows it.
- Save changes, resume blocked jobs or confirm render.
Recommended hierarchy for visual control:
- Use the correct template.
- Configure visual style, references and visual frequency before generating.
- Keep the script concrete. Specific nouns and actions create better scenes.
- Review the first asset plan.
- Edit weak scene prompts directly.
- Regenerate only bad clips instead of restarting the whole job.
Avoid abstract briefs like "make it attractive" or "add cool visuals". Use concrete objects, places, actions and constraints.
Template Workflow
A template is a Calliope project saved as a reusable production format.
To create a good template:
- Start from the most similar existing template, not from scratch.
- Configure visual style and references.
- Configure voice, captions, music, SFX, Motion Graphics and model quality.
- Save the project.
- Reuse that project as a template for future jobs.
- For API use, download and read the API Skill.
Visual Style
All paid plans can use Smart Extract Style with their own uploaded video of at least 30 seconds: it selects 3–7 compatible references and extracts movement direction. Extracting style from a public video link requires Pro or Creator.
In Smart, use the optional prompt (up to 2,000 characters) to say what to retain, focus on or transform, for example “keep the drawing, replace the red palette with blue”. When the source duration is available, select a range of 30 seconds to 30 minutes. Reference images can also be attached in the chat to create a template without extracting from a video.
Important: if you want to add text to the scenes you must specify it explicitly, E.G.: "OBEY this instruction above the rest: I explicitly want text, phrases, symbols or titles inside the images/scenes (As in Refs 1 and 2), diagrams with details or explanations are also allowed (As in Ref 5)". It is highly recommended to add well-labeled Visual Refs that exemplify it.
Graphics-only references
Graphics-only templates create animated scenes from code. Use Graphics Style for reusable drawing and movement direction; voiceover is prepared before the animation. They support Shorts up to 3 minutes and up to 35 reference images.
For motion, one attractive still is not enough. Upload an ordered sequence showing preparation, action and settling, with timestamps or short labels explaining the order. A legible strip of several frames can demonstrate text entrances, character acting or a camera transition without using a separate reference slot for every frame. Choose intervals that actually show the change, rather than almost identical adjacent frames.
Mix these motion studies with references for illustration, colour and composition. Label each sequence by its purpose and keep parts in order, so the chat can consult the relevant study when needed. References guide the result; they are not inserted into the finished film.
Motion Graphics
Use Motion Graphics for reusable overlays: counters, maps, statistics panels, timelines, callouts, labels and brand visual systems.
Rules:
- A Motion Graphic must be visually specific, short and reusable.
- Editable text must be a text variable.
- Finite visual options must be dropdown/choice variables.
- Do not create conceptual variables that do not visibly change the result.
- The selector label must explain when the graphic should appear in a script, not only how it looks.
- Keep Motion Graphics focused. A strong reusable component is better than a generic overlay that tries to do everything.
Example:
Create a reusable Motion Graphic for a history video: a 5-second ancient map callout with a large region, a highlighted route, and a small year label. Make the region and year editable. Make the route style a dropdown with "land", "sea", and "mixed".Captions, music and SFX
Captions:
- Use the template/editor to control the exact style.
- In the editor, selecting a caption style automatically generates missing captions; clipping Shorts also identify speakers. This does not render the video.
- In the API,
captionsis only an on/off switch. - Omit
captionsto inherit the template style. - Smart+ Clips also understand what happens on screen, included with every paid plan at the Smart price. Speech language and Speakers can be adjusted in Clip Settings.
- For Smart/Smart+ clipping,
options.caption_styleselects a caption catalog ID;nulldisables new captions and omission keeps Highlight. Captions already embedded in the source stay unchanged.
Music and SFX:
- Configure them in the template for repeatable formats.
- Use SFX for emphasis, transitions and Motion Graphics.
- In long-form, use SFX moderately unless the format requires them often.
API and automation
API docs: https://calliopelabs.co/api/v1/docs
Checklist for AI assistants
Before writing for Calliope, ask:
- Is it Short or Video?
- Which template/project should be used?
- Is the source AI Writer, Manual Script or Uploaded Narration (No Voiceover: the storyboard only)?
- What is the target duration?
- What visual style or references should the template use?
- Are captions, music, SFX or Motion Graphics needed?
- What should be avoided?
Then generate the correct output for the selected mode:
- AI Writer: write a short and concrete brief for Calliope.
- Manual Script: write only spoken narration.
- Uploaded Narration: use Content Instructions for the visual brief and help the user improve the template, style and post-generation scene prompts.
- No Voiceover: a timestamped storyboard in Content Instructions, with every spoken line in "double quotes" after its speaker.
Common mistakes
- Asking for Motion Graphics, Text Overlays, transitions or Effects in the Content Instructions brief. Calliope does not apply them yet.
- Putting scene instructions in Manual Script as if they were invisible instructions.
- Using vague visual requests instead of concrete subjects and actions.
- Creating a new template before trying a similar existing one.
- Expecting the API
captionsfield to control the detailed captions style. - Asking for exact scene timing before knowing the narration/audio.
- Regenerating the whole job when only one clip prompt needs editing.
Troubleshooting
- A regenerated scene looks identical to the previous scene: ask the editor chat or your AI assistant to regenerate it with
need_prev_frame:false(when true, the previous scene's image is attached as a continuity base).