📘 Hướng Dẫn Sử Dụng Nhanh – AI Video Generation Studio

Tài liệu này giúp bạn đi qua toàn bộ các bước sử dụng phần mềm từ A → Z: đăng ký tài khoản, thêm API key, tạo profile (kèm đăng nhập Veo3), tạo project, chọn profile, xây dựng kịch bản thủ công, import kịch bản bằng JSON/script và generate video.

1. Đăng ký & đăng nhập tài khoản

• Mở ứng dụng lần đầu ➜ màn hình đăng nhập xuất hiện.
• Đăng ký tài khoản mới
  1. Chọn tab Register.
  2. Nhập Email, Password và Display name (bắt buộc).
  3. (Tùy chọn) nhập số điện thoại để tiện hỗ trợ.
  4. Bấm Create Account.
  5. Nếu thành công, phần mềm tự đăng nhập và hiển thị màn hình Dashboard.
• Đăng nhập tài khoản đã có
  1. Chọn tab Login.
  2. Nhập Email & Password → bấm Sign In.
  3. Tick Remember me nếu muốn lưu thông tin.
• Đăng nhập Google (nếu được mở) ➜ bấm Login with Google, chọn tài khoản, chấp nhận yêu cầu.
• Mẹo & Khắc phục
  • Lỗi EMAIL_EXISTS: email đã đăng ký.
  • Lỗi WEAK_PASSWORD: mật khẩu phải ≥ 6 ký tự.
  • Nếu đăng ký thành công nhưng không chuyển trang, thử mở lại app (app đã tạo tài khoản kèm 1-day trial license trong Firestore).

2. Thêm & quản lý API Key

Mục tiêu: lưu nhiều Gemini API key trong database, kích hoạt key đang dùng và tự động chuyển key khi hết quota.

1. Trên thanh công cụ, bấm biểu tượng Settings ⚙️ ➜ mở popup API Key Management.
2. Giao diện gồm: danh sách key (tên, key, status, lần cuối dùng, số lần dùng) và các nút thao tác.
3. Thêm API key mới
   • Bấm + Add API Key
   • Nhập Key (bắt buộc) và Tên mô tả (tùy chọn)
   • Bấm Save. Key được lưu vào bảng api_keys (Prisma).
4. Sửa tên/Key ➜ bấm biểu tượng bút ✏️ trên dòng tương ứng, chỉnh ➜ Update.
5. Xóa Key ➜ chọn biểu tượng thùng rác 🗑️ ➜ xác nhận.
6. Kích hoạt Key ➜ bấm Set Active.
7. Mẹo & Khắc phục
   • Nếu popup báo “table api_keys missing” ➜ chạy npm run db:migrate rồi restart app.
   • Phần mềm tự chuyển sang key khác khi lỗi 429/403/401.

3. Tạo profile browser cho tài khoản Veo3

Profile lưu cookies + lịch sử để tự đăng nhập Veo3 trong những lần chạy tự động.

3.1 Tạo profile mới & đăng nhập Veo3

1. Mở tab Profiles.
2. Bấm Create Profile ➜ nhập Profile name (vd. “Veo3 – Team Marketing”).
3. Bấm Continue.
4. Trình duyệt Chromium mở kèm trạng thái trắng (headless=false).
5. Đăng nhập Veo3 tại https://labs.google/fx/tools/flow.
6. Sau khi thấy trang Flow/Whisk hiển thị, quay lại app và bấm Save Profile After Login.
7. App đóng trình duyệt và lưu cookies vào thư mục profile (~/Documents/EgTools-VideoGenerator/profiles/<profileId>).

3.2 Cập nhật/refresh profile

• Khi Veo3 hết phiên, mở tab Profiles ➜ chọn profile ➜ bấm Refresh Login.
• Trình duyệt mở với cookies cũ, đăng nhập lại (nếu cần) ➜ quay lại app ➜ Save Profile After Login.

3.3 Xóa profile

• Chọn profile ➜ Delete ➜ xác nhận. (Xóa cả cookies & thư mục.)

4. Tạo project & chọn profile

4.1 Tạo project mới

1. Mở tab Projects (Dashboard).
2. Chọn profile ở dropdown Select Profile (các profile đã lưu).
3. Bấm Create New Project.
4. Nhập Project Name, Description (tùy chọn), chọn 1 hay nhiều profile sẽ chạy (tương ứng multi-account).
5. Bấm Create. App tạo bản ghi trong DB và chuẩn bị automation.

4.2 Chọn profile cho project

• Trong form tạo project, tick vào profile muốn gán cho project.
• Có thể chọn nhiều profile (app sẽ lần lượt mở browser theo từng profile để tạo Flow/Whisk project).

4.3 Xem danh sách project

• Dashboard hiển thị project với trạng thái, số scene, ngày tạo.
• Click 1 project ➜ vào Project Detail Page.

5. Tạo kịch bản bằng tay (Manual Script Builder)

5.1 Truy cập giao diện

1. Trong Project Detail Page, chuyển sang tab Script (hoặc Scenes).
2. Chọn sub-tab Manual Create.

5.2 Thêm nhân vật (Characters)

Tính năng đang phát triển

5.3 Thêm cảnh (Scenes)

Tính năng đang phát triển

5.4 Sinh kịch bản nhanh bằng AI (popup Tạo Prompt Mới)

1. Ở tab Manual Create, bấm nút ✏️ Tạo Prompt Mới để mở popup.
2. Trong nhóm Thông tin cơ bản, hãy:
   • Nhập Ý tưởng câu chuyện (≥ 10 ký tự).
   • Chọn Số Prompt:
     • 🤖 Auto: để AI tự quyết số cảnh.
     • Hoặc nhập số cụ thể (1–10) nếu muốn cố định.
   • Chọn Thể loại và Phong cách hình ảnh (bắt buộc).
   • Chọn Độ tuổi khán giả, tick nhiều Pace và Mood nếu cần.
   • Bật/tắt Thoại (Dialogues) theo nhu cầu.
3. (Tùy chọn) mở Cài đặt nâng cao:
   • Tỉ lệ khung hình (9:16, 16:9, 1:1...).
   • Preset ánh sáng và Bảng màu để khóa phong cách.
   • Gợi ý kỹ thuật: Continuity priority, Style lock, ghi chú riêng.
   • Chọn Ngôn ngữ lời thoại (Việt hoặc Anh). Mô tả/prompt vẫn luôn tiếng Anh.
4. Bấm Generate:
   • Prompt chi tiết được copy sẵn vào clipboard (dán vào ChatGPT nếu muốn tinh chỉnh).
   • Ứng dụng gọi Gemini để sinh đầy đủ JSON (scenes, prompts, nhân vật) và tự động điền vào tab Manual.
5. Sau khi AI trả về kịch bản, kiểm tra từng cảnh, chỉnh tay nếu cần trước khi lưu.

5.5 Tạo prompt thủ công

1. Trong mỗi scene, phần Prompts chứa các prompt mẫu.
2. Bấm Edit Prompt để chỉnh, hoặc Create Prompt để viết prompt mới.
3. Nhập nội dung prompt (nhớ mô tả chi tiết: bối cảnh, nhân vật, camera, ánh sáng).
4. Lưu prompt. App cập nhật meta trong DB.

6. Nhập kịch bản bằng script (Import JSON)

1. Trong Project Detail Page, tab Script → chọn Import JSON.
2. Bấm Import Script ➜ chọn file JSON v3.0.0 (tham khảo mẫu ở ScriptImportModal hoặc USER_GUIDE).
3. App validate format, hiển thị lỗi nếu thiếu field.
4. Nếu hợp lệ ➜ xác nhận import ➜ Scenes, Characters, Continuity sẽ được tạo tự động.
5. Xem lại scenes trong tab Manual để chỉnh tay nếu cần.

Mẹo: JSON phải chứa metadata, characters, scenes với các trường prompt, visual, audio. App hỗ trợ auto-fill field thiếu như sceneId, cameraAngles.

7. Generate video với script

7.1 Chuẩn bị trước khi run

• Đảm bảo profile đang login Veo3 (phần 3).
• Chọn project, check scenes/prompt đúng.
• Nếu cần reference image ➜ upload thủ công khi automation mở Flow.
• Kiểm tra API Key hoạt động (Gemini).

7.2 Submit prompt & tạo video

1. Trong Project Detail Page, phần Scene Queue, bạn có thể:
   • Submit Selected (chọn vài scene)
   • Submit All (toàn bộ scene)
2. App tạo batch job: status = QUEUED trong DB.
3. Automation sẽ:
   • Mở browser bằng profile liên quan.
   • Navigate đến Flow project (flowProjectId).
   • Configure output (nếu lần đầu).
   • Điền prompt phối hợp JSON → textarea → nhấn Enter.
   • Theo dõi DOM để bắt card video mới.

7.3 Theo dõi tiến độ

• Mỗi scene hiển thị trạng thái: QUEUED, PROCESSING, COMPLETED, FAILED.
• Thông tin video (URL, poster) được cập nhật tự động khi card Flow xuất hiện.
• UI hiển thị progress bar tổng và từng scene.

7.4 Sau khi hoàn thành

• Có thể Download video trực tiếp về thư mục mặc định (~/Downloads hoặc chọn khác).
• Nếu FAILED, xem log ➜ có thể do prompt cấm hoặc Flow lỗi; bạn có thể Re-Try.
• Browser tự đóng khi không còn job.

Chúc bạn thao tác hiệu quả! Nếu gặp lỗi khó xử lý, thu thập log (Console, Terminal) và liên hệ đội phát triển kèm mô tả bước thực hiện. Chúng tôi sẽ hỗ trợ sớm nhất có thể. 💡🎬✨