User guide

What Colomred does

One brief in, one finished master out — with as much or as little control as you want on the way.

You write an idea. Colomred writes the script, designs the visuals, generates a keyframe for every shot, animates each shot into a clip, records narration, burns in captions, applies your watermark and renders a real MP4 on the server with FFmpeg. Nothing is a mock: the file you download plays anywhere.

Two things make it different from a single-model generator. First, nine providers sit behind one engine layer, chosen per production and even per asset kind — the script can come from one vendor and the video from another. Second, generation is resilient per shot: if one clip fails, that clip is retried or regenerated on its own, and the rest of the production is untouched.

Getting started

Three steps from an empty account to a first playable master.

1. 1
   Create your account

   Open Create account from the landing page. Your name, an email and a password of at least 8 characters. The first account on a fresh installation becomes the platform administrator and owns a workspace — every account after it is a regular user.

2. 2
   Connect a provider key

   Go to Settings & BYOK → API & Voices, pick a provider and paste its key. The key is tested against that provider before it is saved, then sealed with AES-256-GCM. It is never shown again — only a hint such as sk-…4f2a.

3. 3
   Create a production

   On Projects, choose Fast-Track or Agentic Studio, describe your idea, and press Generate project. Fast-Track runs to completion unattended; Agentic Studio stops at each review gate for your approval.

If you would rather not use a key yet, press Use simulator key (Agnes) in Settings. It fills the form with sk-sim-demo. Saving it puts the app into simulation: the director returns deterministic mock manifests and the clips are two real public MP4s, so a project still renders a genuine, playable, captioned master. It is the fastest way to learn the interface, and the fastest way to confirm a problem is in your provider key rather than in the app.

Providers, models and the engine picker

Nine providers, one interface, chosen independently for script, images and video.

At the bottom of the create form you choose which provider generates each kind of asset. The three choices are independent: a production can write its script with one vendor, its keyframes with another and its clips with a third.

The model field is free text, not a fixed list. Leave it empty to take the provider's default, or pick from the suggestions and edit them freely — anything you type is sent to the provider verbatim. The suggestions come from live discovery where a provider publishes a model list, merged with a short curated list that is used when discovery cannot run.

Providers whose models differ in what they accept are handled automatically. OpenRouter's video models, for example, disagree about clip length and aspect ratio — the app reads each model's published constraints and snaps your request onto values that model accepts, rather than failing the shot.

Creating a production

Every field on the create form, and what it changes downstream.

The create panel sits on the right of the Projects page. Start by choosing a mode — that choice changes how much of the form is used and how the production runs.

Two things are fixed at creation and cannot be changed later: the content language (the script is already written in it) and the tier recorded for the project, which is what its generation limits are measured against. Everything else — voice, prompts, shots, timeline — stays editable at its review gate.

The two pipelines

Same generation graph, different amount of supervision.

Fast-Track (mode1) generates straight through: script → publish → keyframes → clips → audio → assembly. You are not asked anything. It is the right choice when the brief is clear and you want a master with minimal involvement.

Agentic Studio (mode2) adds five planning steps in front and makes every step a review gate: requirements → outline → design → reference images → storyboard → publish → keyframes → clips → audio → assembly → export. At each gate the production parks and waits for you to approve, edit or regenerate. It is the right choice when the look has to be right, or when you want the script and the visual bibles under your control before any expensive generation happens.

A production advances by itself. An in-process driver ticks every 6 seconds, and the studio page polls while a step is generating. Both are safe to run at once because advancing takes a database lock rather than a read-then-write. You can close the browser: the driver keeps working and the project is where you left it when you return.

Review gates and the four actions

Approve, Edit, Regenerate, Retry failed — and what each one costs you.

At a gate the studio shows what the step produced and offers a small set of actions. They are not interchangeable, and the difference matters because two of them spend money again.

Editing is available at every gate. The planning steps (requirements, outline, design) present the agent's JSON as a readable summary with an Edit JSON toggle for direct control; invalid JSON is reported and nothing is saved until it parses. The storyboard and script gates present each shot as an editable card — title, description, narration, image prompt, motion prompt, shot scale and camera angle. The audio and assembly gates have their own controls, described below.

Individual shots can also be regenerated on their own from the keyframes and clips panels with Regenerate pair and Re-render clip, so a single bad frame never forces the whole step to run again.

What each step produces

A reference for the eleven stages, and what you are looking at in each panel.

In Fast-Track the same generator runs, with script standing in for the storyboard and the planning steps skipped — so a Fast-Track project shows its shots in a single Fast-Track script panel.

Narration, voices and captions

The audio gate decides how the master sounds.

Audio mode controls what ends up in the mix:

• Narration voice only — studio narration over a clean mix. The default, and what most explainer content wants.
• Original clip sound — keeps only the sound generated with each clip, with no narration.
• Narration + Original sound — blends the two. Use the volume control to set how loud the clip sound sits under the voice.
• No Audio — a silent master.

Voices come from Microsoft Edge's neural catalogue, discovered from the local Edge TTS binary — typically a few hundred voices across dozens of languages. The audio gate lists the voices matching your production's content language, and shows the one the master will actually use. If the voice you approved is not in the catalogue for some reason, it is still displayed rather than silently swapped. FFmpeg's flite is the automatic fallback when Edge TTS is unavailable.

Caption offsets let you nudge the subtitles for an individual shot, between −10 and +10 seconds. This exists because narration timing and picture timing do not always agree; if a line lands early or late against its shot, correct it here rather than re-recording.

Assembly and the master render

The last two decisions are the cut and the watermark.

The assembly gate shows the whole production in a preview player with sponsor placements and the watermark already positioned, then gives you two controls.

Transitions. A soft crossfade of 0.35 s, a long crossfade of 0.6 s, or a hard cut. A crossfade blends the last frames of one shot into the next on both picture and audio, which stops two independently generated shots from colliding as a hard edit. Each transition consumes its duration from the master, and the panel shows you the resulting total: shots × length − (transitions × overlap).

The timeline. Every shot has an include checkbox. Turning one off cuts it from the master without deleting the shot — useful when one clip is weaker than the rest but you do not want to regenerate anything.

Press Render master to produce the MP4. Rendering is the CPU-bound step, so it is capped separately from generation, per plan. Starting a render while your workspace is at its cap returns a message naming the plan limit rather than queueing silently. When it finishes, the panel reports the render status, duration, audio mode and file size.

Downloads and deliverables

Five artifacts come out of a finished production.

A completed render offers a set of downloads. Reopening the production later offers the same files for as long as the render exists.

Every file is served from the production's own render directory and is private to your workspace. Re-hosted media — keyframes, clips, brand logos — is content-addressed and immutable, so a URL stays valid and a repeated run never duplicates storage.

Brands, sponsors and the watermark

Two ways to get a product into the picture — and how to place your mark on it.

Sponsorship here is placement, not overlay. Sponsors with an active catalogue do not get a banner pinned over the video: their products are written into the scene's image and motion prompts, so they appear worn, carried or used within the shot. That is why the app generates a branded product catalogue image per sponsor — a reference sheet the shots are generated against, so the product stays recognisable from one shot to the next.

There are two sources of placement. By default a production draws on the sponsor network, configured by an administrator under Admin → Sponsor Network. If your plan allows it you can instead tick Use my Brand Kit at creation and use your own brand for that production — the checkbox is hidden on plans that require the sponsor network.

Watermark placement is configured on the same screen. Pick one of nine positions — the four corners, the four edges or the centre — and set the mark size as a percentage of the master width, from 4 % to 60 %, with presets at 8, 12, 18, 25, 35 and 50. A live preview shows the result on a 16:9 frame using your actual logo. The mark is also capped at 45 % of the frame height, so a tall logo can never dominate the picture. On plans with a mandatory sponsor network the sponsor watermark is always on; other plans can set or clear their own.

Workspaces, team and plans

How work is separated, shared and billed.

Everything you create lives inside a workspace. Projects, keys, brands, watermark settings and storage all belong to the workspace, not to your user — which is what makes a workspace a clean boundary for a team or a client.

The workspace picker in the sidebar switches between the workspaces you belong to, and the + beside it creates a new one. On Settings & BYOK → Workspace & Team you can rename the active workspace, invite an existing Colomred account by email, and remove members. Seat limits apply: an invite beyond your plan's seat count is refused.

The Plan tab switches the workspace tier. Each tier caps seats, concurrent generation, concurrent renders, storage and available export resolutions.

A paid plan is bought as a prepaid term, not as a subscription. One payment covers a fixed period — a month or a year — and nothing renews on its own: there is no recurring charge and no cancellation step, because nothing is scheduled to happen that would need cancelling. Where the operator has switched payments on, the plan's button opens the processor's own checkout — card, PayPal or Bitcoin, whichever this installation offers — and the workspace is upgraded the moment the processor confirms the payment, usually within seconds. The page you land on afterwards waits for that confirmation and reports it. A plan the operator has priced at zero is never sold at checkout; those are arranged by writing to the operator.

When a term ends the workspace returns to Starter, and nothing is deleted. Every project, video, brand, key and setting stays exactly where it is. What stops is the plan's extra capacity — fewer simultaneous renders, 720P exports and a sponsor line on new renders. You are emailed 7 days before a term ends and again 1 day before, and the Plan tab shows the date your access runs to. Buying the same plan again extends the term you already have instead of restarting it. Buying a different plan replaces the time that is left rather than prorating it, and the checkout tells you how many days that would discard before you pay.

Keys and security

What happens to your credentials, and in what order they are used.

Colomred is BYOK — bring your own key. Keys are validated against their own provider before being saved, so a typo is caught immediately instead of failing a production twenty minutes later. Once accepted, a key is sealed at rest with AES-256-GCM in the envelope v1.<iv>.<tag>.<ct>. The API never returns a stored key, only a short hint and the time it was last tested.

When a production needs a provider, the key is resolved in this order, and the first one that exists wins:

1. Your own key for that provider.
2. The workspace owner's key — so a team can share one set of credentials.
3. The enterprise key pool — a comma-separated list of extra keys the platform rotates across, available on Enterprise.
4. The platform key from the server environment.

Removing a key is immediate: Remove on any connected provider deletes it, and productions using it stop until another key resolves. The confirmation says so. DELETE /api/keys requires either a ?provider= or an explicit ?all=1, so there is no way to wipe every credential by accident.

Messages, notifications and your inbox

The two ways Colomred reaches you, and how to change either one.

Everything the platform has to say travels by two channels. Email goes to the address on your account. The inbox, in the sidebar, keeps a copy inside the app — the two are sent together, so a message you missed in a crowded mailbox is still waiting here.

The badge beside Inbox is your unread count, and it refreshes while the app is open. The list has a search box, an All / Unread / Archived filter and paging, because a long-lived account accumulates messages. Opening one marks it read; you can also mark it unread again, archive it to get it out of the way without losing it, restore it, or delete it.

Settings & BYOK → Notifications shows the two categories you control, each with a separate switch for email and for the inbox — so you can keep a message in the app while keeping it out of your mailbox. A change applies to the next message sent, not to anything already on its way.

Recovering from failures

Failures are per shot, and the messages usually name the real cause.

Generation is isolated per item. A clip that hits a rate limit returns to pending with a retry time and is tried again on a later pass; a shot that exhausts its attempts fails on its own and the rest of the production carries on. When a step ends with failures, the production's status becomes failed and the studio offers Retry failed.

Provider refusals are translated rather than passed through raw, so the message usually tells you what to change:

Platform administration

For the account that owns the installation.

The Admin area appears in the sidebar only for platform administrators — the account that registered first. It has eleven tabs.

• Telemetry — calls, live requests per minute, active renders and storage over the last 24 hours; a per-kind table of call counts, success rate, average and P95 latency; and the recent upstream errors with the actual provider response.
• Tenants — every user with their role and status, and every workspace with its tier, member count, project count and storage. Roles and statuses are changed inline here.
• Sponsor Network — the global sponsors available to every workspace: create one, replace or remove its logo, pause or activate it, regenerate its AI branding, draw or redraw its merchandise reference sheet, rewrite placement copy, and manage its product catalogue. The platform watermark default is set here too.
• Landing — the copy on the public page: headline, feature cards, the pricing section, the footer, and the six policy and support pages the footer links to — privacy, terms, refunds, disclaimer, cookies and support — each in English and Spanish. Edits are stored as overrides, so a field you have not touched still follows the shipped default when that default changes. The policy pages ship with square-bracket placeholders for your registered company name, address, jurisdiction and support address; replace every one of them before you publish, because the pages are live as soon as they are saved.
• Plans — rename a tier, change what it costs and change what it allows. The pricing cards and the pipeline read the same record, so a change applies to productions that are already running.
• Payments — the processors that take money, and whether a paid plan needs a paid term behind it. Each processor is a card you fill in from its own setup guide: paste the credential and the webhook secret, and the exact webhook URL to paste into the processor's dashboard is printed on the card with a copy button — that is the step most people get wrong. Test asks the processor directly whether the credential works and creates nothing. Every processor you switch on is offered to the customer at checkout; switching one on never switches another off. The payment gate is what makes a plan that is marked as paid actually require payment, and it is off until you turn it on: while it is off nothing is enforced, plans switch freely exactly as before, and payments are only recorded. Turning it on also moves every workspace that is sitting on a paid plan with no paid term behind it back to Starter, so the switch shows you that list — by name — and asks you to confirm it before anything changes. A plan priced at zero is never bought at checkout; you grant its term by hand from this tab instead.
• Messages — write to a segment — everyone, a role, a workspace, or a list of people — and choose the channel: email, the in-app inbox, or both. The audience preview tells you how many people a send will reach before you send it, and the history under the composer shows what each message did.
• Templates — the wording of the three messages the platform sends on its own: the welcome, the password reset and the completion notice, each in English and Spanish. A field you leave blank keeps following the shipped copy, so a later improvement to that copy still reaches you; a field you write is yours until you reset it. The preview shows the subject and the body as a recipient would read them, using sample values and the real origin this installation is configured with.
• Email — the sending providers. Add one, send a test to your own address, and activate it; credentials are sealed at rest and shown only as a short hint. The postal address recorded here is the one marketing messages are required to carry.
• CRM — two views. People searches for a user and shows one timeline of everything that has happened to them: messages sent, deliveries and their status, inbox activity, notes, and the administrative changes made to the account; notes are the only part of that timeline you author. Audit log is the other side of the same record — every administrative action in the installation, newest first, with who did it, what it was done to, what changed and from which address. It is append-only and cannot be edited or deleted from here.
• Rate Limits & Models — the global generation requests-per-minute guard (polling is excluded from it), live video model discovery against the active key with the ability to pin one, and the current security posture — whether the AES master secret and session secret are configured or falling back to development defaults.

Limits reference

The numbers the form and the pipeline enforce.

Troubleshooting

The problems worth checking first.

Generate project is disabled. No provider key resolves for the workspace. Connect one — or use sk-sim-demo — on Settings & BYOK.

A production sits still. A mode2 project at a review gate is *waiting for you* — that is the design, not a stall. A mode1 project with no render running should be moving within a few seconds; check that the server is up and that the driver is running (it starts with the server).

The language is wrong. The content language is fixed when the project is created, because the script is already written in it. Changing the voice will not change the language of the narration text. Start a new production with the right language.

A download 404s. The render does not exist yet, or was removed with the project's render directory. Re-render the master.

One clip failed and the rest succeeded. Press Retry failed. It resets only the failed rows, so the successful shots are not regenerated or paid for again.

Everything fails with the same message. That points at a credential, a region or an account condition rather than at the production — the messages in Recovering from failures say which.

The interface is in the wrong language or theme. Use the language and theme switchers at the bottom of the sidebar. Both are saved to your account and follow you between sessions.

Running the platform

For whoever hosts the installation.

1. 1
   Configure

   Copy .env.example to .env and fill in DATABASE_URL, AES_256_MASTER_SECRET and SESSION_SECRET, plus any provider keys you want available platform-wide.

2. 2
   Create the schema

   Run npm run db:push. This is required — the app has no automatic migration, and every query fails with relation "users" does not exist until it has run.

3. 3
   Build and start

   npm run build then npm run start. The pipeline driver starts with the server, so nothing else needs to be scheduled.

Beyond npm the host needs `edge-tts` for narration — it falls back to flite, then to a plain tone, so a missing install degrades rather than breaks. Expect one build warning about an unexpected file in the NFT list: it is traced to the download route, it is harmless, and it cannot be removed without deleting that route.

Before sending marketing email, configure a provider and enter its postal address in Admin → Email. CAN-SPAM and CASL require a real physical address on every promotional message, and the composer refuses to send without one rather than mailing a placeholder. Transactional mail — password resets, completion notices — does not need it, so a fresh installation can recover a locked-out account before any of that is set up. The sending domain's SPF, DKIM and DMARC records are the provider's job; the app signs nothing itself, which is why a transactional API is the supported transport and SMTP is the fallback.

Payments need that public origin too, and for a different reason. A processor confirms a payment by delivering a webhook to PUBLIC_BASE_URL, and the exact address to paste into its dashboard is printed on its card in Admin → Payments with a copy button. If that variable points at 127.0.0.1, a customer can pay and the workspace will never be upgraded — the delivery has nowhere to arrive, and no page in the app can fix it after the fact. Nothing reconciles a payment that never arrived: the term is granted by the webhook, not by the customer returning to the site.