Apito is an independent third-party API access platform. It is not affiliated with, endorsed by, or an official partner of Anthropic, OpenAI, Google, or other model providers.
A polished collage video is not one generation. It is a production line.
The script needs to be divided into beats. References must be selected, people separated from backgrounds, and visual rules kept consistent. Motion, narration, music, subtitles, timing, and final rendering then have to agree with one another.
vox-director packages that chain into an open-source Agent Skill for coding agents such as Claude Code and Codex. Give it a topic, a talking-head video, or a single photograph, and the workflow can plan the story, generate collage keyframes, animate them, prepare audio assets, and assemble the result with FFmpeg.
Its most useful idea is not the imitation of a particular editorial style. It is the conversion of visual judgment into an executable workflow with explicit inputs, outputs, checkpoints, and replaceable model calls.
What Vox Director actually automates
Many AI video products solve one isolated step. One makes an image, another animates it, and a third creates a voiceover. The difficult part is still the handoff between those steps.
Vox Director organizes a project around a beat sheet, typically represented by a beats.json file. Each beat can hold narration, duration, image direction, model selection, style rules, and output paths. Scripts then work through that shared plan:
- Break a topic or transcript into narrative beats.
- Choose a story structure and pacing.
- Test multiple visual directions on a representative beat.
- Generate collage keyframes with a locked style.
- Turn each keyframe into a short motion clip.
- Produce narration, music, and subtitles where required.
- Normalize resolution, frame rate, duration, and audio with FFmpeg.
- Check identity consistency, subtitle readability, and audio-video sync.
That distinction matters. Models are individual workstations; the beat sheet and acceptance criteria are the factory floor.
beats.json is the control plane
It is easy to mistake the project for a chain of image and video prompts. Its more durable asset is the beat sheet. A maintainable beat should answer at least six questions: what is being said, how long it lasts, what the visual subject is, which elements are immutable, how the frame may move, and where every approved output lives.
This simplified schema is not a verbatim copy of the repository. It shows a useful structure for a team adaptation:
{
"project": "api-200-business-failure",
"format": { "ratio": "16:9", "fps": 24 },
"style_lock": "warm paper collage, black type, orange accent",
"beats": [
{
"id": "beat-01",
"narration": "An HTTP 200 response only confirms that the request was accepted.",
"duration_sec": 3.2,
"visual_goal": "contrast a successful response card with a failed workflow",
"immutable": ["200 response code", "orange status light"],
"motion": "slow push-in, status light blinks once",
"status": "keyframe_approved",
"outputs": {
"keyframe": "assets/keyframes/beat-01.png",
"clip": "assets/clips/beat-01.mp4"
}
}
]
}
{
"project": "api-200-business-failure",
"format": { "ratio": "16:9", "fps": 24 },
"style_lock": "warm paper collage, black type, orange accent",
"beats": [
{
"id": "beat-01",
"narration": "An HTTP 200 response only confirms that the request was accepted.",
"duration_sec": 3.2,
"visual_goal": "contrast a successful response card with a failed workflow",
"immutable": ["200 response code", "orange status light"],
"motion": "slow push-in, status light blinks once",
"status": "keyframe_approved",
"outputs": {
"keyframe": "assets/keyframes/beat-01.png",
"clip": "assets/clips/beat-01.mp4"
}
}
]
}
The file provides resumability, targeted regeneration, and an auditable approval trail. A practical state machine is draft -> style_approved -> keyframe_approved -> animated -> audio_synced -> passed. Do not allow a beat to advance until the previous gate is complete.
A-roll, B-roll, or C-roll: choose the right input route
| Route | Starting material | Best for | Main constraint |
|---|---|---|---|
| A-roll | Talking-head or interview video | Preserving a speaker while rebuilding the visual world | Face, lip movement, gaze, and original audio must remain intact |
| B-roll | A topic or written brief | Explainers, knowledge videos, and brand stories | Narrative structure and style must be fixed before batch generation |
| C-roll | A single photo | Short social clips and photo-led visual experiments | Subject identity and relationships must not drift |
A-roll: rebuild the scene, not the speaker
For A-roll, the input is a video with speech. A reference script can also be supplied as a vocabulary list and transcription aid.
The workflow transcribes the audio, uses word-level timestamps to divide the video into model-sized segments, and treats the speaker as protected content. The person can be framed as a photographic cutout with torn-paper edges while the surrounding environment becomes newspaper fragments, tape, halftone dots, maps, or other collage elements.
A reliable A-roll specification should say what must not change:
- preserve the face, mouth movement, gaze, pose, and gestures;
- redesign only the world around the person;
- keep collage elements away from the face and hands;
- time emphasized words from the transcript instead of asking a video model to guess;
- keep the original audio separately and restore it after visual generation.
B-roll: start with structure, then generate scenes
B-roll starts from a subject rather than existing footage. The agent researches or expands the brief, creates a narrative spine, and divides it into beats. It can then produce narration, keyframes, movement, subtitles, and a final render.
The common mistake is to generate every scene immediately. A better sequence is:
- finalize the script and beat lengths;
- choose one representative beat;
- generate two or three visual directions for that beat;
- approve one direction and record its rules;
- batch-generate the remaining beats;
- review the complete sequence before animation.
This small approval gate prevents a costly outcome: twenty individually attractive images that do not belong to the same video.
C-roll: move one photograph into a collage world
C-roll begins with a single photo. The workflow identifies the subject, important objects, their relationships, and the image’s visual anchor. It then creates a collage interpretation and animates selected layers.
It works well for portraits, products, travel photos, architecture, and social posts. The acceptance rule is simple but strict: style may change; identity and relationships may not. If a person, product silhouette, logo placement, or interaction is essential, write it into an immutable-elements list before generation.
Why the workflow separates keyframes from motion
One of the strongest design decisions in Vox Director is the separation of visual design and animation.
The image stage solves composition: hierarchy, cutout edges, typography, paper texture, color, and the relationship between foreground and background. The video stage receives an approved frame and solves motion: camera push, parallax, paper movement, object entrance, and timing.
Trying to solve both in one prompt gives the model too much freedom. Faces drift, layouts change, text mutates, and objects appear or disappear. A locked keyframe acts as a visual contract.
How to install Vox Director locally
The upstream project is designed as a skill folder rather than a conventional desktop application. A typical installation looks like this:
git clone https://github.com/Alisa0808/vox-director.git
# Claude Code
cp -R vox-director ~/.claude/skills/vox-director
# Codex
cp -R vox-director ~/.codex/skills/vox-director
git clone https://github.com/Alisa0808/vox-director.git
# Claude Code
cp -R vox-director ~/.claude/skills/vox-director
# Codex
cp -R vox-director ~/.codex/skills/vox-director
Before running a full project, verify the local toolchain:
python --version
ffmpeg -version
ffprobe -version
git --version
python --version
ffmpeg -version
ffprobe -version
git --version
You will also need enough disk space for source footage, keyframes, generated clips, audio, subtitles, and temporary renders. Keep those directories separate so failed experiments can be deleted without touching approved assets.
Use a predictable project directory
Automated media workflows become fragile when file names depend on the conversation that created them. Keep sources read-only, version generated outputs, and let beats.json point to the approved version:
project/
├─ brief.md
├─ beats.json
├─ config/
│ ├─ style-guide.md
│ └─ model-map.json
├─ sources/
├─ assets/
│ ├─ transcripts/
│ ├─ keyframes/
│ ├─ clips/
│ ├─ audio/
│ └─ subtitles/
├─ renders/
└─ logs/
project/
├─ brief.md
├─ beats.json
├─ config/
│ ├─ style-guide.md
│ └─ model-map.json
├─ sources/
├─ assets/
│ ├─ transcripts/
│ ├─ keyframes/
│ ├─ clips/
│ ├─ audio/
│ └─ subtitles/
├─ renders/
└─ logs/
Generate beat-03-keyframe-v02.png instead of overwriting v01. Once a reviewer approves it, update the beat sheet. This makes rollback possible and shows which model call improved or damaged the sequence.
Important: the upstream repository is not provider-neutral yet
This is the most important compatibility detail.
At the time of verification, the public main branch implements Atlas Cloud as its default and only concrete provider. Its scripts read ATLASCLOUD_API_KEY, call Atlas-specific endpoints, and expect Atlas-specific asynchronous job and response formats.
Therefore, replacing this:
ATLASCLOUD_API_KEY -> APITO_API_KEY
ATLASCLOUD_API_KEY -> APITO_API_KEY
is not a complete migration. A working Apito integration requires a provider adapter that handles:
- Base URL and authentication;
- model ID mapping;
- request-body conversion;
- synchronous versus asynchronous jobs;
- polling and timeout behavior;
- output URL and error-field normalization;
- model-specific parameters for image, video, and speech calls.
This is not a flaw in the creative workflow. It is a boundary between workflow logic and provider implementation, and it should be treated explicitly.
Where Apito fits in the architecture
Apito, also referred to as ClaudeAPI in this content system, belongs in the model-access layer. It can centralize API keys, available model selection, request records, and cost observation while leaving Vox Director’s creative logic intact.
Topic / footage / photo
↓
Vox Director workflow
beats.json · style rules · QA gates · FFmpeg assembly
↓
Apito provider adapter
Base URL · API key · model mapping · request/response conversion
↓
Models currently available in the Apito console
Topic / footage / photo
↓
Vox Director workflow
beats.json · style rules · QA gates · FFmpeg assembly
↓
Apito provider adapter
Base URL · API key · model mapping · request/response conversion
↓
Models currently available in the Apito console
Create a key in the Apito console and keep credentials outside the repository:
# macOS / Linux
export APITO_API_KEY="sk-your-key"
export APITO_BASE_URL="https://apito.ai"
# macOS / Linux
export APITO_API_KEY="sk-your-key"
export APITO_BASE_URL="https://apito.ai"
# Windows PowerShell
$env:APITO_API_KEY = "sk-your-key"
$env:APITO_BASE_URL = "https://apito.ai"
# Windows PowerShell
$env:APITO_API_KEY = "sk-your-key"
$env:APITO_BASE_URL = "https://apito.ai"
A minimal client boundary can look like this:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["APITO_API_KEY"],
base_url=os.environ.get("APITO_BASE_URL", "https://apito.ai"),
)
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["APITO_API_KEY"],
base_url=os.environ.get("APITO_BASE_URL", "https://apito.ai"),
)
This snippet demonstrates configuration separation only. Do not assume that every image, video, or speech endpoint follows the same schema. Check the current Apito console and model documentation, then implement and test each media adapter.
Job submission is not job success
Many video and some image APIs are asynchronous. The first response contains a task ID, not a usable asset. The adapter needs explicit behavior for every state:
| State | Correct action | Avoid |
|---|---|---|
queued |
Wait, poll later, and record queue time | Submitting the same generation again immediately |
running |
Poll with bounded backoff | Querying every second until rate-limited |
succeeded |
Download and validate size, format, and duration | Marking a beat as passed because a URL exists |
failed |
Preserve the error class and raw response | Retrying forever |
expired |
Submit a new task with a new idempotency key | Polling an invalid task ID |
rejected |
Review the material or task design manually | Rephrasing repeatedly to bypass a restriction |
Retry only when the error is recoverable, the attempt limit has not been reached, and the beat does not already have a valid output. Timeouts and temporary throttling may be retried. Authentication errors, invalid model IDs, unsupported parameters, and content rejection should stop the stage.
Keep a compact call record for every generated asset:
{
"beat_id": "beat-01",
"stage": "image_to_video",
"provider": "apito-adapter",
"model_id": "actual-console-model-id",
"request_id": "req_xxx",
"attempt": 1,
"latency_ms": 42800,
"status": "succeeded",
"estimated_cost": null,
"output": "assets/clips/beat-01-v01.mp4"
}
{
"beat_id": "beat-01",
"stage": "image_to_video",
"provider": "apito-adapter",
"model_id": "actual-console-model-id",
"request_id": "req_xxx",
"attempt": 1,
"latency_ms": 42800,
"status": "succeeded",
"estimated_cost": null,
"output": "assets/clips/beat-01-v01.mp4"
}
If the interface does not return dependable cost data, leave the field null rather than inventing precision. Model ID, request count, latency, failures, and output path are still enough to identify the most expensive and unreliable production stage.
Model routing: use expensive capability only where it matters
The workflow does not need the same model at every stage.
| Production stage | What the model must do | Practical routing principle |
|---|---|---|
| Script planning | Structure, causal logic, pacing | Use a strong reasoning model; prompts are short relative to media generation |
| Transcription | Stable timestamps and terminology | Prefer a speech model with word-level timing |
| Keyframe generation | Composition and identity consistency | Test a small set before batch generation |
| Image-to-video | Controlled motion and low drift | Animate only approved frames and keep clips short |
| Music or narration | Tone, pronunciation, usable duration | Generate after the script is locked |
| Assembly | Deterministic rendering | Use local FFmpeg, not another generative model |
Apito makes the access layer easier to manage, but a model switch still requires a regression test. Parameter names, safety behavior, supported dimensions, and response formats may differ.
Run a ten-second acceptance test first
Do not begin with a two-minute production. Build one eight-to-ten-second beat and require it to pass these checks:
- the subject remains recognizable;
- the visual hierarchy is readable on a phone;
- the approved color and paper system is present;
- motion supports the narration instead of competing with it;
- subtitles remain within safe margins;
- audio duration and clip duration match;
- the provider adapter records model, latency, cost, and errors;
- the final file plays correctly outside the editing environment.
Once the representative beat passes, freeze the style rules and expand the batch.
Scale in four controlled batches
| Stage | Deliverable | Human checkpoint | What it unlocks |
|---|---|---|---|
| Structure | Complete beat sheet | Logic, duration, and information density | Visual exploration |
| Visual direction | Three keyframes for one representative beat | Subject, color, paper system, layout | Global style lock |
| Small batch | Keyframes and motion for the first three beats | Continuity, drift, subtitle safe area | Remaining beat generation |
| Full preview | Low-bitrate complete render | Pacing, sync, rights, and brand details | Final high-quality export |
A low-bitrate preview is faster to review and replace. Export the final resolution, bitrate, and container only after content and timing are locked.
Before publication, verify facts and names, subject identity, product geometry, text rendering, voice-to-music balance, subtitle timing, mobile safe areas, codec compatibility, source rights, and the link between the final file and its beat-level call records.
A reusable project brief
The following brief is more useful than a one-line request such as “make this look like a collage”:
Goal: produce a 10-second B-roll proof of concept.
Input: a 60-word English script about urban public transport.
Format: 16:9, 1920×1080, 24 fps.
Visual system: editorial paper collage, warm gray base, one orange accent,
no photorealistic text generated inside the image.
Motion: slow camera push, two-layer parallax, one paper element entering per beat.
Immutable elements: approved subject silhouette and color palette.
Subtitles: rendered locally with FFmpeg inside safe margins.
Provider: use the tested Apito adapter configured in this project.
Deliverables: beats.json, approved keyframe, motion clip, subtitles, final MP4,
and a short call log containing model ID, latency, and errors.
Stop condition: do not batch-generate until the keyframe is approved.
Goal: produce a 10-second B-roll proof of concept.
Input: a 60-word English script about urban public transport.
Format: 16:9, 1920×1080, 24 fps.
Visual system: editorial paper collage, warm gray base, one orange accent,
no photorealistic text generated inside the image.
Motion: slow camera push, two-layer parallax, one paper element entering per beat.
Immutable elements: approved subject silhouette and color palette.
Subtitles: rendered locally with FFmpeg inside safe margins.
Provider: use the tested Apito adapter configured in this project.
Deliverables: beats.json, approved keyframe, motion clip, subtitles, final MP4,
and a short call log containing model ID, latency, and errors.
Stop condition: do not batch-generate until the keyframe is approved.
Five problems that usually break the result
1. Generating all scenes before approving a style
This multiplies inconsistency. Approve one representative beat first.
2. Letting the video model redesign the frame
Use the approved keyframe as a contract and describe motion only.
3. Putting credentials in prompts or repositories
Use environment variables or a secrets manager. Rotate a key immediately if it appears in a screenshot, log, or commit.
4. Assuming a provider migration is only a Base URL change
Media APIs often use provider-specific job creation, polling, and result formats. Build an adapter and test failure paths.
5. Skipping the final render check
Inspect the actual MP4 for duration, resolution, audio peaks, blank frames, subtitle clipping, and playback compatibility.
Frequently asked questions
Can I run Vox Director by changing only the API key?
Not with the verified public main branch. It currently implements an Atlas Cloud provider. Apito requires a tested adapter for authentication, model IDs, job polling, and response conversion.
Does it work only with Claude Code?
No. It is structured as an Agent Skill and can be used by coding agents that can read the instructions, run scripts, and manage project files, including Codex. Exact installation paths vary by client.
Which model should I choose in Apito?
Choose by production stage, not by a single global ranking. Use the models and interfaces currently visible in your Apito console, and validate a representative sample before scaling.
Can it generate a complete video without FFmpeg?
Individual media models can create clips, but deterministic assembly is still valuable. FFmpeg gives you reliable control over timing, codecs, subtitles, frame rate, audio mixing, and final verification.
Is it safe to use for commercial work?
The repository uses the MIT License, but that does not automatically clear every model output, font, source image, music track, voice, trademark, or depicted person. Review the licenses and rights for every asset and service in your production.
References
Get started
Start with one approved beat, not a full batch. If you need a centralized model-access layer for the workflow, create an API key at Apito, verify the models and interfaces currently available to your account, and connect them through a tested provider adapter.
This article reflects the public repository as verified on August 26, 2026. The project, available models, and API interfaces may change; recheck the repository and Apito console before implementation.
