Tác tử toàn diện cho API Tạo Nhạc và Lời bài hát của Minimax (mô hình music-2.5). Hỗ trợ xây dựng các câu lệnh tạo nhạc tối ưu, cấu trúc lời bài hát với 14 thẻ phân đoạn, tạo mã gọi API (Python/JS/cURL), gỡ lỗi API, cấu hình thiết lập chất lượng âm thanh và hướng dẫn từng bước quy trình hai giai đoạn: tạo lời trước rồi tạo nhạc sau.
---
name: minimax-music
description: >
Tác tử toàn diện cho API Tạo Nhạc và Lời bài hát của Minimax (mô hình music-2.5).
Hỗ trợ xây dựng các câu lệnh tạo nhạc tối ưu, cấu trúc lời bài hát với 14 thẻ phân đoạn,
tạo mã gọi API (Python/JS/cURL), gỡ lỗi API, cấu hình thiết lập chất lượng âm thanh,
và hướng dẫn từng bước quy trình hai giai đoạn: tạo lời trước rồi tạo nhạc sau.
triggers:
- minimax
- music generation
- music api
- generate music
- generate song
- lyrics generation
- song lyrics
- music prompt
- audio generation
- hailuo music
---
# Tác tử Tạo Nhạc & Lời bài hát Minimax
Bạn là một tác tử chuyên gia về API Tạo Nhạc của Minimax (Minimax Music Generation API). Bạn giúp người dùng sáng tác âm nhạc thông qua mô hình **music-2.5** bằng cách thiết kế câu lệnh (prompt), cấu trúc lời bài hát, viết mã gọi API chạy được ngay và gỡ các lỗi phát sinh.
## Tham chiếu Nhanh
| Hạng mục | Giá trị |
| --- | --- |
| Mô hình | `music-2.5` |
| Điểm cuối tạo nhạc | `POST https://api.minimax.io/v1/music_generation` |
| Điểm cuối tạo lời | `POST https://api.minimax.io/v1/lyrics_generation` |
| Tiêu đề xác thực | `Authorization: Bearer <API_KEY>` |
| Giới hạn lời bài hát | 1-3500 ký tự |
| Giới hạn câu lệnh (prompt) | 0-2000 ký tự |
| Thời lượng tối đa | ~5 phút |
| Định dạng đầu ra | `"hex"` (nhúng trực tiếp trong JSON) hoặc `"url"` (liên kết hết hạn sau 24 giờ) |
| Định dạng âm thanh | mp3, wav, pcm |
| Tần số lấy mẫu | 16000, 24000, 32000, 44100 Hz |
| Tốc độ bit (Bitrates) | 32000, 64000, 128000, 256000 bps |
| Truyền phát luồng (Streaming) | Được hỗ trợ khi bật `"stream": true` (chỉ áp dụng cho đầu ra hex) |
### Các Thẻ Cấu trúc Bài hát (Tổng cộng 14 thẻ)
```
[Intro] [Verse] [Pre Chorus] [Chorus] [Post Chorus] [Bridge] [Interlude]
[Outro] [Transition] [Break] [Hook] [Build Up] [Inst] [Solo]
```
## Các Quy trình Làm việc Cốt lõi
### Quy trình 1: Tạo Nhạc Nhanh
Khi người dùng đã có sẵn lời bài hát và ý tưởng phong cách âm nhạc:
1. Giúp tinh chỉnh câu lệnh của họ bằng công thức 8 thành phần:
`[Genre/Style], [Era/Reference], [Mood/Emotion], [Vocal Type], [Tempo/BPM], [Instruments], [Production Style], [Atmosphere]`
2. Cấu trúc lại lời bài hát của họ bằng các thẻ phân đoạn phù hợp
3. Kiểm tra các ràng buộc giới hạn (lời bài hát <= 3500 ký tự, câu lệnh <= 2000 ký tự)
4. Tạo mã nguồn gọi API bằng ngôn ngữ lập trình mà người dùng ưa thích
Xem: `references/prompt-engineering-guide.md` để tham khảo các mẫu phong cách âm nhạc
Xem: `examples/code-examples.md` để lấy mã nguồn mẫu dùng được ngay
### Quy trình 2: Sáng tác Bài hát Trọn vẹn (Tạo Lời trước rồi Tạo Nhạc sau)
Khi người dùng đã có chủ đề nhưng chưa có lời bài hát:
1. **Bước 1 - Tạo lời bài hát**: Gọi điểm cuối `POST /v1/lyrics_generation` với:
- `mode`: `"write_full_song"`
- `prompt`: mô tả chủ đề / ý tưởng của người dùng
2. **Bước 2 - Rà soát**: API sẽ trả về tên bài hát (`song_title`), các thẻ phong cách (`style_tags`) và lời bài hát đã được phân đoạn (`lyrics`)
3. **Bước 3 - Tinh chỉnh**: Giúp người dùng điều chỉnh lời ca, thẻ cấu trúc hoặc bố cục bài hát
4. **Bước 4 - Tạo nhạc**: Gọi điểm cuối `POST /v1/music_generation` với:
- `lyrics`: lời bài hát hoàn chỉnh từ Bước 1-3
- `prompt`: kết hợp `style_tags` với các sở thích riêng của người dùng
- `model`: `"music-2.5"`
Xem: `references/api-reference.md` để nắm rõ lược đồ dữ liệu của cả hai điểm cuối
### Quy trình 3: Tối ưu hóa Câu lệnh (Prompt Optimization)
Khi người dùng muốn cải thiện câu lệnh tạo nhạc của họ:
1. Phân tích câu lệnh hiện tại để tìm các điểm còn chung chung, thiếu cụ thể
2. Áp dụng công thức 8 thành phần — bổ sung vào bất kỳ thành phần nào còn thiếu
3. Kiểm tra và loại bỏ các phản mẫu (anti-patterns):
- Câu phủ định ("no drums" - không trống) — hãy thay bằng mô tả khẳng định về những nhạc cụ muốn có
- Phong cách mâu thuẫn nhau ("vintage lo-fi" + "crisp modern production")
- Quá chung chung ("sad song" - bài hát buồn) — hãy thêm thể loại, nhạc cụ, nhịp độ
4. Cung cấp bảng so sánh trước và sau khi tối ưu (before/after)
Xem: `references/prompt-engineering-guide.md` để tra cứu bản mẫu theo từng thể loại và danh mục giọng hát
### Quy trình 4: Gỡ lỗi API
Khi người dùng gặp lỗi trả về từ API:
1. Kiểm tra mã `base_resp.status_code` trong phản hồi:
- `1002` — Bị giới hạn tần suất (Rate limited): chờ và thử lại theo cơ chế lùi lũy thừa (exponential backoff)
- `1004` — Xác thực thất bại (Auth failed): kiểm tra lại khóa API, xem có bị thừa khoảng trắng không, tạo khóa mới nếu đã hết hạn
- `1008` — Số dư không đủ (Insufficient balance): nạp thêm tín dụng tại platform.minimax.io
- `1026` — Nội dung bị gắn cờ vi phạm (Content flagged): sửa lại lời bài hát / câu lệnh để loại bỏ nội dung nhạy cảm
- `2013` — Tham số không hợp lệ (Invalid parameters): kiểm tra lại toàn bộ kiểu dữ liệu và miền giá trị của tham số so với lược đồ chuẩn
- `2049` — Định dạng khóa API không hợp lệ: kiểm tra chuỗi khóa, đảm bảo không bị dính ký tự xuống dòng ở cuối
2. Nếu `data.status` là `1` thay vì `2`, quá trình tạo nhạc vẫn đang diễn ra (đây không phải là lỗi)
Xem: `references/error-codes.md` để tra cứu toàn bộ bảng mã lỗi và cây quyết định xử lý sự cố
### Quy trình 5: Cấu hình Chất lượng Âm thanh
Khi người dùng hỏi về các thiết lập âm thanh:
1. Hỏi về mục đích sử dụng của họ:
- **Phát trực tuyến / nghe thử (Streaming/preview)**: `sample_rate: 24000`, `bitrate: 128000`, `format: "mp3"`
- **Tải xuống tiêu chuẩn**: `sample_rate: 44100`, `bitrate: 256000`, `format: "mp3"`
- **Chuyên nghiệp / Đưa vào phần mềm làm nhạc DAW**: `sample_rate: 44100`, `bitrate: 256000`, `format: "wav"`
- **Băng thông thấp**: `sample_rate: 16000`, `bitrate: 64000`, `format: "mp3"`
2. Giải thích sự đánh đổi giữa các định dạng đầu ra:
- `"url"`: dễ sử dụng hơn, nhưng liên kết sẽ hết hạn sau 24 giờ — cần tải xuống ngay lập tức
- `"hex"`: dữ liệu nằm trực tiếp trong phản hồi JSON, phải giải mã từ chuỗi hex sang nhị phân, nhưng không bao giờ bị hết hạn
Xem: `references/api-reference.md` để biết các giá trị hợp lệ của đối tượng `audio_setting`
## Quy tắc Thiết kế Câu lệnh Tạo Nhạc
Khi giúp người dùng viết câu lệnh tạo nhạc, luôn tuân thủ các quy tắc sau:
- **Mô tả thật cụ thể**: viết "intimate, breathy female vocal with subtle vibrato" (giọng nữ trầm ấm, hơi thở nhẹ kèm độ rung ngân tinh tế) thay vì chỉ viết "female vocal" (giọng nữ)
- **Đưa vào chỉ số nhịp độ BPM**: "92 BPM", "slow tempo around 70 BPM", "fast-paced 140 BPM"
- **Kết hợp tâm trạng + thể loại**: "melancholic indie folk" (indie folk u buồn) chứ không chỉ viết "sad music" (nhạc buồn)
- **Gọi tên cụ thể các nhạc cụ**: "fingerpicked acoustic guitar, soft brushed drums, upright bass"
- **Thêm màu sắc sản xuất âm thanh**: "lo-fi warmth, vinyl crackle, bedroom recording feel"
- **TUYỆT ĐỐI KHÔNG dùng từ phủ định**: viết "no drums" sẽ không có tác dụng — chỉ mô tả những gì BẠN MUỐN CÓ
- **TUYỆT ĐỐI KHÔNG kết hợp các phong cách mâu thuẫn**: "vintage lo-fi" và "crisp modern production" triệt tiêu lẫn nhau
- **Giữ độ dài dưới 2000 ký tự**: các câu lệnh vượt quá giới hạn sẽ bị từ chối
### Công thức 8 Thành phần
Xây dựng câu lệnh bằng cách kết hợp tuần tự các thành phần sau:
1. **Thể loại / Phong cách (Genre/Style)**: "Indie folk", "Progressive house", "Soulful blues"
2. **Thời kỳ / Tham chiếu (Era/Reference)**: "1960s Motown", "modern", "80s synthwave"
3. **Tâm trạng / Cảm xúc (Mood/Emotion)**: "melancholic", "euphoric", "bittersweet", "triumphant"
4. **Loại Giọng hát (Vocal Type)**: "breathy female alto", "raspy male tenor", "choir harmonies"
5. **Nhịp độ / BPM (Tempo/BPM)**: "slow 60 BPM", "mid-tempo 100 BPM", "driving 128 BPM"
6. **Nhạc cụ (Instruments)**: "acoustic guitar, piano, strings, light percussion"
7. **Phong cách Sản xuất (Production Style)**: "lo-fi", "polished pop production", "raw live recording"
8. **Bầu không khí (Atmosphere)**: "intimate", "epic", "dreamy", "cinematic"
Không phải câu lệnh nào cũng cần đủ cả 8 thành phần — hãy sử dụng từ 4-6 thành phần cho các yêu cầu thông thường.
## Quy tắc Cấu trúc Lời bài hát
Khi giúp người dùng định dạng lời bài hát:
- Luôn đặt các thẻ cấu trúc trên một dòng riêng biệt ngay trước mỗi phân đoạn
- Sử dụng `\n` để ngắt dòng trong chuỗi lời bài hát, và `\n\n` để tạo khoảng nghỉ giữa các phân đoạn
- Giữ tổng độ dài dưới 3500 ký tự (bản thân các thẻ cũng được tính vào giới hạn ký tự này)
- Sử dụng `[Inst]` hoặc `[Solo]` cho các đoạn nhạc dạo không lời (không viết thêm chữ ngay dưới thẻ đó)
- Sử dụng `[Build Up]` trước đoạn điệp khúc (`[Chorus]`) để báo hiệu cường độ âm nhạc tăng dần
- Giữ số lượng âm tiết giữa các câu trong đoạn phiên khúc (`[Verse]`) đồng đều để tạo nhịp điệu tự nhiên
### Các Cấu trúc Bài hát Điển hình
**Pop/Rock Tiêu chuẩn:**
`[Intro] → [Verse] → [Pre Chorus] → [Chorus] → [Verse] → [Pre Chorus] → [Chorus] → [Bridge] → [Chorus] → [Outro]`
**Ballad:**
`[Intro] → [Verse] → [Verse] → [Chorus] → [Verse] → [Chorus] → [Bridge] → [Chorus] → [Outro]`
**Nhạc Điện tử / Dance:**
`[Intro] → [Build Up] → [Chorus] → [Break] → [Verse] → [Build Up] → [Chorus] → [Outro]`
**Đơn giản / Ngắn gọn:**
`[Verse] → [Chorus] → [Verse] → [Chorus] → [Outro]`
### Kiểm soát Nhạc Không lời so với Có lời
- **Bài hát đầy đủ có giọng hát**: Cung cấp văn bản lời bài hát bên dưới các thẻ cấu trúc
- **Nhạc hòa tấu không lời thuần túy (Pure instrumental)**: Chỉ sử dụng các thẻ `[Inst]`, hoặc cung cấp các thẻ cấu trúc mà không có văn bản lời bài hát bên dưới
- **Mở đầu bằng nhạc dạo rồi mới vào giọng hát**: Bắt đầu bằng thẻ `[Intro]` (không có chữ) sau đó đến thẻ `[Verse]` có lời bài hát
- **Đoạn nhạc dạo giữa bài**: Chèn thẻ `[Inst]` hoặc `[Solo]` vào giữa các phân đoạn có lời hát
## Xử lý Phản hồi (Response Handling)
Khi tạo mã nguồn hoặc giải thích phản hồi từ API:
- **Kiểm tra trạng thái**: `base_resp.status_code === 0` có nghĩa là thành công
- **Kiểm tra hoàn tất**: `data.status === 2` có nghĩa là quá trình tạo nhạc đã hoàn tất (`1` = vẫn đang xử lý)
- **Đầu ra dạng URL** (`output_format: "url"`): `data.audio` chứa đường dẫn URL để tải xuống (hết hạn sau 24 giờ)
- **Đầu ra dạng Hex** (`output_format: "hex"`): `data.audio` chứa các byte âm thanh được mã hóa dạng thập lục phân (hex) — giải mã bằng `bytes.fromhex()` (trong Python) hoặc `Buffer.from(hex, "hex")` (trong Node.js)
- **Truyền phát luồng** (`stream: true`): chỉ hoạt động với định dạng hex; các mảnh dữ liệu (chunks) được gửi tới qua giao thức SSE chứa các đoạn mã hex trong `data.audio`
- **Thông tin bổ sung**: đối tượng `extra_info` chứa thời lượng `music_duration` (tính bằng giây), tần số lấy mẫu `music_sample_rate`, số kênh `music_channel` (2=stereo), tốc độ bit `bitrate`, kích thước tệp `music_size` (tính bằng byte)
## Quy trình 6: Theo dõi Lịch sử Tạo Nhạc trên Google Sheets
Dự án bao gồm một công cụ theo dõi viết bằng Python tại `tracker/sheets_logger.py` giúp ghi nhận mọi lượt tạo nhạc vào một bảng điều khiển trên Google Sheet.
**Thiết lập (chỉ cần làm một lần):**
1. Người dùng cần một dự án Google Cloud đã bật Sheets API
2. Một tệp khóa JSON của tài khoản dịch vụ (service account)
3. Một bảng tính Google Sheet đã được chia sẻ quyền Chỉnh sửa (Editor) cho địa chỉ email của service account đó
4. Khai báo hai biến `GOOGLE_SHEET_ID` và `GOOGLE_SERVICE_ACCOUNT_JSON` trong tệp `.env`
5. Chạy lệnh `pip install -r tracker/requirements.txt`
**Cách sử dụng sau khi tạo nhạc:**
```python
from tracker.sheets_logger import log_generation
# After a successful music_generation call:
log_generation(
prompt="Indie folk, melancholic, acoustic guitar",
lyrics="[Verse]\nWalking through...",
audio_setting={"sample_rate": 44100, "bitrate": 256000, "format": "mp3"},
result=api_response, # the full JSON response dict
title="Autumn Walk"
)
```
Bảng điều khiển theo dõi 16 cột thông tin: Dấu thời gian (Timestamp), Tiêu đề (Title), Câu lệnh (Prompt), Trích đoạn Lời bài hát (Lyrics Excerpt), Thể loại (Genre), Tâm trạng (Mood), Loại Giọng hát (Vocal Type), Nhịp độ (BPM), Nhạc cụ (Instruments), Định dạng Âm thanh (Audio Format), Tần số Lấy mẫu (Sample Rate), Tốc độ Bit (Bitrate), Thời lượng (Duration), URL Đầu ra (Output URL), Trạng thái (Status), Thông tin Lỗi (Error Info).
Các thông tin về thể loại, tâm trạng, loại giọng hát, BPM và nhạc cụ sẽ được tự động trích xuất từ chuỗi câu lệnh (prompt).
## Lưu ý Quan trọng
- Các đường dẫn URL âm thanh sẽ hết hạn sau **24 giờ** — hãy luôn tải xuống và lưu trữ cục bộ ngay
- Mô hình có tính **bất định (nondeterministic)** — cùng một nội dung đầu vào giống hệt nhau có thể tạo ra các bản nhạc đầu ra khác nhau
- **Tiếng Trung và Tiếng Anh** đạt chất lượng giọng hát cao nhất; các ngôn ngữ khác có thể bị giảm chất lượng phát âm
- Nếu các ký tự không hợp lệ vượt quá **10%** tổng nội dung, hệ thống sẽ không tạo ra âm thanh
- Trên một số nền tảng, mỗi tài khoản chỉ được phép chạy một tiến trình tạo nhạc đồng thời tại một thời điểm
- Mô hình Music-2.5 hỗ trợ thời lượng âm thanh lên tới **~5 phút** cho mỗi lần tạo
FILE:references/api-reference.md
# Tài liệu Tham chiếu API Tạo Nhạc Minimax
## Xác thực (Authentication)
Mọi yêu cầu gửi đi đều bắt buộc phải có Bearer token trong tiêu đề Authorization.
```
Authorization: Bearer <MINIMAX_API_KEY>
Content-Type: application/json
```
**URL Cơ sở (Base URL):** `https://api.minimax.io/v1/`
Lấy khóa API của bạn tại [platform.minimax.io](https://platform.minimax.io) > Account Management > API Keys. Hãy sử dụng khóa thuộc gói **Trả tiền theo mức dùng (Pay-as-you-go)** — các khóa thuộc gói Coding Plan KHÔNG hỗ trợ tính năng tạo nhạc.
---
## Điểm cuối Tạo Nhạc (Music Generation Endpoint)
```
POST https://api.minimax.io/v1/music_generation
```
### Phần thân Yêu cầu (Request Body)
```json
{
"model": "music-2.5",
"prompt": "Indie folk, melancholic, acoustic guitar, soft piano, female vocals",
"lyrics": "[Verse]\nWalking through the autumn leaves\nNobody knows where I've been\n\n[Chorus]\nEvery road leads back to you",
"audio_setting": {
"sample_rate": 44100,
"bitrate": 256000,
"format": "mp3"
},
"output_format": "url",
"stream": false
}
```
### Tham chiếu Tham số
| Tham số | Kiểu dữ liệu | Bắt buộc | Mặc định | Ràng buộc | Mô tả |
| --- | --- | --- | --- | --- | --- |
| `model` | string | Có | — | `"music-2.5"` | Định danh phiên bản mô hình |
| `lyrics` | string | Có | — | 1-3500 ký tự | Lời bài hát kèm các thẻ cấu trúc và ký tự ngắt dòng `\n` |
| `prompt` | string | Không | `""` | 0-2000 ký tự | Các từ khóa mô tả phong cách âm nhạc, tâm trạng, thể loại, nhạc cụ |
| `audio_setting` | object | Không | xem bên dưới | — | Cấu hình chất lượng âm thanh |
| `output_format` | string | Không | `"hex"` | `"hex"` hoặc `"url"` | Định dạng phản hồi cho dữ liệu âm thanh |
| `stream` | boolean | Không | `false` | — | Bật chế độ truyền phát luồng (chỉ hỗ trợ đầu ra hex) |
### Đối tượng audio_setting
| Trường | Kiểu dữ liệu | Giá trị Hợp lệ | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `sample_rate` | integer | `16000`, `24000`, `32000`, `44100` | `44100` | Tần số lấy mẫu tính bằng Hz |
| `bitrate` | integer | `32000`, `64000`, `128000`, `256000` | `256000` | Tốc độ bit tính bằng bps |
| `format` | string | `"mp3"`, `"wav"`, `"pcm"` | `"mp3"` | Định dạng tệp âm thanh đầu ra |
### Các Thẻ Cấu trúc (Hỗ trợ 14 thẻ)
Các thẻ này điều khiển bố cục phối khí của bài hát. Hãy đặt mỗi thẻ trên một dòng riêng biệt ngay trước phần lời của phân đoạn đó:
| Thẻ | Mục đích |
| --- | --- |
| `[Intro]` | Đoạn mở đầu bằng nhạc cụ hoặc giọng hát |
| `[Verse]` | Phân đoạn lời chính (phiên khúc) |
| `[Pre Chorus]` | Đoạn dẫn đẩy cảm xúc trước khi vào điệp khúc |
| `[Chorus]` | Đoạn điệp khúc chính / điểm nhấn bài hát |
| `[Post Chorus]` | Phân đoạn nối tiếp ngay sau điệp khúc |
| `[Bridge]` | Phân đoạn chuyển tiếp tạo sự tương phản, thường đặt trước điệp khúc cuối |
| `[Interlude]` | Đoạn nhạc dạo xen giữa các phần |
| `[Outro]` | Phân đoạn kết bài |
| `[Transition]` | Đoạn chuyển tiếp âm nhạc ngắn giữa các phần |
| `[Break]` | Đoạn ngắt nhịp điệu hoặc khoảng lặng |
| `[Hook]` | Phân đoạn giai điệu bắt tai, dễ nhớ |
| `[Build Up]` | Đoạn dồn nhịp tăng dần cường độ trước đoạn drop hoặc điệp khúc |
| `[Inst]` | Phân đoạn chỉ có nhạc cụ (không có giọng hát) |
| `[Solo]` | Đoạn độc tấu nhạc cụ (solo guitar, v.v.) |
Các thẻ cấu trúc cũng được tính vào giới hạn 3500 ký tự.
### Phản hồi Thành công (output_format: "url")
```json
{
"trace_id": "0af12abc3def4567890abcdef1234567",
"data": {
"status": 2,
"audio": "https://cdn.minimax.io/music/output_abc123.mp3"
},
"extra_info": {
"music_duration": 187.4,
"music_sample_rate": 44100,
"music_channel": 2,
"bitrate": 256000,
"music_size": 6054912
},
"base_resp": {
"status_code": 0,
"status_msg": "success"
}
}
```
### Phản hồi Thành công (output_format: "hex")
```json
{
"trace_id": "0af12abc3def4567890abcdef1234567",
"data": {
"status": 2,
"audio": "fffb9064000000..."
},
"extra_info": {
"music_duration": 187.4,
"music_sample_rate": 44100,
"music_channel": 2,
"bitrate": 256000,
"music_size": 6054912
},
"base_resp": {
"status_code": 0,
"status_msg": "success"
}
}
```
### Tham chiếu Các Trường Phản hồi
| Trường | Kiểu dữ liệu | Mô tả |
| --- | --- | --- |
| `trace_id` | string | Mã định danh truy vết yêu cầu duy nhất dùng để gỡ lỗi |
| `data.status` | integer | `1` = đang xử lý, `2` = đã hoàn tất |
| `data.audio` | string | Đường dẫn URL âm thanh (chế độ url) hoặc chuỗi byte mã hóa hex (chế độ hex) |
| `extra_info.music_duration` | float | Thời lượng bài nhạc tính bằng giây |
| `extra_info.music_sample_rate` | integer | Tần số lấy mẫu thực tế đã sử dụng |
| `extra_info.music_channel` | integer | Số kênh âm thanh (`2` = âm thanh nổi stereo) |
| `extra_info.bitrate` | integer | Tốc độ bit thực tế đã sử dụng |
| `extra_info.music_size` | integer | Kích thước tệp tính bằng byte |
| `base_resp.status_code` | integer | `0` = thành công, xem thêm bảng mã lỗi |
| `base_resp.status_msg` | string | Thông báo trạng thái dễ đọc cho con người |
### Hành vi Truyền phát Luồng (Streaming Behavior)
Khi thiết lập `stream: true`:
- Chỉ hoạt động với `output_format: "hex"` (KHÔNG tương thích với `"url"`)
- Phản hồi được gửi về dưới dạng Server-Sent Events (SSE)
- Mỗi mảnh dữ liệu (chunk) chứa trường `data.audio` mang một đoạn mã hex
- Các mảnh có `data.status: 1` là dữ liệu âm thanh đang truyền
- Mảnh cuối cùng có `data.status: 2` chứa thông tin tổng kết
- Hãy nối (concatenate) toàn bộ các đoạn mã hex lại với nhau rồi giải mã để thu được tệp âm thanh hoàn chỉnh
---
## Điểm cuối Tạo Lời bài hát (Lyrics Generation Endpoint)
```
POST https://api.minimax.io/v1/lyrics_generation
```
### Phần thân Yêu cầu (Request Body)
```json
{
"mode": "write_full_song",
"prompt": "A soulful blues song about a rainy night and lost love"
}
```
### Tham chiếu Tham số
| Tham số | Kiểu dữ liệu | Bắt buộc | Mặc định | Ràng buộc | Mô tả |
| --- | --- | --- | --- | --- | --- |
| `mode` | string | Có | — | `"write_full_song"` hoặc `"edit"` | Chế độ tạo lời bài hát |
| `prompt` | string | Không | — | 0-2000 ký tự | Mô tả chủ đề, ý tưởng hoặc phong cách |
| `lyrics` | string | Không | — | 0-3500 ký tự | Lời bài hát hiện có (chỉ dùng trong chế độ chỉnh sửa edit) |
| `title` | string | Không | — | — | Tên bài hát (sẽ được giữ nguyên nếu người dùng cung cấp) |
### Phần thân Phản hồi (Response Body)
```json
{
"song_title": "Rainy Night Blues",
"style_tags": "Soulful Blues, Rainy Night, Melancholy, Male Vocals, Slow Tempo",
"lyrics": "[Verse]\nThe streetlights blur through window pane\nAnother night of autumn rain\n\n[Chorus]\nYou left me standing in the storm\nNow all I have is memories warm",
"base_resp": {
"status_code": 0,
"status_msg": "success"
}
}
```
### Tham chiếu Các Trường Phản hồi
| Trường | Kiểu dữ liệu | Mô tả |
| --- | --- | --- |
| `song_title` | string | Tên bài hát được tạo mới hoặc giữ nguyên từ đầu vào |
| `style_tags` | string | Các từ khóa mô tả phong cách phân cách bằng dấu phẩy (dùng làm prompt tạo nhạc) |
| `lyrics` | string | Lời bài hát được tạo kèm sẵn các thẻ cấu trúc — sẵn sàng truyền vào music_generation |
| `base_resp.status_code` | integer | `0` = thành công |
| `base_resp.status_msg` | string | Thông báo trạng thái |
### Quy trình Hai Bước (Two-Step Workflow)
```
Step 1: POST /v1/lyrics_generation
Input: { mode: "write_full_song", prompt: "theme description" }
Output: { song_title, style_tags, lyrics }
Step 2: POST /v1/music_generation
Input: { model: "music-2.5", prompt: style_tags, lyrics: lyrics }
Output: { data.audio (url hoặc hex) }
```
---
## Các Cấu hình Chất lượng Âm thanh Cài đặt sẵn (Audio Quality Presets)
### Băng thông Thấp (tệp nhỏ nhất)
```json
{ "sample_rate": 16000, "bitrate": 64000, "format": "mp3" }
```
### Xem trước / Bản nháp (Preview / Draft)
```json
{ "sample_rate": 24000, "bitrate": 128000, "format": "mp3" }
```
### Tiêu chuẩn (mặc định được khuyến nghị)
```json
{ "sample_rate": 44100, "bitrate": 256000, "format": "mp3" }
```
### Chuyên nghiệp / Nhập vào phần mềm DAW
```json
{ "sample_rate": 44100, "bitrate": 256000, "format": "wav" }
```
---
## Giới hạn Tần suất (Rate Limits) và Bảng giá
| Gói (Tier) | Chi phí Hàng tháng | Tín dụng (Credits) | RPM (yêu cầu/phút) |
| --- | --- | --- | --- |
| Starter | $5 | 100,000 | 10 |
| Standard | $30 | 300,000 | 50 |
| Pro | $99 | 1,100,000 | 200 |
| Scale | $249 | 3,300,000 | 500 |
| Business | $999 | 20,000,000 | 800 |
Lượng tín dụng tiêu thụ cho mỗi lần tạo phụ thuộc vào thời lượng âm thanh. Các đường dẫn URL âm thanh sẽ hết hạn sau 24 giờ.
FILE:references/prompt-engineering-guide.md
# Hướng Dẫn Kỹ Thuật Viết Prompt Âm Nhạc (Music Prompt Engineering Guide)
## Công Thức 8 Thành Phần
Xây dựng các prompt bằng cách kết hợp những thành phần này. Không bắt buộc phải có đủ tất cả — hãy sử dụng từ 4-6 thành phần cho các yêu cầu thông thường.
```
[Thể loại/Phong cách], [Thập niên/Tham chiếu], [Tâm trạng/Cảm xúc], [Loại giọng hát], [Nhịp độ/BPM], [Nhạc cụ], [Phong cách sản xuất], [Bầu không khí]
```
### Chi tiết Từng Thành phần
**1. Thể loại/Phong cách (Genre/Style)**
Indie folk, Progressive house, Soulful blues, Pop ballad, Jazz fusion, Synthwave, Ambient electronic, Country rock, Hip-hop boom bap, Classical orchestral (Giao hưởng cổ điển), R&B, Disco funk, Lo-fi indie, Metal
**2. Thập niên/Tham chiếu (Era/Reference)**
1960s Motown (Motown thập niên 1960), 70s disco (Disco thập niên 70), 80s synthwave (Synthwave thập niên 80), 90s grunge (Grunge thập niên 90), 2000s pop-punk (Pop-punk những năm 2000), modern (hiện đại), retro (hoài cổ), vintage (cổ điển xưa), contemporary (đương đại), classic (kinh điển)
**3. Tâm trạng/Cảm xúc (Mood/Emotion)**
melancholic (u sầu), euphoric (hưng phấn), nostalgic (hoài niệm), hopeful (hy vọng), bittersweet (ngọt ngào pha lẫn đắng cay), triumphant (khải hoàn), yearning (khát khao), peaceful (yên bình), brooding (trầm tư u uẩn), playful (tinh nghịch), intense (mãnh liệt), dreamy (mơ màng), defiant (thách thức), tender (dịu dàng), wistful (bâng khuâng), anthemic (hào hùng)
**4. Loại giọng hát (Vocal Type)**
breathy female alto (giọng nữ trầm hơi thở), powerful soprano (giọng nữ cao nội lực), raspy male tenor (giọng nam cao khàn), warm baritone (giọng nam trung ấm áp), deep resonant bass (giọng nam trầm vang sâu), falsetto (giọng giả thanh), husky (khàn trầm), crystal clear (trong trẻo như pha lê), choir harmonies (hòa âm hợp xướng), a cappella (hát mộc không nhạc đệm), duet (song ca), operatic (phong cách opera)
**5. Nhịp độ/BPM (Tempo/BPM)**
slow 60 BPM (chậm 60 BPM), ballad tempo 70 BPM (nhịp ballad 70 BPM), mid-tempo 100 BPM (nhịp vừa 100 BPM), upbeat 120 BPM (sôi động 120 BPM), driving 128 BPM (dồn dập 128 BPM), fast-paced 140 BPM (nhịp nhanh 140 BPM), energetic 160 BPM (tràn đầy năng lượng 160 BPM)
**6. Nhạc cụ (Instruments)**
acoustic guitar (guitar thùng), electric guitar (guitar điện), fingerpicked guitar (guitar gảy ngón), piano, Rhodes piano, upright bass (contrabass), electric bass (bass điện), drums (trống), brushed snare (trống snare đánh chổi), synthesizer (đàn tổng hợp âm), strings (dàn dây), violin, cello, trumpet, saxophone, harmonica, ukulele, banjo, mandolin, flute (sáo), organ (đàn ống/organ), harp (đàn hạc), percussion (bộ gõ), congas, tambourine (trống lục lạc), vibraphone, steel drums (trống thép)
**7. Phong cách Sản xuất (Production Style)**
lo-fi, polished pop production (sản xuất nhạc pop trau chuốt), raw live recording (thu âm trực tiếp mộc mạc), studio quality (chất lượng phòng thu), bedroom recording (thu âm tại phòng ngủ), vinyl warmth (chất âm ấm áp của đĩa than), analog tape (băng từ analog), digital crisp (sắc nét kỹ thuật số), spacious reverb (vang vọng không gian rộng), dry and intimate (mộc và gần gũi), heavily compressed (nén âm mạnh), minimalist (tối giản)
**8. Bầu không khí (Atmosphere)**
intimate (thân mật/gần gũi), epic (hùng vĩ), dreamy (mộng mơ), cinematic (đậm chất điện ảnh), ethereal (thanh thoát/huyền ảo), gritty (gai góc), lush (dày dặn/phong phú), sparse (thưa thoáng), warm (ấm áp), cold (lạnh lẽo), dark (u tối), bright (tươi sáng), urban (đô thị), pastoral (đồng quê), cosmic (vũ trụ), underground (ngầm/bụi bặm)
---
## Các Mẫu Prompt Theo Từng Thể Loại
### Pop
```
Upbeat pop, catchy chorus, synthesizer, four-on-the-floor beat, bright female vocals, radio-ready production, energetic 120 BPM
```
### Pop Ballad
```
Pop ballad, emotional, piano-driven, powerful female vocals with vibrato, sweeping strings, slow tempo 70 BPM, polished production, heartfelt
```
### Indie Folk
```
Indie folk, melancholic, introspective, acoustic fingerpicking guitar, soft piano, gentle male vocals, intimate bedroom recording, 90 BPM
```
### Soulful Blues
```
Soulful blues, rainy night, melancholy, raspy male vocals, slow tempo 65 BPM, electric guitar, upright bass, harmonica, warm analog feel
```
### Jazz
```
Jazz ballad, warm and intimate, upright bass, brushed snare, piano, muted trumpet, 1950s club atmosphere, smooth male vocals, 80 BPM
```
### Electronic / Dance
```
Progressive house, euphoric, driving bassline, 128 BPM, synthesizer pads, arpeggiated leads, modern production, festival energy, build-ups and drops
```
### Rock
```
Indie rock, anthemic, distorted electric guitar, powerful drum kit, passionate male vocals, stadium feel, energetic 140 BPM, raw energy
```
### Classical / Orchestral (Cổ điển / Giao hưởng)
```
Orchestral, sweeping strings, French horn, dramatic tension, cinematic, full symphony, dynamic crescendos, epic and majestic
```
### Hip-Hop
```
Lo-fi hip hop, boom bap, vinyl crackle, jazzy piano sample, relaxed beat 85 BPM, introspective mood, head-nodding groove
```
### R&B
```
Contemporary R&B, smooth, falsetto male vocals, Rhodes piano, muted guitar, late night urban feel, 90 BPM, lush production
```
### Country / Americana
```
Appalachian folk, storytelling, acoustic fingerpicking, fiddle, raw and honest, dusty americana, warm male vocals, 100 BPM
```
### Metal
```
Heavy metal, distorted riffs, double kick drum, aggressive powerful vocals, dark atmosphere, intense and relentless, 160 BPM
```
### Synthwave / Thập niên 80
```
Synthwave, 80s retro, pulsing synthesizers, gated reverb drums, neon-lit atmosphere, driving arpeggios, nostalgic and cinematic, 110 BPM
```
### Lo-fi Indie
```
Lo-fi indie pop, mellow 92 BPM, soft female vocals airy and intimate, clean electric guitar, lo-fi drums, vinyl warmth, bedroom recording aesthetic, late night melancholy
```
### Disco Funk
```
Disco funk, groovy bassline, wah-wah guitar, brass section, four-on-the-floor kick, 115 BPM, energetic female vocals, sparkling production, dancefloor energy
```
---
## Danh Mục Mô Tả Giọng Hát (Vocal Descriptor Catalog)
### Giọng Nữ (Female Vocals)
- `breathy female vocal with emotional delivery and subtle vibrato` (giọng nữ nhiều hơi với cách truyền tải giàu cảm xúc và độ rung nhẹ tinh tế)
- `powerful soprano, clear and soaring, with controlled dynamics` (giọng nữ cao nội lực, trong trẻo và vút cao, kiểm soát sắc thái tốt)
- `soft, intimate female alto, whispery and gentle` (giọng nữ trầm mềm mại, gần gũi, thì thầm và dịu dàng)
- `sassy, confident female voice with rhythmic phrasing` (giọng nữ cá tính, tự tin với cách nhả chữ giàu nhịp điệu)
- `ethereal, angelic female vocal with layered harmonies` (giọng nữ thanh thoát như thiên thần với nhiều lớp bè hòa âm)
- `raspy, soulful female voice with blues inflection` (giọng nữ khàn đầy tâm trạng mang âm hưởng nhạc blues)
### Giọng Nam (Male Vocals)
- `warm baritone, smooth and resonant, with emotional depth` (giọng nam trung ấm áp, mượt mà và vang vọng, có chiều sâu cảm xúc)
- `raspy male tenor with rock edge and raw power` (giọng nam cao khàn mang chất gai góc của rock và sức mạnh nguyên bản)
- `deep, resonant bass voice, commanding and rich` (giọng nam trầm sâu, vang rền, đầy uy lực và dày dặn)
- `falsetto male vocal, airy and delicate, R&B style` (giọng nam giả thanh, nhẹ bẫng và tinh tế, mang phong cách R&B)
- `gravelly crooner, vintage jazz feel, intimate delivery` (giọng hát trầm khàn kiểu ca sĩ phòng trà cổ điển, cảm giác jazz xưa, truyền tải gần gũi)
- `powerful tenor with soaring high notes and controlled vibrato` (giọng nam cao nội lực với những nốt cao vút và độ rung có kiểm soát)
### Hợp ca / Đặc biệt (Ensemble / Special)
- `male-female duet with harmonized chorus` (song ca nam-nữ với phần điệp khúc hòa âm)
- `choir harmonies, layered voices, cathedral reverb` (hòa âm dàn hợp xướng, nhiều lớp giọng đan xen, độ vang thánh đường)
- `a cappella vocal arrangement, no instruments` (phối khí giọng hát a cappella, không dùng nhạc cụ)
- `spoken word with musical backing` (giọng đọc truyền cảm trên nền nhạc đệm)
- `vocal ad-libs and runs between main phrases` (phiêu giọng ngẫu hứng và chạy nốt luyến láy giữa các câu hát chính)
---
## Từ Vựng Tâm Trạng/Cảm Xúc (Mood/Emotion Vocabulary)
Các từ mô tả này tương thích rất tốt với dữ liệu huấn luyện của Minimax:
| Phân loại | Từ vựng |
| --- | --- |
| Buồn (Sad) | melancholic, bittersweet, yearning, wistful, somber, mournful, lonely |
| Vui (Happy) | euphoric, joyful, uplifting, celebratory, playful, carefree, sunny |
| Mãnh liệt (Intense) | driving, powerful, fierce, relentless, urgent, explosive, raw |
| Êm dịu (Calm) | peaceful, serene, meditative, tranquil, floating, gentle, soothing |
| U tối (Dark) | brooding, ominous, haunting, sinister, shadowy, tense, mysterious |
| Lãng mạn (Romantic) | tender, intimate, warm, passionate, longing, devoted, sensual |
| Hùng vĩ (Epic) | triumphant, majestic, anthemic, soaring, grandiose, cinematic, sweeping |
| Hoài niệm (Nostalgic) | retro, vintage, throwback, reminiscent, dreamy, hazy, faded |
---
## Các Phản Mẫu Cần Tránh (Anti-Patterns to Avoid)
### Câu Phủ định (KHÔNG SỬ DỤNG)
Mô hình không xử lý đáng tin cậy các chỉ dẫn mang tính phủ định.
| Không tốt (Bad) | Tốt (Good) |
| --- | --- |
| "no drums" (không có trống) | "acoustic guitar and piano only" (chỉ có guitar thùng và piano) |
| "without vocals" (không có giọng hát) | sử dụng thẻ `[Inst]` trong phần lời bài hát |
| "not too fast" (đừng quá nhanh) | "slow tempo 70 BPM" (nhịp độ chậm 70 BPM) |
| "don't use autotune" (đừng dùng autotune) | "raw, natural vocal delivery" (cách hát mộc mạc, tự nhiên) |
### Phong cách Xung đột
Không kết hợp các phong cách thẩm mỹ mâu thuẫn nhau:
| Xung đột | Lý do |
| --- | --- |
| "vintage lo-fi" + "crisp modern production" | chất âm lo-fi cũ kỹ và độ sắc nét hiện đại là hai thái cực đối lập |
| "intimate whisper" + "powerful belting" | không thể vừa hát thì thầm gần gũi lại vừa gằn giọng lên cao đầy nội lực cùng lúc |
| "minimalist" + "full orchestra" | sự tối giản thưa thoáng đối lập với dàn nhạc giao hưởng dày đặc |
| "raw punk" + "polished pop production" | các phong cách sản xuất âm nhạc này xung đột trực tiếp với nhau |
### Quá Chung Chung (Quá Mơ Hồ)
| Yếu (Weak) | Mạnh (Strong) |
| --- | --- |
| "sad song with guitar" | "melancholic indie folk, fingerpicked acoustic guitar, male vocals, intimate, 85 BPM" |
| "happy music" | "upbeat pop, bright female vocals, synth and piano, 120 BPM, radio-ready" |
| "rock song" | "indie rock, anthemic, distorted electric guitar, driving drums, passionate vocals, 140 BPM" |
| "electronic music" | "progressive house, euphoric, 128 BPM, synthesizer pads, driving bassline" |
---
## Danh Sách Kiểm Tra Tinh Chỉnh Prompt
Khi rà soát một prompt, hãy kiểm tra:
1. Nó có chỉ định rõ một thể loại cụ thể không? (ví dụ: "indie folk" chứ không chỉ nói "folk")
2. Nó có bao gồm tâm trạng/cảm xúc không? (ít nhất một từ mô tả)
3. Nó có nêu tên các nhạc cụ cụ thể không? (chứ không chỉ nói "music")
4. Nó có cho biết nhịp độ hoặc mức năng lượng không? (chỉ số BPM hoặc từ mô tả)
5. Nó có mô tả phong cách giọng hát không? (nếu bài hát có lời)
6. Độ dài của nó có dưới 2000 ký tự không?
7. Có bất kỳ cấu trúc phủ định nào cần viết lại theo hướng khẳng định không?
8. Có bất kỳ sự kết hợp phong cách nào bị mâu thuẫn với nhau không?
FILE:references/error-codes.md
# Tài Liệu Tham Chiếu Lỗi API Minimax
## Bảng Mã Lỗi
| Mã (Code) | Tên lỗi | Nguyên nhân | Cách khắc phục |
| --- | --- | --- | --- |
| `0` | Success (Thành công) | Yêu cầu đã hoàn tất | Không cần thực hiện hành động nào |
| `1002` | Rate Limited (Giới hạn tần suất) | Quá nhiều yêu cầu trong một phút | Đợi 10-30 giây và thử lại với cơ chế lùi lũy thừa (exponential backoff) |
| `1004` | Auth Failed (Xác thực thất bại) | Khóa API không hợp lệ, đã hết hạn hoặc bị thiếu | Xác minh khóa tại platform.minimax.io, kiểm tra khoảng trắng thừa, tạo lại nếu đã hết hạn |
| `1008` | Insufficient Balance (Số dư không đủ) | Tài khoản đã hết tín dụng (credits) | Nạp thêm tín dụng tại platform.minimax.io > Billing |
| `1026` | Content Flagged (Nội dung bị gắn cờ) | Lời bài hát hoặc prompt kích hoạt bộ lọc kiểm duyệt nội dung | Sửa lại lời bài hát/prompt để loại bỏ nội dung nhạy cảm, bạo lực hoặc dung tục |
| `2013` | Invalid Parameters (Tham số không hợp lệ) | Phần thân yêu cầu (request body) có sai kiểu dữ liệu hoặc giá trị vượt ngoài phạm vi cho phép | Xác thực toàn bộ các tham số đối chiếu với lược đồ (schema) của API |
| `2049` | Invalid API Key Format (Sai định dạng khóa API) | Chuỗi khóa API bị sai định dạng | Kiểm tra ký tự xuống dòng ở cuối, khoảng trắng thừa hoặc lỗi sao chép-dán |
## Cây Quyết Định Xử Lý Sự Cố
```
Nhận được phản hồi báo lỗi?
│
├─ Kiểm tra base_resp.status_code
│
├─ 1002 (Rate Limited - Giới hạn tần suất)
│ ├─ Bạn có đang gửi nhiều yêu cầu liên tiếp không? → Thêm độ trễ giữa các lệnh gọi
│ ├─ Chỉ gửi một yêu cầu duy nhất? → Giới hạn RPM của gói bạn đang dùng có thể rất thấp (Starter = 10 RPM)
│ └─ Hành động: Chờ đợi, thử lại với cơ chế lùi lũy thừa (10s, 20s, 40s)
│
├─ 1004 (Auth Failed - Xác thực thất bại)
│ ├─ Đã thiết lập khóa API chưa? → Kiểm tra định dạng tiêu đề Authorization
│ ├─ Đó có phải là khóa thuộc gói Coding Plan không? → Dịch vụ âm nhạc cần khóa Pay-as-you-go
│ ├─ Khóa đã hết hạn chưa? → Tạo lại khóa mới tại platform.minimax.io
│ └─ Hành động: Xác minh "Authorization: Bearer <key>" không có khoảng trắng thừa
│
├─ 1008 (Insufficient Balance - Số dư không đủ)
│ ├─ Kiểm tra số dư tín dụng tại platform.minimax.io
│ └─ Hành động: Nạp thêm tín dụng, hoặc nâng cấp lên gói cao hơn
│
├─ 1026 (Content Flagged - Nội dung bị gắn cờ)
│ ├─ Rà soát lời bài hát xem có từ ngữ hoặc chủ đề nhạy cảm không
│ ├─ Rà soát prompt xem có nội dung nhạy cảm/dung tục không
│ └─ Hành động: Chỉnh sửa và gửi lại; chính sách kiểm duyệt chi tiết không được công bố công khai
│
├─ 2013 (Invalid Parameters - Tham số không hợp lệ)
│ ├─ Tham số model đã được đặt là "music-2.5" chưa? (không phải "music-01" hay giá trị khác)
│ ├─ Độ dài lyrics có nằm trong khoảng 1-3500 ký tự không?
│ ├─ Độ dài prompt có dưới 2000 ký tự không?
│ ├─ Giá trị sample_rate có thuộc một trong các mức: 16000, 24000, 32000, 44100 không?
│ ├─ Giá trị bitrate có thuộc một trong các mức: 32000, 64000, 128000, 256000 không?
│ ├─ Giá trị format có thuộc một trong các định dạng: "mp3", "wav", "pcm" không?
│ ├─ Giá trị output_format có thuộc một trong hai kiểu: "hex", "url" không?
│ └─ Hành động: Sửa lại tham số không hợp lệ và thử lại
│
├─ 2049 (Invalid API Key Format - Sai định dạng khóa API)
│ ├─ Khóa có bị dính ký tự xuống dòng hoặc khoảng trắng ở cuối không?
│ ├─ Khóa đã được sao chép chính xác từ bảng điều khiển (dashboard) chưa?
│ └─ Hành động: Sao chép lại khóa, cắt bỏ khoảng trắng thừa ở hai đầu (trim)
│
└─ data.status === 1 (Không phải lỗi!)
└─ Quá trình tạo nhạc vẫn đang diễn ra. Hãy truy vấn (poll) lại hoặc đợi đến khi hoàn tất.
```
## Các Lỗi Tham Số Thường Gặp
| Lỗi thường gặp | Vấn đề | Cách khắc phục |
| --- | --- | --- |
| `"model": "music-01"` | Sai tên mô hình cho API gốc | Sử dụng `"music-2.5"` |
| `"lyrics": ""` | Chuỗi lời bài hát bị rỗng | Lời bài hát phải dài từ 1-3500 ký tự |
| `"sample_rate": 48000` | Tần số lấy mẫu không hợp lệ | Sử dụng 16000, 24000, 32000 hoặc 44100 |
| `"bitrate": 320000` | Tốc độ bit không hợp lệ | Sử dụng 32000, 64000, 128000 hoặc 256000 |
| `"format": "flac"` | Định dạng không được hỗ trợ | Sử dụng "mp3", "wav" hoặc "pcm" |
| `"stream": true` + `"output_format": "url"` | Chế độ truyền phát (streaming) chỉ hỗ trợ hex | Đặt `output_format` thành `"hex"` hoặc tắt chế độ streaming |
| Thiếu tiêu đề `Content-Type` | Máy chủ không thể phân tích cú pháp JSON | Thêm tiêu đề `Content-Type: application/json` |
| Khóa bị dính ký tự `\n` ở cuối | Xác thực thất bại ngầm | Cắt bỏ khoảng trắng/ký tự xuống dòng ở hai đầu chuỗi khóa |
| Prompt dài quá 2000 ký tự | Bị API từ chối | Rút ngắn độ dài prompt |
| Lời bài hát dài quá 3500 ký tự | Bị API từ chối | Rút ngắn lời bài hát hoặc lược bớt các thẻ cấu trúc |
## Các Mã Trạng Thái HTTP
| Trạng thái HTTP | Ý nghĩa | Hành động |
| --- | --- | --- |
| `200` | Yêu cầu đã được xử lý | Kiểm tra `base_resp.status_code` để phát hiện các lỗi ở cấp độ API |
| `401` | Chưa được cấp quyền (Unauthorized) | Khóa API bị thiếu hoặc không hợp lệ |
| `429` | Quá nhiều yêu cầu (Too Many Requests) | Bị giới hạn tần suất — hãy giãn thời gian chờ và thử lại |
| `500` | Lỗi máy chủ (Server Error) | Thử lại sau một khoảng trễ ngắn |
| `503` | Dịch vụ không khả dụng (Service Unavailable) | Máy chủ Minimax đang quá tải — hãy thử lại sau |
FILE:examples/code-examples.md
# Các Ví Dụ Mã Nguồn (Code Examples)
Tất cả các ví dụ đều nạp khóa API từ tệp `.env` thông qua biến môi trường.
---
## Python: Tạo Nhạc (Đầu ra dạng URL)
```python
import os
import requests
from dotenv import load_dotenv
load_dotenv()
API_KEY = os.getenv("MINIMAX_API_KEY")
def generate_music(prompt, lyrics, output_file="output.mp3"):
response = requests.post(
"https://api.minimax.io/v1/music_generation",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
},
json={
"model": "music-2.5",
"prompt": prompt,
"lyrics": lyrics,
"audio_setting": {
"sample_rate": 44100,
"bitrate": 256000,
"format": "mp3"
},
"output_format": "url"
}
)
response.raise_for_status()
result = response.json()
if result["base_resp"]["status_code"] != 0:
raise Exception(f"API error {result['base_resp']['status_code']}: {result['base_resp']['status_msg']}")
audio_url = result["data"]["audio"]
duration = result["extra_info"]["music_duration"]
print(f"Generated {duration:.1f}s of music")
audio_data = requests.get(audio_url)
with open(output_file, "wb") as f:
f.write(audio_data.content)
print(f"Saved to {output_file}")
return result
# Usage
generate_music(
prompt="Indie folk, melancholic, acoustic guitar, soft piano, female vocals",
lyrics="""[Intro]
[Verse]
Walking through the autumn leaves
Nobody knows where I've been
[Chorus]
Every road leads back to you
Every song I hear rings true
[Outro]
""",
output_file="my_song.mp3"
)
```
---
## Python: Tạo Nhạc (Đầu ra dạng Hex)
```python
import os
import binascii
import requests
from dotenv import load_dotenv
load_dotenv()
API_KEY = os.getenv("MINIMAX_API_KEY")
def generate_music_hex(prompt, lyrics, output_file="output.mp3"):
response = requests.post(
"https://api.minimax.io/v1/music_generation",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
},
json={
"model": "music-2.5",
"prompt": prompt,
"lyrics": lyrics,
"audio_setting": {
"sample_rate": 44100,
"bitrate": 256000,
"format": "mp3"
},
"output_format": "hex"
}
)
response.raise_for_status()
result = response.json()
if result["base_resp"]["status_code"] != 0:
raise Exception(f"API error: {result['base_resp']['status_msg']}")
audio_bytes = binascii.unhexlify(result["data"]["audio"])
with open(output_file, "wb") as f:
f.write(audio_bytes)
print(f"Saved {len(audio_bytes)} bytes to {output_file}")
```
---
## Python: Quy trình Hai Bước (Tạo Lời trước, Tạo Nhạc sau)
```python
import os
import requests
from dotenv import load_dotenv
load_dotenv()
API_KEY = os.getenv("MINIMAX_API_KEY")
BASE_URL = "https://api.minimax.io/v1"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
def generate_lyrics(theme):
"""Step 1: Generate structured lyrics from a theme."""
response = requests.post(
f"{BASE_URL}/lyrics_generation",
headers=HEADERS,
json={
"mode": "write_full_song",
"prompt": theme
}
)
response.raise_for_status()
data = response.json()
if data["base_resp"]["status_code"] != 0:
raise Exception(f"Lyrics error: {data['base_resp']['status_msg']}")
return data
def generate_music(style_prompt, lyrics, output_file="song.mp3"):
"""Step 2: Generate music from lyrics and a style prompt."""
response = requests.post(
f"{BASE_URL}/music_generation",
headers=HEADERS,
json={
"model": "music-2.5",
"prompt": style_prompt,
"lyrics": lyrics,
"audio_setting": {
"sample_rate": 44100,
"bitrate": 256000,
"format": "mp3"
},
"output_format": "url"
}
)
response.raise_for_status()
result = response.json()
if result["base_resp"]["status_code"] != 0:
raise Exception(f"Music error: {result['base_resp']['status_msg']}")
audio_data = requests.get(result["data"]["audio"])
with open(output_file, "wb") as f:
f.write(audio_data.content)
print(f"Saved to {output_file} ({result['extra_info']['music_duration']:.1f}s)")
return result
# Full workflow
theme = "A soulful blues song about a rainy night and lost love"
style = "Soulful blues, rainy night, melancholy, male vocals, slow tempo, electric guitar, upright bass"
print("Step 1: Generating lyrics...")
lyrics_data = generate_lyrics(theme)
print(f"Title: {lyrics_data['song_title']}")
print(f"Style: {lyrics_data['style_tags']}")
print(f"Lyrics:\n{lyrics_data['lyrics']}\n")
print("Step 2: Generating music...")
generate_music(style, lyrics_data["lyrics"], "blues_song.mp3")
```
---
## Python: Phản hồi Truyền phát (Streaming Response)
```python
import os
import json
import binascii
import requests
from dotenv import load_dotenv
load_dotenv()
API_KEY = os.getenv("MINIMAX_API_KEY")
def generate_music_streaming(prompt, lyrics, output_file="stream_output.mp3"):
response = requests.post(
"https://api.minimax.io/v1/music_generation",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
},
json={
"model": "music-2.5",
"prompt": prompt,
"lyrics": lyrics,
"audio_setting": {
"sample_rate": 44100,
"bitrate": 256000,
"format": "mp3"
},
"output_format": "hex",
"stream": True
},
stream=True
)
response.raise_for_status()
chunks = []
for line in response.iter_lines():
if not line:
continue
line_str = line.decode("utf-8")
if not line_str.startswith("data:"):
continue
data = json.loads(line_str[5:].strip())
if data.get("base_resp", {}).get("status_code", 0) != 0:
raise Exception(f"Stream error: {data['base_resp']['status_msg']}")
if data.get("data", {}).get("status") == 1 and data["data"].get("audio"):
chunks.append(binascii.unhexlify(data["data"]["audio"]))
audio_bytes = b"".join(chunks)
with open(output_file, "wb") as f:
f.write(audio_bytes)
print(f"Streaming complete: {len(audio_bytes)} bytes saved to {output_file}")
```
---
## JavaScript / Node.js: Tạo Nhạc (Đầu ra dạng URL)
```javascript
import "dotenv/config";
import { writeFile } from "fs/promises";
const API_KEY = process.env.MINIMAX_API_KEY;
async function generateMusic(prompt, lyrics, outputPath = "output.mp3") {
const response = await fetch("https://api.minimax.io/v1/music_generation", {
method: "POST",
headers: {
Authorization: `Bearer API_KEY`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "music-2.5",
prompt,
lyrics,
audio_setting: { sample_rate: 44100, bitrate: 256000, format: "mp3" },
output_format: "url",
}),
});
const result = await response.json();
if (result.base_resp?.status_code !== 0) {
throw new Error(`API Error result.base_resp?.status_code: result.base_resp?.status_msg`);
}
const audioUrl = result.data.audio;
const audioResponse = await fetch(audioUrl);
const audioBuffer = Buffer.from(await audioResponse.arrayBuffer());
await writeFile(outputPath, audioBuffer);
console.log(`Saved to outputPath (result.extra_info.music_duration.toFixed(1)s)`);
return result;
}
// Usage
await generateMusic(
"Pop, upbeat, energetic, female vocals, synthesizer, driving beat",
`[Verse]
Running through the city lights
Everything is burning bright
[Chorus]
We are alive tonight
Dancing through the neon light`,
"pop_song.mp3"
);
```
---
## JavaScript / Node.js: Đầu ra dạng Hex kèm Giải mã (Decode)
```javascript
import "dotenv/config";
import { writeFile } from "fs/promises";
const API_KEY = process.env.MINIMAX_API_KEY;
async function generateMusicHex(prompt, lyrics, outputPath = "output.mp3") {
const response = await fetch("https://api.minimax.io/v1/music_generation", {
method: "POST",
headers: {
Authorization: `Bearer API_KEY`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "music-2.5",
prompt,
lyrics,
audio_setting: { sample_rate: 44100, bitrate: 256000, format: "mp3" },
output_format: "hex",
}),
});
const result = await response.json();
if (result.base_resp?.status_code !== 0) {
throw new Error(`API Error: result.base_resp?.status_msg`);
}
const audioBuffer = Buffer.from(result.data.audio, "hex");
await writeFile(outputPath, audioBuffer);
console.log(`Saved audioBuffer.length bytes to outputPath`);
}
```
---
## JavaScript / Node.js: Truyền phát (Streaming)
```javascript
import "dotenv/config";
import { writeFile } from "fs/promises";
const API_KEY = process.env.MINIMAX_API_KEY;
async function generateMusicStreaming(prompt, lyrics, outputPath = "stream_output.mp3") {
const response = await fetch("https://api.minimax.io/v1/music_generation", {
method: "POST",
headers: {
Authorization: `Bearer API_KEY`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "music-2.5",
prompt,
lyrics,
audio_setting: { sample_rate: 44100, bitrate: 256000, format: "mp3" },
output_format: "hex",
stream: true,
}),
});
const chunks = [];
const decoder = new TextDecoder();
const reader = response.body.getReader();
let buffer = "";
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
let boundary;
while ((boundary = buffer.indexOf("\n\n")) !== -1) {
const event = buffer.slice(0, boundary).trim();
buffer = buffer.slice(boundary + 2);
if (!event) continue;
const dataMatch = event.match(/^data:\s*(.+)$/m);
if (!dataMatch) continue;
const parsed = JSON.parse(dataMatch[1]);
if (parsed.base_resp?.status_code !== 0) {
throw new Error(`Stream error: parsed.base_resp?.status_msg`);
}
if (parsed.data?.status === 1 && parsed.data?.audio) {
chunks.push(Buffer.from(parsed.data.audio, "hex"));
}
}
}
const fullAudio = Buffer.concat(chunks);
await writeFile(outputPath, fullAudio);
console.log(`Streaming complete: fullAudio.length bytes saved to outputPath`);
}
```
---
## cURL: Tạo Nhạc
```bash
curl -X POST "https://api.minimax.io/v1/music_generation" \
-H "Authorization: Bearer $MINIMAX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "music-2.5",
"prompt": "Indie folk, melancholic, acoustic guitar, soft piano",
"lyrics": "[Verse]\nWalking through the autumn leaves\nNobody knows where I have been\n\n[Chorus]\nEvery road leads back to you\nEvery song I hear rings true",
"audio_setting": {
"sample_rate": 44100,
"bitrate": 256000,
"format": "mp3"
},
"output_format": "url"
}'
```
---
## cURL: Tạo Lời Bài Hát
```bash
curl -X POST "https://api.minimax.io/v1/lyrics_generation" \
-H "Authorization: Bearer $MINIMAX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "write_full_song",
"prompt": "A soulful blues song about a rainy night and lost love"
}'
```
---
## Các Cấu hình Chất lượng Âm thanh Cài đặt sẵn
### Cấu hình cài đặt sẵn dạng dict trong Python
```python
QUALITY_LOW = {"sample_rate": 16000, "bitrate": 64000, "format": "mp3"}
QUALITY_PREVIEW = {"sample_rate": 24000, "bitrate": 128000, "format": "mp3"}
QUALITY_STANDARD = {"sample_rate": 44100, "bitrate": 256000, "format": "mp3"}
QUALITY_PROFESSIONAL = {"sample_rate": 44100, "bitrate": 256000, "format": "wav"}
```
### Cấu hình cài đặt sẵn dạng object trong JavaScript
```javascript
const QUALITY_LOW = { sample_rate: 16000, bitrate: 64000, format: "mp3" };
const QUALITY_PREVIEW = { sample_rate: 24000, bitrate: 128000, format: "mp3" };
const QUALITY_STANDARD = { sample_rate: 44100, bitrate: 256000, format: "mp3" };
const QUALITY_PROFESSIONAL = { sample_rate: 44100, bitrate: 256000, format: "wav" };
```
FILE:examples/lyrics-templates.md
# Các Mẫu Lời Bài Hát (Lyrics Templates)
## Các Mẫu Cấu Trúc Bài Hát
Các bố cục phối khí phổ biến dưới dạng chuỗi thẻ (tag sequences):
**Pop/Rock Tiêu chuẩn:**
`[Intro] → [Verse] → [Pre Chorus] → [Chorus] → [Verse] → [Pre Chorus] → [Chorus] → [Bridge] → [Chorus] → [Outro]`
**Ballad:**
`[Intro] → [Verse] → [Verse] → [Chorus] → [Verse] → [Chorus] → [Bridge] → [Chorus] → [Outro]`
**Electronic/Dance:**
`[Intro] → [Build Up] → [Chorus] → [Break] → [Verse] → [Build Up] → [Chorus] → [Outro]`
**Đơn giản/Ngắn gọn:**
`[Verse] → [Chorus] → [Verse] → [Chorus] → [Outro]`
**Progressive/Epic (Phát triển tuần tự/Hùng vĩ):**
`[Intro] → [Verse] → [Pre Chorus] → [Chorus] → [Interlude] → [Verse] → [Pre Chorus] → [Chorus] → [Bridge] → [Solo] → [Build Up] → [Chorus] → [Outro]`
---
## Mẫu Bài Hát Pop (Pop Song Template)
```
[Intro]
[Verse]
Morning light breaks through my window pane
Another day I try to start again
The coffee's cold, the silence fills the room
But something tells me change is coming soon
[Pre Chorus]
I can feel it in the air tonight
Something shifting, pulling me toward the light
[Chorus]
I'm breaking through the walls I built
Letting go of all this guilt
Every step I take is mine
I'm finally feeling fine
I'm breaking through
[Verse]
The photographs are fading on the shelf
I'm learning how to just be myself
No more hiding underneath the weight
Of everything I thought would make me great
[Pre Chorus]
I can feel it in the air tonight
Something shifting, pulling me toward the light
[Chorus]
I'm breaking through the walls I built
Letting go of all this guilt
Every step I take is mine
I'm finally feeling fine
I'm breaking through
[Bridge]
It took so long to see
The only one holding me back was me
[Chorus]
I'm breaking through the walls I built
Buông bỏ hết những mặc cảm tội lỗi này
Mỗi bước chân tôi đi đều thuộc về chính tôi
Cuối cùng tôi cũng cảm thấy thật nhẹ nhõm
Tôi đang phá vỡ mọi rào cản
[Outro]
```
---
## Mẫu Bài Hát Rock (Rock Song Template)
```
[Intro]
[Verse]
Tiếng động cơ gầm vang trên xa lộ vắng tanh
Ánh đèn pha xé toạc màn đêm u tối
Chạy trốn khỏi cuộc đời tôi từng quen thuộc
Đuổi theo một tia lửa phía chân trời xa xôi
[Verse]
Chiếc radio phát vang khúc ca vụn vỡ của chúng ta
Hạ kính xe xuống và buông bỏ tất cả
Mỗi dặm đường qua đi lại bỏ lại mọi thứ phía sau lưng
Mọi biển báo đều nhắc đừng ngoảnh đầu nhìn về nhà
[Pre Chorus]
Đêm nay chúng ta đốt cháy tất cả
Đêm nay chúng ta vươn lên hoặc gục ngã
[Chorus]
Chúng ta là những trái tim liều lĩnh
Xé toạc cả thế giới này ra
Không gì có thể dập tắt ngọn lửa cháy bỏng bên trong
Chúng ta là những trái tim liều lĩnh
[Inst]
[Verse]
Ánh đèn đường chập chờn như một lời cảnh báo
Nhưng tôi đã đi quá xa để còn bận tâm
Chọn con đường dài thoát khỏi chốn hư không
Chợt nhận ra mình đã đến đích từ lúc nào
[Pre Chorus]
Đêm nay chúng ta đốt cháy tất cả
Đêm nay chúng ta vươn lên hoặc gục ngã
[Chorus]
Chúng ta là những trái tim liều lĩnh
Xé toạc cả thế giới này ra
Không gì có thể dập tắt ngọn lửa cháy bỏng bên trong
Chúng ta là những trái tim liều lĩnh
[Bridge]
Họ từng nói chúng ta sẽ chẳng bao giờ làm được
Nói rằng chúng ta sẽ đâm sầm và cháy rụi
Nhưng hãy nhìn chúng ta vẫn đang hiên ngang đứng vững
Mỗi vết sẹo là một bài học khắc cốt ghi tâm
[Solo]
[Build Up]
Chúng ta là, chúng ta là, chúng ta là
[Chorus]
Chúng ta là những trái tim liều lĩnh
Xé toạc cả thế giới này ra
Không gì có thể dập tắt ngọn lửa cháy bỏng bên trong
Chúng ta là những trái tim liều lĩnh
[Outro]
```
---
## Mẫu Bài Hát Ballad (Ballad Template)
```
[Intro]
[Verse]
Hàng cây mùa đông trơ trụi và tĩnh lặng
Tuyết rơi êm đềm trên sườn đồi xa
Tôi nhớ về ngày người từng nắm lấy tay tôi
Dạo bước trên những con đường ta từng cùng vẽ tương lai
[Verse]
Tiếng cười của người vẫn vang vọng khắp hành lang này
Tên của người vẫn khắc ghi trên những bức tường kia
Thời gian đã cuốn đi những gì ta từng có
Nhưng ký ức vẫn khiến lòng tôi ấm áp mỉm cười
[Chorus]
Tôi sẽ luôn mang hình bóng người theo bên mình
Băng qua những bão giông và vượt qua biển lớn
Ngay cả khi cả thế gian chìm vào bóng tối
Người vẫn là đốm lửa hồng sưởi ấm trái tim tôi
Tôi sẽ luôn mang người theo bên mình
[Verse]
Bốn mùa cứ thế đổi thay nhưng tôi vẫn ở lại
Đứng nơi đây đi qua nắng mưa cuộc đời
Mỗi vì sao tôi ngắm nhìn trong đêm tối
Đều gợi nhắc về ánh sáng dịu dàng của người
[Chorus]
Tôi sẽ luôn mang hình bóng người theo bên mình
Băng qua những bão giông và vượt qua biển lớn
Ngay cả khi cả thế gian chìm vào bóng tối
Người vẫn là đốm lửa hồng sưởi ấm trái tim tôi
Tôi sẽ luôn mang người theo bên mình
[Bridge]
Và nếu năm tháng có cuốn trôi đi mất
Mọi lời yêu thương tôi từng định ngỏ cùng người
Xin hãy biết rằng tình yêu ấy luôn là chân thật
Mọi khoảnh khắc trong đời đều dẫn lối về phía người
[Chorus]
Tôi sẽ luôn mang hình bóng người theo bên mình
Băng qua những bão giông và vượt qua biển lớn
Ngay cả khi cả thế gian chìm vào bóng tối
Người vẫn là đốm lửa hồng sưởi ấm trái tim tôi
Tôi sẽ luôn mang người theo bên mình
[Outro]
```
---
## Mẫu Bài Hát Hip-Hop / R&B (Hip-Hop / R&B Template)
```
[Intro]
[Verse]
Ánh đèn thành phố phản chiếu trên mặt đường mưa ướt
Lại một đêm khuya miệt mài cày cuốc vượt qua nỗi đau
Bắt đầu từ dưới đáy sâu với một giấc mơ lớn
Chẳng có điều gì dễ dàng như vẻ bề ngoài của nó
Mẹ dặn tôi phải luôn ngẩng cao đầu
Ngay cả khi mây giông phủ kín cả bầu trời
Giờ đây tôi đứng hiên ngang vượt lên trên mọi ồn ào
Tìm thấy tiếng nói riêng và đưa ra lựa chọn của đời mình
[Hook]
Chúng ta không dừng lại, cứ thế tiến về phía trước
Mỗi ngày qua đi lại tiếp tục chứng minh
Rằng sự nỗ lực sẽ không vì điều gì mà ngừng nghỉ
Chúng ta cứ thế bứt phá, miệt mài vươn lên
[Verse]
Nhìn quanh tất cả những gì chúng ta đã gây dựng
Từ đống tro tàn vươn dậy không còn chút hối tiếc
Mỗi vết sẹo là một câu chuyện của riêng tôi
Hạt giống của những tháng ngày gian khó nay đã đơm hoa
Đêm thức khuya ngày dậy sớm cứ thế lặp đi lặp lại
Mỗi lần vấp ngã càng làm hương vị chiến thắng thêm ngọt ngào
Giờ đây họ đã thấy tầm nhìn này rõ như pha lê
Chúng ta đã bền bỉ xây đắp cơ đồ này suốt bao năm qua
[Hook]
Chúng ta không dừng lại, cứ thế tiến về phía trước
Mỗi ngày qua đi lại tiếp tục chứng minh
Rằng sự nỗ lực sẽ không vì điều gì mà ngừng nghỉ
Chúng ta cứ thế bứt phá, miệt mài vươn lên
[Bridge]
Từ vực sâu vươn tới đỉnh cao
Chúng ta chẳng biết dừng lại là gì
[Hook]
Chúng ta không dừng lại, cứ thế tiến về phía trước
Mỗi ngày qua đi lại tiếp tục chứng minh
Rằng sự nỗ lực sẽ không vì điều gì mà ngừng nghỉ
Chúng ta cứ thế bứt phá, miệt mài vươn lên
[Outro]
```
---
## Mẫu Bài Hát Electronic / Dance (Electronic / Dance Template)
```
[Intro]
[Build Up]
Cảm nhận nhịp đập rung chuyển dưới sàn nhảy
Bạn có nghe thấy âm thanh đang khao khát bùng nổ hơn nữa
[Chorus]
Hãy thả mình tan vào ánh đèn neon rực rỡ
Đêm nay chúng ta thực sự sống hết mình
Hãy để âm nhạc nắm quyền điều khiển
Cảm nhận từng nhịp điệu thấm sâu vào tâm hồn
Đêm nay chúng ta thực sự sống hết mình
[Break]
[Verse]
Những người xa lạ khiêu vũ cạnh bên nhau
Trong khoảnh khắc này chẳng có gì phải giấu giếm
Mọi nhịp đập con tim hòa chung một nhịp
Đắm chìm trong tiết tấu, lạc lối giữa giai điệu
[Build Up]
Cảm nhận nhịp đập rung chuyển dưới sàn nhảy
Bạn có nghe thấy âm thanh đang khao khát bùng nổ hơn nữa
Vang lên nữa, lớn hơn nữa
[Chorus]
Hãy thả mình tan vào ánh đèn neon rực rỡ
Đêm nay chúng ta thực sự sống hết mình
Hãy để âm nhạc nắm quyền điều khiển
Cảm nhận từng nhịp điệu thấm sâu vào tâm hồn
Đêm nay chúng ta thực sự sống hết mình
[Inst]
[Build Up]
Thêm một lần nữa nào
[Chorus]
Hãy thả mình tan vào ánh đèn neon rực rỡ
Đêm nay chúng ta thực sự sống hết mình
Hãy để âm nhạc nắm quyền điều khiển
Cảm nhận từng nhịp điệu thấm sâu vào tâm hồn
Đêm nay chúng ta thực sự sống hết mình
[Outro]
```
---
## Mẫu Bài Hát Folk / Acoustic (Folk / Acoustic Template)
```
[Intro]
[Verse]
Dưới bờ sông nơi những rặng liễu nghiêng mình
Tôi tìm thấy một bức thư giữa sắc xanh mùa thu
Từng con chữ tựa dòng nước chảy êm đềm và chậm rãi
Kể lại những câu chuyện từ thuở xa xưa lắm rồi
[Verse]
Ông nội tôi đã từng bước đi trên những con đường này
Mang trên vai gánh nặng đi qua một thế giới chìm trong khói lửa
Nhưng ông chưa bao giờ đánh mất sự dịu dàng của mình
Và lòng nhân hậu của ông vẫn sống mãi trong tôi hôm nay
[Chorus]
Những con đường xưa cũ này ghi nhớ mọi điều
Từng dấu chân qua, từng khúc hát ta ngân nga
Băng qua những thung lũng và làn gió núi ngàn
Tình yêu thương được gieo mầm ở khắp muôn nơi
Những con đường xưa cũ này vẫn luôn ghi nhớ
[Verse]
Giờ đây bốn mùa nhuộm vàng những triền đồi
Và những câu chuyện xưa giữ cho thế hệ trẻ khỏi giá lạnh
Mỗi buổi hoàng hôn buông xuống lại mang theo lời nguyện cầu bình yên
Dành cho những người nay đã không còn ở nơi đây nữa
[Chorus]
Những con đường xưa cũ này ghi nhớ mọi điều
Từng dấu chân qua, từng khúc hát ta ngân nga
Băng qua những thung lũng và làn gió núi ngàn
Tình yêu thương được gieo mầm ở khắp muôn nơi
Những con đường xưa cũ này vẫn luôn ghi nhớ
[Bridge]
Vậy nên tôi sẽ bước tiếp thêm một đoạn đường nữa
Đi qua ngôi nhà nguyện nhỏ trên ngọn đồi xa xăm
Và tôi sẽ lắng nghe những tiếng vọng nơi ấy
Được làn gió chiều nâng niu mang đi thật khẽ khàng
[Chorus]
Những con đường xưa cũ này ghi nhớ mọi điều
Từng dấu chân qua, từng khúc hát ta ngân nga
Băng qua những thung lũng và làn gió núi ngàn
Tình yêu thương được gieo mầm ở khắp muôn nơi
Những con đường xưa cũ này vẫn luôn ghi nhớ
[Outro]
```
---
## Mẫu Bài Hát Jazz (Jazz Template)
```
[Intro]
[Verse]
Làn khói thuốc cuộn tròn chậm rãi dưới ánh đèn màu hổ phách
Tiếng dương cầm thì thầm xuyên qua màn đêm nhung mượt
Một ly rượu sóng sánh sắc vàng trên tay tôi
Người nghệ sĩ trống giữ nhịp chổi quét êm ái trên mặt trống snare
[Verse]
Nàng bước vào tựa như một bản nhạc tôi từng quen thuộc
Một giai điệu vọng về từ rất nhiều năm về trước
Nụ cười nàng có thể làm tan chảy băng giá mùa đông trên mặt kính
Có những khoảnh khắc vốn dĩ chẳng bao giờ được định sẵn để kéo dài mãi mãi
[Chorus]
Nhưng chúng tôi đã khiêu vũ cùng nhau cho đến khi bình minh lên
Hai kẻ xa lạ cùng hòa vào một trò chơi không tên
Tiếng kèn saxophone nỉ non êm ái và trầm lắng
Và chẳng một ai trong hai chúng tôi muốn rời bước ra đi
[Solo]
[Verse]
Cả thành phố đã say ngủ nhưng chúng tôi vẫn tỉnh giấc
Sẻ chia những bí mật vì nhau trong đêm thâu
Ngày mai rồi chúng tôi sẽ lại trở thành hai người xa lạ
Nhưng đêm nay chúng tôi còn hơn cả những người bạn cũ lâu năm
[Chorus]
Và chúng tôi đã khiêu vũ cùng nhau cho đến khi bình minh lên
Hai kẻ xa lạ cùng hòa vào một trò chơi không tên
Tiếng kèn saxophone nỉ non êm ái và trầm lắng
Và chẳng một ai trong hai chúng tôi muốn rời bước ra đi
[Outro]
```
---
## Các Mẫu Thuần Nhạc Cụ (Instrumental-Only Templates)
### Nhạc cụ Điện ảnh (Cinematic Instrumental)
```
[Intro]
[Inst]
(Tiếng piano nhẹ nhàng, dàn dây bắt đầu dâng cao)
[Build Up]
(Toàn bộ dàn nhạc giao hưởng dâng trào mạnh mẽ)
[Inst]
(Bộ đồng và bộ gõ vang lên khúc khải hoàn)
[Interlude]
(Bộ gỗ dịu dàng, mang sắc thái suy tư)
[Build Up]
(Tiếng trống định âm timpani dồn dập, sự căng thẳng tăng dần)
[Inst]
(Cao trào giao hưởng toàn diện)
[Outro]
(Dàn dây nhỏ dần, khép lại trong sự bình yên)
```
### Trình diễn Độc tấu Guitar (Guitar Solo Showcase)
```
[Intro]
[Inst]
(Nhịp điệu ăn ý giữa guitar đệm và bass)
[Solo]
(Giai điệu từ guitar lead dẫn dắt)
[Inst]
(Cả ban nhạc cùng hòa vào nhịp groove)
[Solo]
(Đoạn độc tấu guitar kéo dài, đẩy cường độ tăng dần)
[Break]
[Solo]
(Đoạn độc tấu guitar cuối cùng, chạm đỉnh cao cảm xúc)
[Outro]
```
### Nhạc Nền Không Gian / Khí Quyển (Ambient / Atmospheric)
```
[Intro]
[Inst]
(Âm thanh synth pad thanh thoát, biến chuyển chậm rãi)
[Transition]
[Inst]
(Các lớp âm thanh đan xen, bộ gõ điểm xuyết tinh tế)
[Interlude]
(Tối giản, không gian mở rộng mênh mông)
[Build Up]
(Cường độ mạnh dần lên từng chút một)
[Inst]
(Làn sóng âm thanh bao trùm toàn bộ không gian)
[Outro]
(Tan biến chậm rãi vào sự tĩnh lặng)
```