Send This to your AI Assistant

Calliope Best Practices

Last update: June 27, 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 to 80 seconds. 1.B Long-Form Video: horizontal video from 1 to 60 minutes. 1.C Auto-Broll: a video, usually talking-head, where Calliope adds AI B-Roll; avoid long silent sections, a continuous already-edited video is recommended.

  1. 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:

  1. AI Writer: specific instructions for Calliope to write or refine the narration.
  2. Manual Script: the user already has the exact text that must be narrated.
  3. 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.

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.

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 to 80 seconds.
  • 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 language, 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/v3 voices): optional prompt that guides Eleven v3 expressive tags; the final result varies depending on the selected voice. To use custom ElevenLabs V3 tags, turn this option off and add the tags directly in your script.

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. 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.

From the UI, the user can:

  1. Preview the video and select clips in the timeline.
  2. Edit the prompt of a completed or failed clip and regenerate only that clip.
  3. Change the image/video model for a regeneration when the UI allows it.
  4. Animate available image clips.
  5. Generate a new clip in empty V2 spaces with a custom prompt.
  6. Upload their own images or videos to the timeline.
  7. Adjust timing, split clips and move/trim their own assets.
  8. Edit captions, effects, Motion Graphics, music, SFX, narration volume and music volume from the sidebars.
  9. Move or delete Motion Graphics and SFX badges in the timeline.
  10. Replace uploaded narration when the UI allows it.
  11. Save changes, resume blocked jobs or confirm render.

Recommended hierarchy for visual control:

  1. Use the correct template.
  2. Configure visual style, references and visual frequency before generating.
  3. Keep the script concrete. Specific nouns and actions create better scenes.
  4. Review the first asset plan.
  5. Edit weak scene prompts directly.
  6. 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:

  1. Start from the most similar existing template, not from scratch.
  2. Configure visual style and references.
  3. Configure voice, language, captions, music, SFX, Motion Graphics and model quality.
  4. Save the project.
  5. Reuse that project as a template for future jobs.
  6. For API use, download and read the API Skill.

Visual Style

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.

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 API, captions is only an on/off switch.
  • Omit captions to inherit the template style.

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:

  1. Is it Short or Video?
  2. Which template/project should be used?
  3. Is the source AI Writer, Manual Script or Uploaded Narration?
  4. What is the target duration?
  5. What visual style or references should the template use?
  6. Are captions, music, SFX or Motion Graphics needed?
  7. 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.

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 captions field 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.