AI Music Video Generator

Create complete music videos: AI music + AI visuals + ffmpeg assembly.

Quick Start

CODEBLOCK0

Workflow

1. Plan scenes from lyrics/mood

CODEBLOCK1

2. Generate music

Options:

• - --model V4_5ALL (default), V5, V4_5PLUS, V4_5, INLINECODE5
• INLINECODE6 — no vocals
• INLINECODE7 — vocal gender hint
• INLINECODE8 — styles to avoid
• INLINECODE9 — generate Suno native music video (MP4)
• INLINECODE10 — cost check only

Persona (일관된 스타일 유지):

• - --persona-id ID — 기존 페르소나 사용 (같은 보컬/스타일로 여러 곡 생성)
• INLINECODE12 — 생성된 곡에서 페르소나 생성 → persona.json 저장
• INLINECODE14 / --persona-desc "설명" / INLINECODE16

Auto features:

• - 🎤 Timestamped Lyrics: Non-instrumental tracks automatically fetch lyrics timestamps and save as INLINECODE17
• 🎬 Suno Native MV: With --music-video, Suno generates a visualized MP4 video directly
• 🎭 Persona: With --create-persona, extracts voice/style identity for reuse

3. Generate visuals (custom MV flow)

Or with OpenAI (cheaper, lower res):

bash scripts/gen_visuals.sh \
  --mode slideshow \
  --prompts-file /tmp/mv_project/prompts.json \
  --image-provider openai --image-model gpt-image-1-mini --image-quality medium \
  --outdir /tmp/mv_project

4. Assemble

Subtitle behavior:

• - Auto-detects {outdir}/lyrics.srt and overlays lyrics automatically
• INLINECODE22 — use custom SRT file
• INLINECODE23 — disable lyrics overlay entirely

Modes

Image cost is token-based — actual billing may be lower than listed estimates. Use --dry-run for precise cost.

Provider Options

Images: --image-provider seedream (recommended), openai, or google-together
Image Model (OpenAI): --image-model gpt-image-1-mini (default, cheap) or gpt-image-1 (premium)
Videos: --video-provider sora (default), sora-pro, seedance-lite, seedance-pro, veo-fast, veo-audio
Quality: INLINECODE40

Cost Tracking

Every script outputs cost before and after. Always --dry-run first.
Cost data saved to {outdir}/cost_estimate.json and {outdir}/visuals_meta.json.

Environment Variables

CODEBLOCK6

⚠️ Required keys: SUNO_API_KEY and OPENAI_API_KEY must be set before running any script.
BYTEPLUS_API_KEY is needed for Seedream image provider (sign up at console.byteplus.com, 200 free images).
TOGETHER_API_KEY is only needed for Seedance/Veo/Imagen providers.

Callback URL

The Suno API requires a callBackUrl field for music generation requests.
By default, if SUNO_CALLBACK_URL is not set, the script uses https://localhost/noop
as a harmless no-op endpoint (an unreachable localhost URL that effectively disables callbacks).

To customize: set SUNO_CALLBACK_URL to your own endpoint, or set it to
any dummy URL you control. The callback payload contains task metadata and
audio URLs — no API keys are sent.

To disable: set SUNO_CALLBACK_URL=https://localhost/noop or any unreachable URL.
Generation still works via polling; the callback is not required for the script to function.

Persona Workflow (채널 컨셉 유지)

YouTube 채널처럼 일관된 스타일로 여러 곡을 만들 때:

CODEBLOCK7

페르소나는 보컬 특성 + 음악 스타일을 기억해서, 채널 전체의 통일감을 유지해줌.

Prerequisites

• - curl, python3, ffmpeg (for assembly)

References

• - SunoAPI details: Read INLINECODE56
• Visual provider details: Read INLINECODE57