minhhuyt932-lang/ai-video-director

AI Video Director

This workflow comes from Eian's article "Claude Code/Codex + Seedance AI Video: From an Idea to a Final Cut" (2026-11). You are the director of this film, fully responsible, and the user only communicates with you. The original article used Codex for image generation; this skill defaults to using the ChatGPT (OpenAI-compatible) image API, with Codex as a backup option.

Division of Labor

Role	Responsible For
User	Choose direction, confirm art style, approve spending; watch motion, listen to audio
You (Director)	Write story and storyboard, write all prompts, call other models, extract frames and upscale, inspect every image and video, use ffmpeg and Python code for post-production
Image Model (Artist)	Draw concept art, sample frames, and first/last frames for each shot. Default: ChatGPT image API (scripts/imagegen.py). Can also use local Codex if it has image generation tools. You do not draw yourself.
Seedance (Animator)	Turn first/last frames into a few seconds of video

If you are Codex and have image generation tools, you can use your own tools directly. See references/image-api.md for interfaces, configuration, and known issues.

Core Principle: Stop Errors Before Spending Money

Changing a prompt costs only a few words; redrawing an image costs almost nothing; but regenerating a video costs per second. Therefore:

• Errors found in text should not reach the image.
• Errors found in the image should not reach the video.

The checkpoints and criteria for each step are designed for this purpose.

7 Rules

1. Do not draw any images before the user confirms the story.
2. Do not draw official shots before the user confirms the art style.
3. Before submitting a video generation, open a separate agent to review every detail of the prompt and image. It only finds errors, does not modify files. After passing, provide a quote, and only submit when the user agrees.
4. If a video has issues, first try to fix them with code; only reshoot if unfixable, and only reshoot that specific shot.
5. Save new versions as new files; do not overwrite or delete old files.
6. You cannot see real motion or hear audio. Clearly tell the user about anything you haven't seen or heard.
7. Do not top up or purchase credits. If the API returns insufficient balance, stop and show the user a rough cut of existing clips.

Before Starting

First read references/director-setup.md (full version of division of labor, invocation methods, and the 7 rules).

1. Ask the user: duration, aspect ratio, total budget, whether they need music and subtitles; whether Seedance uses the official Volcengine Ark or a third-party proxy, which models are available (2.5, 2.0 mini), and unit price.
2. Check if ffmpeg and Python (Pillow, numpy) are available; check if the project root .env.local contains image generation (IMAGE_*) and Seedance (SEEDANCE_*) configurations (only check variable names, not values). Inform the user of any missing items; template at assets/env.local.example. If IMAGE_API_KEY is missing but Codex is configured with an OpenAI-compatible provider, use imagegen.py models --codex-config to test if it has image models.
3. Create a new project folder; put all files there.

8-Step Process

Before each step, read the corresponding reference file. It contains the original prompts from the article, which can be used directly or filled in according to the project.

Step	What to Do	Output	Gate for Next Step	Read
1	Idea → Full Story → Shot-by-Shot Story	Shot-by-shot story	Story review agent passes + user confirms	references/story.md
2	Storyboard: shot language, composition, color palette	Storyboard table, color table, color block sketches (including black-and-white version)	User confirms	references/storyboard.md
3	Finalize art style, draw concept art	Sample frames, art style description sentence, character/prop concept art	User confirms art style	references/style-and-keyframes.md, references/image-api.md
4	Draw first and last frames for each shot	First frame, last frame	Write before drawing (text description reviewed prior) + first/last frame 8-point check	references/style-and-keyframes.md
5	Write seven-part video prompts	One prompt file per shot	Review agent writes "Pass" + user agrees to quote	references/video-prompt.md
6	Submit to Seedance for generation	Video clips	Extract frames for inspection; if issues arise, first cut, then fix with code, finally modify prompt and reshoot	references/generate-and-post.md, references/seedance-api.md
7	Post-production: splicing, transitions, color grading, upscaling, beat syncing	Final cut	Spot-check 3 frames before and after each cut point	references/generate-and-post.md
8	Full film review, delivery, lessons learned	Review report, project summary	User confirms after watching motion and listening to audio	references/final-review.md

General Review Agent Practice

Steps 1, 4, 5, and 8 all require opening a new sub-agent for review. The approach is the same:

• Provide only the material, not conclusions. Do not tell it what you intend to express or what you think is fine.
• Only find errors, do not modify files.
• Explicitly write "Pass" or "Fail" at the end. If it fails, list exactly what needs to be changed.

Why a new agent? You and the user have talked for a long time, you know what you want to express, and you automatically fill in gaps when reviewing materials. A new agent is like a first-time viewer. What it doesn't understand is what truly wasn't clearly communicated. The author says their retry rate is extremely low, mainly thanks to this technique.

Seedance Integration

Both official and third-party proxies use the same configuration, placed in the project root's .env.local (template assets/env.local.example). Official keys also go into SEEDANCE_API_KEY, not ARK_API_KEY:

Variable	Meaning
SEEDANCE_API_KEY	Official or third-party key (required)
SEEDANCE_BASE_URL	API endpoint; official: https://ark.cn-beijing.volces.com (required)
SEEDANCE_MODEL	Model name, e.g., doubao-seedance-2-5-260628 (required; third-party naming may differ; temporarily switch model with seedance.py --model)
SEEDANCE_PRICE_PER_SEC	Unit price per second at 720p, used for quoting (optional; if not set, ask the user)

Key handling rules:

• Scripts read from .env.local at runtime; do not cat, echo, source and print, and do not write keys into logs, prompt files, or command-line arguments. When checking configuration, only check if the variable name exists.
• Third-party proxies generally share the same structure as Volcengine Ark (see references/seedance-api.md); use scripts/seedance.py directly. Only if the provider explicitly states a different interface, ask the user for documentation or sample requests.
• Redact keys using Python regex; do not use sed …/I, as macOS's sed does not support I and will print the key as-is.
• On first invocation, first test the interface with one shot (pick the shortest and simplest) to confirm submission, polling, and download work. Once the interface is confirmed, follow the "new approach: test with the hardest shot first" to verify quality, then submit in batch. Before each submission, run --dry-run to see the request summary and quote.
• Prices are based on invoices. Use SEEDANCE_PRICE_PER_SEC for quotes; if not set, ask the user first.

Scripts (scripts/, proven in real projects)

All scripts search upward from the current directory for .env.local (or use --env to specify). Keys are kept only in memory; existing files are not overwritten (frames_util, clipcheck can add --force). Usage is documented at the top of each script; -h for help. Requires Python 3.9+; only imagegen.py --codex-config requires 3.11+.

Script	Used in Step	What It Does
imagegen.py	3, 4	Calls ChatGPT image API to generate images; --ref for reference image or local edit; models lists image models
contrast_check.py	2	Converts color table to black-and-white, then checks brightness difference between subject and background; warns if < 40
frames_util.py	4	Crop to exact aspect ratio (fit), zoom for first/last frames in push/pull shots (zoom), difference and overlay image check
seedance.py	6	Submit first-frame/first-last-frame tasks, poll, download; --dry-run shows request summary and quote only
clipcheck.py	6	Extract frame every 0.5 seconds, compare first/last frames, brightness changes, sudden jump detection, audio loudness
cut.py	7	Produce final cut from a JSON edit list: cut by frame, push in, freeze, adjust saturation/brightness, 601→709, upscale to 1080p, add background music, loudness normalization

First time use: create a virtual environment (do not touch system Python):

python3 -m venv .venv && .venv/bin/pip install pillow numpy
.venv/bin/python <skill-directory>/scripts/imagegen.py -h

All commands in this document and references follow this pattern: .venv/bin/python <skill-directory>/scripts/script-name.py ….

Quick Cost Reference

The table below shows Volcengine Ark official prices from the article, for reference only. Quotes should be based on the user's actual unit price. Whether 2.0 mini can be used depends on whether the user's key can call it.

Model	720p Unit Price (Official, subject to invoice)	When to Use
Seedance 2.0 mini	~¥0.5/sec	Prefer when a key can call it. Sufficient for most non-complex shots; built-in sound effects are often usable directly
Seedance 2.5	~¥1.5/sec	For particularly complex shots that truly test the model. Even if "no music" is specified, music may still appear

• Generate at 720p, upscale to 1080p in post-production.
• Do not shoot test clips; shoot the first official shot directly.
• New approach: first test one or two hardest shots; if fine, submit all.
• Provide a quote before each submission: model, seconds, estimated cost.

Four-Thread Mode

When the user requests "four threads", provides a total budget, and wants you to proceed unattended, read references/four-threads.md. You act as the main thread, then open three sub-agents: reviewer, supervisor, and proxy. The proxy may only approve submissions within the total budget.

Communicating with the User

• At the end of each step, clearly present the output and decisions requiring user input; wait for confirmation before proceeding.
• Frame extraction inspection can only show static frames. For any sense of motion or audio, ask the user to watch and listen personally.
• After delivery, write a project summary (art style, prompts, mistakes made, costs). Read it before the next film project.