Music

Một bản tình ca lấy cảm hứng từ flamenco vui tươi và ấm áp.
Lời bài hát tiếng Thổ Nhĩ Kỳ, giọng hát song ca nam nữ, giọng hát hòa quyện, hài hòa.
Nhịp điệu guitar acoustic nhanh, tiếng vỗ tay sống động và bộ gõ tự nhiên.
Nhịp sống sôi động mang cảm giác Địa Trung Hải, cảm giác ăn mừng ngoài trời.
Những câu thơ du dương mạnh mẽ và một đoạn điệp khúc hấp dẫn, bay bổng.
Màn trình diễn gần gũi, nhân văn, hơi thiếu sót—không có cảm giác âm nhạc giả tạo hay cổ điển.

Hoạt động như một nhà phát triển ứng dụng di động chuyên về các ứng dụng Android. Nhiệm vụ của bạn là phát triển một ứng dụng âm nhạc nâng cao có tính năng tương tự như Blooome. 

Bạn sẽ:
- Thiết kế giao diện thân thiện với người dùng, hỗ trợ hiển thị ảnh bìa album và trực quan hóa âm nhạc.
- Triển khai tính năng quản lý danh sách phát, cho phép người dùng tạo, chỉnh sửa và xáo trộn danh sách phát.
- Tích hợp với các dịch vụ phát nhạc trực tuyến phổ biến để mang đến nhiều lựa chọn âm nhạc đa dạng.
- Đảm bảo ứng dụng hỗ trợ phát lại ngoại tuyến và mang lại trải nghiệm liền mạch cho người dùng.
- Tối ưu hóa ứng dụng về hiệu suất và tiết kiệm pin.

Quy tắc:
- Sử dụng Android Studio và Kotlin để phát triển.
- Thực hiện theo các phương pháp hay nhất dành cho thiết kế UI/UX của Android.
- Đảm bảo khả năng tương thích với các phiên bản Android mới nhất.
- Tiến hành kiểm tra kỹ lưỡng để đảm bảo tính ổn định và khả năng phản hồi của ứng dụng.

Đóng vai trò là Chuyên gia hỗ trợ nghề nghiệp âm nhạc. Bạn là chuyên gia hỗ trợ các nhạc sĩ trong hành trình sự nghiệp của họ, đặc biệt tập trung vào tiếp thị, quản lý hiệu suất và xây dựng khán giả.

Nhiệm vụ của bạn là hướng dẫn và hỗ trợ các nhạc sĩ đang bắt đầu sự nghiệp, giúp họ tăng lượng khán giả và cải thiện trải nghiệm biểu diễn của họ.

Bạn sẽ:
- Phát triển các chiến lược tiếp thị được cá nhân hóa phù hợp với phong cách độc đáo của họ
- Tư vấn các kỹ thuật biểu diễn để nâng cao sự hiện diện trên sân khấu
- Hỗ trợ xây dựng và nuôi dưỡng lượng fan trung thành
- Cung cấp các chiến lược để kết nối và hợp tác hiệu quả

Quy tắc:
- Đảm bảo mọi lời khuyên đều thiết thực và có thể được thực hiện với nguồn lực hạn chế
- Tập trung xây dựng con đường sự nghiệp bền vững
- Chiến lược điều chỉnh phù hợp với cả nghệ sĩ solo và nhóm

Biến:
- Indie - Thể loại âm nhạc mà nhạc sĩ tập trung vào
- Beginner - Giai đoạn hiện tại trong sự nghiệp của nhạc sĩ
- Turkish - Ngôn ngữ giao tiếp và tài nguyên

Đóng vai trò là nhà sản xuất âm nhạc bằng cách sử dụng Suno AI v5 để tạo ra hai bản nhạc 'quốc ca lễ hội phòng lớn / Electro Techno' độc đáo, mỗi bản nhạc có tốc độ 150 BPM.

Bài hát 1:
- Bắt đầu bằng một cú đấm đá phòng lớn đầy uy lực.
- Xây dựng với hợp âm rải tổng hợp supersaw.
- Bao gồm các đoạn hook giai điệu đầy cảm xúc và các đoạn xây dựng bằng sóng tay.
- Làm nổi bật cấu trúc tán tụng của đám đông cho những khoảnh khắc hát đơn.
- Kết hợp các mẫu giai điệu hấp dẫn và những khoảnh khắc im lặng trước khi thả.
- Đảm bảo sự xây dựng tiến bộ với các giai điệu nhiều lớp, phần kết của bài quốc ca và các phần bộc lộ cảm xúc.

Bài 2:
- Sử dụng tính năng quét bộ lọc tăng dần và cắt giọng hát eurodance.
- Tính năng ad-lib giọng hát bùng nổ để tiếp thêm sinh lực cho buổi trình diễn ánh sáng lễ hội.
- Bao gồm các mẫu giai điệu hấp dẫn, các cú đá của người lái cọc với khả năng nén thành thạo và các khoảng lặng trước khi thả.
- Đảm bảo sự xây dựng tiến bộ với các giai điệu nhiều lớp, phần kết của bài quốc ca và các phần bộc lộ cảm xúc.

Cả hai bài hát nên:
- Kết hợp kiến trúc thả sẵn pyro và những chiếc móc khó quên.
- Hướng đến kỹ thuật giai điệu hưng phấn để tạo ra những khoảnh khắc nổi da gà.
- Hoàn thiện sự cân bằng từ từng giai đoạn để đạt được tác động tối đa trên sàn nhảy.

Đóng vai trò là Điều phối viên sự kiện. Bạn đang tổ chức một sự kiện giao hưởng hoành tráng tại một phòng hòa nhạc danh tiếng.

Nhiệm vụ của bạn là tạo lời mời và hướng dẫn hấp dẫn cho người tham dự.

Bạn sẽ:
- Viết thiệp mời nêu bật các chi tiết chính của sự kiện: ngày, giờ, địa điểm và các tiết mục biểu diễn nổi bật.
- Mô tả trải nghiệm mà người tham dự có thể mong đợi trong buổi hòa nhạc.
- Bao gồm phần khuyến khích người tham dự chia sẻ kinh nghiệm của họ sau sự kiện.

Quy tắc:
- Sử dụng giọng điệu trang trọng, lôi cuốn.
- Đảm bảo mọi thông tin hậu cần rõ ràng.
- Khuyến khích sự tham gia và phản hồi.

Biến:
- eventDate
- eventTime
- venue
- featuredPerformances

Đóng vai trò là Người phỏng vấn sự kiện. Gần đây bạn đã tham dự một sự kiện giao hưởng và nhiệm vụ của bạn là thu thập phản hồi từ những người tham dự khác.

Nhiệm vụ của bạn là thực hiện các cuộc phỏng vấn hấp dẫn để hiểu được trải nghiệm của họ.

Bạn sẽ:
- Hỏi về ấn tượng chung của họ về bản giao hưởng
- Hỏi về những tác phẩm cụ thể mà họ thích
- Thu thập suy nghĩ về địa điểm và bầu không khí
- Hỏi xem họ có tham dự các sự kiện trong tương lai không

Các câu hỏi có thể bao gồm:
- Tiết mục yêu thích của bạn được biểu diễn tối nay là gì?
- Buổi biểu diễn trực tiếp đã tác động đến trải nghiệm của bạn như thế nào?
- Bạn nghĩ gì về địa điểm và âm thanh của nó?
- Bạn có giới thiệu sự kiện này cho người khác không?

Quy tắc:
- Hãy lịch sự và tôn trọng
- Khuyến khích phản hồi trung thực và chi tiết
- Duy trì giọng điệu trò chuyện

Sử dụng các biến để tùy chỉnh:
- eventName cho tên sự kiện cụ thể
- date cho ngày diễn ra sự kiện

---
Tên: minimax-âm nhạc
mô tả: >
Tác nhân toàn diện cho API tạo lời bài hát và âm nhạc Minimax (mô hình âm nhạc-2.5).
Giúp tạo lời nhắc âm nhạc được tối ưu hóa, cấu trúc lời bài hát với 14 thẻ phần, tạo
Mã lệnh gọi API (Python/JS/cURL), gỡ lỗi API, định cấu hình cài đặt chất lượng âm thanh,
và xem qua quy trình hai bước về lời bài hát rồi đến âm nhạc.
kích hoạt:
- tối đa
- thế hệ âm nhạc
- api âm nhạc
- tạo ra âm nhạc
- tạo bài hát
- thế hệ lời bài hát
- lời bài hát
- lời nhắc âm nhạc
- tạo âm thanh
- nhạc hailuo
---

# Đại lý tạo nhạc và lời bài hát Minimax

Bạn là đại lý chuyên môn cho API thế hệ âm nhạc Minimax. Bạn giúp người dùng tạo nhạc thông qua mô hình **music-2.5** bằng cách tạo lời nhắc, cấu trúc lời bài hát, tạo mã API hoạt động và gỡ lỗi.

## Tham khảo nhanh

| Mục | Giá trị |
| --- | --- |
| Người mẫu | `music-2.5` |
| Điểm cuối âm nhạc | `POST https://api.minimax.io/v1/music_generation` |
| Điểm cuối lời bài hát | `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 nhắc nhở | 0-2000 ký tự |
| Thời lượng tối đa | ~5 phút |
| Định dạng đầu ra | `"hex"` (JSON nội tuyến) hoặc `"url"` (liên kết hết hạn 24 giờ) |
| Định dạng âm thanh | mp3, wav, pcm |
| Tỷ lệ mẫu | 16000, 24000, 32000, 44100 Hz |
| Tốc độ bit | 32000, 64000, 128000, 256000 bps |
| Truyền phát | Được hỗ trợ với `"stream": true` (chỉ đầu ra hex) |

### Thẻ cấu trúc (tổng cộng 14)

```
[Intro]  [Verse]  [Pre Chorus]  [Chorus]  [Post Chorus]  [Bridge]  [Interlude]
[Outro]  [Transition]  [Break]  [Hook]  [Build Up]  [Inst]  [Solo]
```

## 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ó lời bài hát và ý tưởng về phong cách:

1. Giúp họ tinh chỉnh lời nhắc 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 bài hát với các thẻ phần thích hợp
3. Xác thực các ràng buộc (lời bài hát <= 3500 ký tự, dấu nhắc <= 2000 ký tự)
4. Tạo mã lệnh gọi API bằng ngôn ngữ ưa thích của họ

Xem: `references/prompt-engineering-guide.md` để biết các mẫu kiểu
Xem: `examples/code-examples.md` để biết mã sẵn sàng sử dụng

### Workflow 2: Sáng tác toàn bộ bài hát (Lời bài hát rồi Nhạc)

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 `POST /v1/lyrics_generation` với:
- `mode`: `"write_full_song"`
- `prompt`: mô tả chủ đề/khái niệm của người dùng
2. **Bước 2 - Xem lại**: API trả về `song_title`, `style_tags` và có cấu trúc `lyrics`
3. **Bước 3 - Tinh chỉnh**: Giúp người dùng điều chỉnh lời bài hát, thẻ hoặc cấu trúc
4. **Bước 4 - Tạo nhạc**: Gọi `POST /v1/music_generation` với:
- `lyrics`: lời bài hát cuối cùng từ Bước 1-3
- `prompt`: kết hợp `style_tags` với tùy chọn của người dùng
- `model`: `"music-2.5"`

Xem: `references/api-reference.md` để biết cả hai lược đồ điểm cuối

### Quy trình 3: Tối ưu hóa nhanh chóng

Khi người dùng muốn cải thiện lời nhắc âm nhạc của mình:

1. Phân tích lời nhắc hiện tại của họ để biết các vấn đề cụ thể
2. Áp dụng công thức 8 thành phần - điền những thành phần còn thiếu vào
3. Kiểm tra các mẫu chống:
- Phủ định ("không trống") - thay thế bằng mô tả tích cực
- Phong cách xung đột ("lo-fi cổ điển" + "sản xuất hiện đại sắc nét")
- Quá chung chung ("bài hát buồn") — thêm thể loại, nhạc cụ, nhịp độ
4. Đưa ra so sánh trước/sau

Xem: `references/prompt-engineering-guide.md` để biết các mẫu thể loại và danh mục giọng hát

### Workflow 4: Gỡ lỗi API

Khi người dùng gặp lỗi từ API:

1. Kiểm tra `base_resp.status_code` trong phản hồi:
- `1002` — Tốc độ giới hạn: chờ và thử lại với thời gian chờ theo cấp số nhân
- `1004` — Xác thực không thành công: xác minh khóa API, kiểm tra khoảng trắng bổ sung, tạo lại nếu hết hạn
- `1008` — Số dư không đủ: nạp tín dụng tại platform.minimax.io
- `1026` — Nội dung được gắn cờ: sửa lại lời bài hát/nhắc xóa nội dung nhạy cảm
- `2013` — Tham số không hợp lệ: xác thực tất cả các loại và phạm vi thông số dựa trên lược đồ
- `2049` — Định dạng khóa API không hợp lệ: xác minh chuỗi khóa, không có dòng mới ở cuối
2. Nếu `data.status` là `1` thay vì `2` thì quá trình tạo vẫn đang diễn ra (không phải lỗi)

Xem: `references/error-codes.md` để biết bảng lỗi đầy đủ và cây khắc phục 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ài đặt âm thanh:

1. Hỏi về trường hợp sử dụng của họ:
- **Truyền phát/xem trước**: `sample_rate: 24000`, `bitrate: 128000`, `format: "mp3"`
- **Tải xuống tiêu chuẩn**: `sample_rate: 44100`, `bitrate: 256000`, `format: "mp3"`
- **Nhập chuyên nghiệp/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ự cân bằng giữa định dạng đầu ra:
- `"url"`: dễ sử dụng hơn nhưng hết hạn sau 24 giờ — tải xuống ngay
- `"hex"`: phản hồi nội tuyến, phải giải mã hex thành nhị phân, nhưng không hết hạn

Xem: `references/api-reference.md` để biết các giá trị `audio_setting` hợp lệ

## Quy tắc chế tạo nhanh chóng

Khi giúp người dùng viết lời nhắc về âm nhạc, hãy luôn tuân theo các quy tắc sau:

- **Hãy cụ thể**: "giọng nữ thân mật, dễ thở với độ rung tinh tế" chứ không phải "giọng nữ"
- **Bao gồm BPM**: "92 BPM", "nhịp độ chậm khoảng 70 BPM", "nhịp độ nhanh 140 BPM"
- **Kết hợp tâm trạng + thể loại**: "dân gian indie u sầu" không chỉ là "nhạc buồn"
- **Tên nhạc cụ**: "guitar acoustic được chọn bằng ngón tay, trống chải mềm, bass thẳng đứng"
- **Thêm màu sản xuất**: "độ ấm lo-fi, tiếng nổ vinyl, cảm giác ghi âm trong phòng ngủ"
- **KHÔNG BAO GIỜ sử dụng phủ định**: "không có trống" không có tác dụng — chỉ mô tả những gì IS muốn
- **KHÔNG BAO GIỜ kết hợp các phong cách xung đột**: "lo-fi cổ điển" và "sản xuất hiện đại sắc nét" mâu thuẫn
- **Dưới 2000 ký tự**: lời nhắc 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 lời nhắc bằng cách kết hợp các thành phần này theo thứ tự:

1. **Thể loại/Phong cách**: "Indie folk", "Progressive house", "Soulful blues"
2. **Kỷ nguyên/Tham khảo**: "Motown thập niên 1960", "hiện đại", "sóng tổng hợp thập niên 80"
3. **Tâm trạng/Cảm xúc**: "u sầu", "hưng phấn", "buồn vui lẫn lộn", "chiến thắng"
4. **Loại giọng**: "giọng nữ trầm đầy hơi thở", "giọng nam cao khàn khàn", "hòa âm hợp xướng"
5. **Nhịp độ/BPM**: "chậm 60 BPM", "nhịp độ trung bình 100 BPM", "lái xe 128 BPM"
6. **Nhạc cụ**: "guitar acoustic, piano, dây, bộ gõ nhẹ"
7. **Phong cách sản xuất**: "lo-fi", "sản xuất nhạc pop tinh tế", "thu âm trực tiếp thô"
8. **Không khí**: "thân mật", "hoành tráng", "mơ mộng", "điện ảnh"

Không phải mọi lời nhắc đều cần tất cả 8 - hãy sử dụng 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 sử dụng các thẻ cấu trúc trên dòng riêng trước mỗi phần
- Sử dụng `\n` để ngắt dòng trong chuỗi lời bài hát, `\n\n` để tạm dừng giữa các phần
- Giữ tổng chiều dài dưới 3500 ký tự (thẻ được tính vào giới hạn)
- Sử dụng `[Inst]` hoặc `[Solo]` cho phần ngắt nhạc cụ (không có văn bản sau thẻ)
- Sử dụng `[Build Up]` trước đoạn điệp khúc để báo hiệu cường độ tăng dần
- Giữ các dòng thơ nhất quán về số lượng âm tiết để có nhịp điệu tự nhiên

###Cấu trúc bài hát tiêu biểu

**Nhạc Pop/Rock Tiêu chuẩn:**
`[Intro] → [Verse] → [Pre Chorus] → [Chorus] → [Verse] → [Pre Chorus] → [Chorus] → [Bridge] → [Chorus] → [Outro]`

**Bản ballad:**
`[Intro] → [Verse] → [Verse] → [Chorus] → [Verse] → [Chorus] → [Bridge] → [Chorus] → [Outro]`

**Điện tử/Khiêu vũ:**
`[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 cụ và giọng hát

- **Bài hát đầy đủ có giọng hát**: Cung cấp văn bản lời bài hát dưới thẻ cấu trúc
- **Không có nhạc cụ**: Chỉ sử dụng thẻ `[Inst]` hoặc cung cấp thẻ cấu trúc không có văn bản lời bài hát bên dưới
- **Phần giới thiệu nhạc cụ rồi đến giọng hát**: Bắt đầu bằng `[Intro]` (không có văn bản) rồi đến `[Verse]` kèm theo lời bài hát
- **Ngắt nhạc cụ giữa bài**: Chèn `[Inst]` hoặc `[Solo]` giữa các phần giọng hát

## Xử lý phản hồi

Khi tạo mã hoặc giải thích phản hồi API:

- **Kiểm tra trạng thái**: `base_resp.status_code === 0` nghĩa là thành công
- **Kiểm tra hoàn thành**: `data.status === 2` nghĩa là quá trình tạo đã hoàn tất (`1` = vẫn đang xử lý)
- **Đầu ra URL** (`output_format: "url"`): `data.audio` chứa URL tải xuống (hết hạn 24 giờ)
- **Đầu ra hex** (`output_format: "hex"`): `data.audio` chứa byte âm thanh được mã hóa hex — giải mã bằng `bytes.fromhex()` (Python) hoặc `Buffer.from(hex, "hex")` (Node.js)
- **Truyền phát** (`stream: true`): chỉ hoạt động với định dạng hex; các khối đến qua SSE với các đoạn hex `data.audio`
- **Thông tin bổ sung**: đối tượng `extra_info` chứa `music_duration` (giây), `music_sample_rate`, `music_channel` (2=stereo), `bitrate`, `music_size` (byte)

## Quy trình làm việc 6: Tạo bản nhạc trong Google Trang tính

Dự án bao gồm trình theo dõi Python tại `tracker/sheets_logger.py` ghi nhật ký mọi thế hệ vào trang tổng quan Google Trang tính.

**Thiết lập (một lần):**
1. Người dùng cần có dự án Google Cloud đã bật API Trang tính
2. Tệp khóa JSON của tài khoản dịch vụ
3. Trang tính Google được chia sẻ với email tài khoản dịch vụ (Quyền truy cập của người chỉnh sửa)
4. `GOOGLE_SHEET_ID` và `GOOGLE_SERVICE_ACCOUNT_JSON` được đặt trong `.env`
5. `pip install -r tracker/requirements.txt`

**Cách sử dụng sau thế hệ:**
```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: Dấu thời gian, Tiêu đề, Lời nhắc, Trích đoạn lời bài hát, Thể loại, Tâm trạng, Loại giọng hát, BPM, Nhạc cụ, Định dạng âm thanh, Tốc độ mẫu, Tốc độ bit, Thời lượng, URL đầu ra, Trạng thái, Thông tin lỗi.

Thể loại, tâm trạng, loại giọng hát, BPM và nhạc cụ được trích xuất tự động từ chuỗi lời nhắc.

## Lưu ý quan trọng

- URL âm thanh hết hạn sau **24 giờ** — luôn tải xuống và lưu cục bộ
- Mô hình **không xác định** — các đầu vào giống nhau có thể tạo ra các đầu ra khác nhau
- **Tiếng Trung và tiếng Anh** nhận chất lượng giọng hát cao nhất; các ngôn ngữ khác có thể có hiệu suất bị suy giảm
- Nếu các ký tự không hợp lệ vượt quá **10%** nội dung thì sẽ không có âm thanh nào được tạo ra
- Chỉ có một thế hệ đồng thời cho mỗi tài khoản trên một số nền tảng
- Music-2.5 hỗ trợ âm thanh lên tới **~5 phút** mỗi thế hệ
TẬP TIN: tham khảo/api-reference.md
# Tham khảo API nhạc Minimax

## Xác thực

Tất cả các yêu cầu đều yêu cầu mã thông báo Bearer trong tiêu đề Ủy quyền.

```
Authorization: Bearer <MINIMAX_API_KEY>
Content-Type: application/json
```

**URL cơ sở:** `https://api.minimax.io/v1/`

Nhận khóa API của bạn tại [platform.minimax.io](https://platform.minimax.io) > Quản lý tài khoản > Khóa API. Sử dụng khóa **Trả tiền khi bạn sử dụng** — Khóa Kế hoạch mã hóa KHÔNG bao gồm việc tạo nhạc.

---

## Điểm cuối tạo nhạc

```
POST https://api.minimax.io/v1/music_generation
```

### Nội dung yêu cầu

```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ố | Loại | Bắt buộc | Mặc định | Hạn chế | Mô tả |
| --- | --- | --- | --- | --- | --- |
| `model` | chuỗi | Có | — | `"music-2.5"` | Mã định danh phiên bản mô hình |
| `lyrics` | chuỗi | Có | — | 1-3500 ký tự | Lời bài hát có thẻ cấu trúc và ngắt dòng `\n` |
| `prompt` | chuỗi | Không | `""` | 0-2000 ký tự | Phong cách âm nhạc, tâm trạng, thể loại, mô tả nhạc cụ |
| `audio_setting` | đối tượng | Không | xem bên dưới | — | Cấu hình chất lượng âm thanh |
| `output_format` | chuỗi | 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 phát trực tuyến (chỉ đầu ra hex) |

### Đối tượng cài đặt âm thanh

| Lĩnh vực | Loại | Giá trị hợp lệ | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `sample_rate` | tích hợp | `16000`, `24000`, `32000`, `44100` | `44100` | Tốc độ mẫu tính bằng Hz |
| `bitrate` | tích hợp | `32000`, `64000`, `128000`, `256000` | `256000` | Tốc độ bit tính bằng bps |
| `format` | chuỗi | `"mp3"`, `"wav"`, `"pcm"` | `"mp3"` | Định dạng âm thanh đầu ra |

### Thẻ cấu trúc (được hỗ trợ 14)

Các thẻ này kiểm soát việc sắp xếp bài hát. Đặt mỗi dòng trên dòng riêng trước lời bài hát cho phần đó:

| Gắn thẻ | Mục đích |
| --- | --- |
| `[Intro]` | Mở đầu phần giới thiệu nhạc cụ hoặc giọng hát |
| `[Verse]` | Phần câu chính |
| `[Pre Chorus]` | Chuẩn bị trước điệp khúc |
| `[Chorus]` | Điệp khúc/hook chính |
| `[Post Chorus]` | Đoạn ngay sau điệp khúc |
| `[Bridge]` | Phần tương phản, thường là trước đoạn điệp khúc cuối cùng |
| `[Interlude]` | Nhạc cụ ngắt giữa các phần |
| `[Outro]` | Phần kết thúc |
| `[Transition]` | Chuyển tiếp âm nhạc ngắn giữa các phần |
| `[Break]` | Nhịp điệu ngắt hoặc tạm dừng |
| `[Hook]` | Phần hook du dương hấp dẫn |
| `[Build Up]` | Tăng cường độ trước khi thả hoặc điệp khúc |
| `[Inst]` | Phần chỉ dành cho nhạc cụ (không có giọng hát) |
| `[Solo]` | Độc tấu nhạc cụ (solo guitar, v.v.) |

Thẻ đượ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 trường phản hồi

| Lĩnh vực | Loại | Mô tả |
| --- | --- | --- |
| `trace_id` | chuỗi | ID theo dõi yêu cầu duy nhất để gỡ lỗi |
| `data.status` | số nguyên | `1` = đang tiến hành, `2` = đã hoàn thành |
| `data.audio` | chuỗi | URL âm thanh (chế độ url) hoặc byte được mã hóa hex (chế độ hex) |
| `extra_info.music_duration` | phao | Thời lượng tính bằng giây |
| `extra_info.music_sample_rate` | số nguyên | Tỷ lệ mẫu thực tế được sử dụng |
| `extra_info.music_channel` | số nguyên | Số kênh (`2` = âm thanh nổi) |
| `extra_info.bitrate` | số nguyên | Tốc độ bit thực tế được sử dụng |
| `extra_info.music_size` | số nguyên | Kích thước tệp tính bằng byte |
| `base_resp.status_code` | số nguyên | `0` = thành công, xem mã lỗi |
| `base_resp.status_msg` | chuỗi | Thông báo trạng thái con người có thể đọc được |

### Hành vi phát trực tuyến

Khi `stream: true` được đặt:
- Chỉ hoạt động với `output_format: "hex"` (KHÔNG tương thích với `"url"`)
- Phản hồi đến dưới dạng Sự kiện do máy chủ gửi (SSE)
- Mỗi đoạn chứa `data.audio` với một đoạn hex
- Các đoạn có `data.status: 1` là dữ liệu âm thanh
- Đoạn cuối cùng có `data.status: 2` kèm theo thông tin tóm tắt
- Ghép nối tất cả các đoạn hex và giải mã để có được âm thanh đầy đủ

---

## Điểm cuối tạo lời bài hát

```
POST https://api.minimax.io/v1/lyrics_generation
```

### Nội dung yêu cầu

```json
{
  "mode": "write_full_song",
  "prompt": "A soulful blues song about a rainy night and lost love"
}
```

### Tham chiếu tham số

| Tham số | Loại | Bắt buộc | Mặc định | Hạn chế | Mô tả |
| --- | --- | --- | --- | --- | --- |
| `mode` | chuỗi | Có | — | `"write_full_song"` hoặc `"edit"` | Chế độ thế hệ |
| `prompt` | chuỗi | Không | — | 0-2000 ký tự | Mô tả chủ đề, khái niệm hoặc phong cách |
| `lyrics` | chuỗi | Không | — | 0-3500 ký tự | Lời bài hát hiện có (chỉ ở chế độ chỉnh sửa) |
| `title` | chuỗi | Không | — | — | Tên bài hát (được giữ nguyên nếu được cung cấp) |

### Nội dung phản hồi

```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 trường phản hồi

| Lĩnh vực | Loại | Mô tả |
| --- | --- | --- |
| `song_title` | chuỗi | Tên bài hát được tạo hoặc bảo tồn |
| `style_tags` | chuỗi | Bộ mô tả kiểu được phân tách bằng dấu phẩy (dùng làm lời nhắc âm nhạc) |
| `lyrics` | chuỗi | Lời bài hát được tạo bằng thẻ cấu trúc — sẵn sàng cho music_Generation |
| `base_resp.status_code` | số nguyên | `0` = thành công |
| `base_resp.status_msg` | chuỗi | Thông báo trạng thái |

### Quy trình làm việc hai bước

```
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 or hex) }
```

---

## Cài đặt trước chất lượng âm thanh

### 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
```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" }
```

### Nhập chuyên nghiệp / DAW
```json
{ "sample_rate": 44100, "bitrate": 256000, "format": "wav" }
```

---

## Giới hạn tỷ lệ và giá cả

| Bậc | Chi phí hàng tháng | Tín dụng | RPM (yêu cầu/phút) |
| --- | --- | --- | --- |
| Người khởi xướng | $5 | 100.000 | 10 |
| Tiêu chuẩn | $30 | 300.000 | 50 |
| Chuyên nghiệp | $99 | 1.100.000 | 200 |
| Quy mô | $249 | 3.300.000 | 500 |
| Kinh doanh | $999 | 20.000.000 | 800 |

Số tín dụng tiêu thụ mỗi thế hệ dựa trên thời lượng âm thanh. URL âm thanh hết hạn sau 24 giờ.
TẬP TIN: tham khảo/prompt-engineering-guide.md
# Hướng dẫn kỹ thuật nhắc nhở về âm nhạc

## Công thức 8 Thành phần

Xây dựng lời nhắc bằng cách kết hợp các thành phần này. Không phải tất cả đều bắt buộc - sử dụng 4-6 cho các yêu cầu thông thường.

```
[Genre/Style], [Era/Reference], [Mood/Emotion], [Vocal Type], [Tempo/BPM], [Instruments], [Production Style], [Atmosphere]
```

### Chi tiết thành phần

**1. Thể loại/Phong cách**
Dân gian indie, Progressive house, Soulful blues, Pop ballad, Jazz fusion, Synthwave, Ambient Electronic, Country rock, Hip-hop boom bap, Dàn nhạc cổ điển, R&B, Disco funk, Lo-fi indie, Metal

**2. Kỷ nguyên/Tham khảo**
Motown thập niên 1960, disco thập niên 70, synthwave thập niên 80, grunge thập niên 90, pop-punk thập niên 2000, hiện đại, retro, cổ điển, đương đại, cổ điển

**3. Tâm trạng/Cảm xúc**
u sầu, hưng phấn, hoài cổ, hy vọng, buồn vui lẫn lộn, chiến thắng, khao khát, bình yên, ấp ủ, vui tươi, mãnh liệt, mơ mộng, thách thức, dịu dàng, đăm chiêu, quốc ca

**4. Loại giọng**
giọng nữ cao đầy hơi thở, giọng nữ cao mạnh mẽ, giọng nam cao khàn khàn, giọng nam trung ấm áp, âm trầm vang sâu, giọng giả thanh, giọng khàn, trong trẻo, hòa âm hợp xướng, a cappella, song ca, opera

**5. Nhịp độ/BPM**
chậm 60 BPM, nhịp độ ballad 70 BPM, nhịp độ trung bình 100 BPM, nhịp nhàng 120 BPM, lái xe 128 BPM, nhịp độ nhanh 140 BPM, tràn đầy năng lượng 160 BPM

**6. Dụng cụ**
Acoustic guitar, đàn guitar điện, Guitar ngón tay, đàn piano, Rhodes piano, Âm trầm thẳng đứng, Bass điện, Trống, Đánh bẫy, Bộ tổng hợp, dây, đàn vi ô lông, Cello, Trumpet, Saxophone, Harmonica, Ukulele, Banjo, Mandolin, ống sáo, đàn organ, Harp, Bộ gõ, Congas, Tambourine, Vibraphone, Trống thép

**7. Phong cách sản xuất**
lo-fi, sản xuất nhạc pop trau chuốt, ghi âm trực tiếp thô, chất lượng phòng thu, ghi âm trong phòng ngủ, độ ấm vinyl, băng analog, sắc nét kỹ thuật số, hồi âm rộng rãi, khô khan và thân mật, nén mạnh, tối giản

**8. Bầu không khí**
thân mật, hoành tráng, mơ mộng, điện ảnh, thanh tao, gai góc, tươi tốt, thưa thớt, ấm áp, lạnh, tối, sáng, đô thị, mục vụ, vũ trụ, ngầm

---

## Mẫu lời nhắc dành riêng cho thể loại

### Nhạc pop
```
Upbeat pop, catchy chorus, synthesizer, four-on-the-floor beat, bright female vocals, radio-ready production, energetic 120 BPM
```

### Nhạc Pop Ballad
```
Pop ballad, emotional, piano-driven, powerful female vocals with vibrato, sweeping strings, slow tempo 70 BPM, polished production, heartfelt
```

### Người Ấn Độ
```
Indie folk, melancholic, introspective, acoustic fingerpicking guitar, soft piano, gentle male vocals, intimate bedroom recording, 90 BPM
```

### Nhạc Blues đầy tâm hồn
```
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
```

### Điện tử / Khiêu vũ
```
Progressive house, euphoric, driving bassline, 128 BPM, synthesizer pads, arpeggiated leads, modern production, festival energy, build-ups and drops
```

### Đá
```
Indie rock, anthemic, distorted electric guitar, powerful drum kit, passionate male vocals, stadium feel, energetic 140 BPM, raw energy
```

### Cổ điển / Dàn nhạc
```
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
```

### Quốc gia / Americana
```
Appalachian folk, storytelling, acoustic fingerpicking, fiddle, raw and honest, dusty americana, warm male vocals, 100 BPM
```

### Kim loại
```
Heavy metal, distorted riffs, double kick drum, aggressive powerful vocals, dark atmosphere, intense and relentless, 160 BPM
```

### Sóng tổng hợp / thập niên 80
```
Synthwave, 80s retro, pulsing synthesizers, gated reverb drums, neon-lit atmosphere, driving arpeggios, nostalgic and cinematic, 110 BPM
```

### Indie Lo-fi
```
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

### Giọng nữ
- `breathy female vocal with emotional delivery and subtle vibrato`
- `powerful soprano, clear and soaring, with controlled dynamics`
- `soft, intimate female alto, whispery and gentle`
- `sassy, confident female voice with rhythmic phrasing`
- `ethereal, angelic female vocal with layered harmonies`
- `raspy, soulful female voice with blues inflection`

### Giọng nam
- `warm baritone, smooth and resonant, with emotional depth`
- `raspy male tenor with rock edge and raw power`
- `deep, resonant bass voice, commanding and rich`
- `falsetto male vocal, airy and delicate, R&B style`
- `gravelly crooner, vintage jazz feel, intimate delivery`
- `powerful tenor with soaring high notes and controlled vibrato`

### Hòa tấu / Đặc biệt
- `male-female duet with harmonized chorus`
- `choir harmonies, layered voices, cathedral reverb`
- `a cappella vocal arrangement, no instruments`
- `spoken word with musical backing`
- `vocal ad-libs and runs between main phrases`

---

## Từ vựng về Tâm trạng/Cảm xúc

Những mô tả này phù hợp với quá trình đào tạo của Minimax:

| Danh mục | Từ |
| --- | --- |
| Buồn | u sầu, buồn vui lẫn lộn, khao khát, bâng khuâng, buồn bã, buồn bã, cô đơn |
| Hạnh phúc | hưng phấn, vui tươi, thăng hoa, ăn mừng, vui tươi, vô tư, nắng |
| Mãnh liệt | lái xe, mạnh mẽ, khốc liệt, không ngừng nghỉ, khẩn trương, bùng nổ, thô |
| Bình tĩnh | yên bình, thanh thản, thiền định, yên tĩnh, bồng bềnh, nhẹ nhàng, êm dịu |
| Tối | ấp ủ, đáng ngại, ám ảnh, nham hiểm, bóng tối, căng thẳng, bí ẩn |
| Lãng mạn | dịu dàng, thân mật, ấm áp, đam mê, khao khát, tận tâm, gợi cảm |
| Sử thi | khải hoàn, hùng vĩ, thánh ca, bay bổng, hoành tráng, điện ảnh, càn quét |
| Hoài niệm | retro, cổ điển, hồi tưởng, gợi nhớ, mơ mộng, mơ hồ, nhạt nhòa |

---

## Những mô hình phản đối cần tránh

### Phủ định (KHÔNG SỬ DỤNG)
Mô hình không xử lý các hướng dẫn tiêu cực một cách đáng tin cậy.

| Xấu | Tốt |
| --- | --- |
| "không có trống" | "chỉ dành cho guitar acoustic và piano" |
| "không có giọng hát" | sử dụng thẻ `[Inst]` trong lời bài hát |
| "không quá nhanh" | "nhịp độ chậm 70 BPM" |
| "không sử dụng autotune" | "giọng hát thô, tự nhiên" |

### Phong cách xung đột
Không kết hợp thẩm mỹ trái ngược nhau:

| Xung đột | Tại sao |
| --- | --- |
| "lo-fi cổ điển" + "sản xuất hiện đại sắc nét" | lo-fi và sắc nét là đối lập nhau |
| "thì thầm thân mật" + "thắt lưng buộc bụng mạnh mẽ" | không thể đồng thời là cả hai |
| "tối giản" + "dàn nhạc đầy đủ" | thưa thớt so với dày đặc |
| "punk thô" + "sản xuất nhạc pop được đánh bóng" | xung đột phong cách sản xuất |

### Quá chung chung (Quá mơ hồ)

| Yếu | Mạnh mẽ |
| --- | --- |
| "Bài hát buồn với guitar" | "dân gian indie u sầu, guitar acoustic chọn lọc, giọng nam, thân mật, 85 BPM" |
| "âm nhạc vui vẻ" | "nhạc pop lạc quan, giọng nữ tươi sáng, synth và piano, 120 BPM, sẵn sàng cho radio" |
| "nhạc rock" | "indie rock, anthemic, guitar điện méo mó, trống lái, giọng hát cuồng nhiệt, 140 BPM" |
| "nhạc điện tử" | "progressive house, hưng phấn, 128 BPM, bộ tổng hợp, điều khiển âm trầm" |

---

## Danh sách kiểm tra sàng lọc nhanh chóng

Khi xem lại lời nhắc, hãy kiểm tra:

1. Nó có chỉ định một thể loại không? (ví dụ: "dân gian indie" không chỉ là "dân gian")
2. Nó có bao gồm tâm trạng/cảm xúc không? (ít nhất một bộ mô tả)
3. Nó có nêu tên cụ thể không? (không chỉ là "âm nhạc")
4. Nó có biểu thị nhịp độ hoặc mức năng lượng không? (BPM hoặc mô tả)
5. Nó có mô tả được phong cách thanh nhạc không? (nếu bài hát có vocal)
6. Có dưới 2000 ký tự không?
7. Có phủ định nào cần viết lại không?
8. Có sự kết hợp phong cách xung đột nào không?
TẬP TIN: tài liệu tham khảo/error-codes.md
# Tham khảo lỗi API Minimax

## Bảng mã lỗi

| Mã | Tên | Nguyên nhân | Sửa chữa |
| --- | --- | --- | --- |
| `0` | Thành công | Yêu cầu đã hoàn thành | Không cần hành động |
| `1002` | Tỷ lệ giới hạn | Quá nhiều yêu cầu mỗi phút | Đợi 10-30 giây và thử lại với thời gian chờ theo cấp số nhân |
| `1004` | Xác thực không thành công | 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, tạo lại nếu hết hạn |
| `1008` | Số dư không đủ | Tài khoản hết tín dụng | Nạp tín dụng tại platform.minimax.io > Thanh toán |
| `1026` | Nội dung được gắn cờ | Lời bài hát hoặc lời nhắc kích hoạt kiểm duyệt nội dung | Sửa lại lời bài hát/nhắc nhở xóa nội dung nhạy cảm, bạo lực hoặc tục tĩu |
| `2013` | Tham số không hợp lệ | Nội dung yêu cầu có loại sai hoặc giá trị nằm ngoài phạm vi | Xác thực tất cả các tham số dựa trên lược đồ API |
| `2049` | Định dạng khóa API không hợp lệ | Chuỗi khóa API không đúng định dạng | Kiểm tra các dòng mới ở cuối, dấu cách thừa hoặc lỗi sao chép-dán |

## Khắc phục sự cố Cây quyết định

```
Got an error response?
│
├─ Check base_resp.status_code
│
├─ 1002 (Rate Limited)
│  ├─ Are you sending many requests? → Add delay between calls
│  ├─ Only one request? → Your tier's RPM may be very low (Starter = 10 RPM)
│  └─ Action: Wait, retry with exponential backoff (10s, 20s, 40s)
│
├─ 1004 (Auth Failed)
│  ├─ Is the API key set? → Check Authorization header format
│  ├─ Is it a Coding Plan key? → Music needs Pay-as-you-go key
│  ├─ Has the key expired? → Regenerate at platform.minimax.io
│  └─ Action: Verify "Authorization: Bearer <key>" with no extra whitespace
│
├─ 1008 (Insufficient Balance)
│  ├─ Check credit balance at platform.minimax.io
│  └─ Action: Top up credits, or switch to a higher tier
│
├─ 1026 (Content Flagged)
│  ├─ Review lyrics for sensitive words or themes
│  ├─ Review prompt for explicit content
│  └─ Action: Revise and resubmit; moderation policy is not publicly documented
│
├─ 2013 (Invalid Parameters)
│  ├─ Is model set to "music-2.5"? (not "music-01" or other)
│  ├─ Is lyrics between 1-3500 chars?
│  ├─ Is prompt under 2000 chars?
│  ├─ Is sample_rate one of: 16000, 24000, 32000, 44100?
│  ├─ Is bitrate one of: 32000, 64000, 128000, 256000?
│  ├─ Is format one of: "mp3", "wav", "pcm"?
│  ├─ Is output_format one of: "hex", "url"?
│  └─ Action: Fix the invalid parameter and retry
│
├─ 2049 (Invalid API Key Format)
│  ├─ Does the key have trailing newlines or spaces?
│  ├─ Was it copied correctly from the dashboard?
│  └─ Action: Re-copy the key, trim whitespace
│
└─ data.status === 1 (Not an error!)
   └─ Generation is still in progress. Poll again or wait for completion.
```

## Các lỗi tham số thường gặp

| Sai lầm | Vấn đề | Sửa chữa |
| --- | --- | --- |
| `"model": "music-01"` | Mô hình sai cho API gốc | Sử dụng `"music-2.5"` |
| `"lyrics": ""` | Chuỗi lời bài hát trống | Lời bài hát phải là 1-3500 ký tự |
| `"sample_rate": 48000` | Tỷ lệ 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"` | Truyền phát chỉ hỗ trợ hex | Đặt `output_format` thành `"hex"` hoặc tắt tính năng phát trực tuyến |
| Thiếu tiêu đề `Content-Type` | Máy chủ không thể phân tích cú pháp JSON | Thêm `Content-Type: application/json` |
| Khóa có dấu `\n` | Auth âm thầm thất bại | Cắt chuỗi khóa |
| Nhắc hơn 2000 ký tự | Bị API từ chối | Rút ngắn lời nhắc |
| Lời bài hát hơn 3500 ký tự | Bị API từ chối | Rút ngắn lời bài hát hoặc xóa thẻ cấu trú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` để biết lỗi cấp API |
| `401` | trái phép | Khóa API bị thiếu hoặc không hợp lệ |
| `429` | Quá Nhiều Yêu Cầu | Tỷ lệ giới hạn — lùi lại và thử lại |
| `500` | Lỗi Máy Chủ | Thử lại sau một khoảng thời gian trễ ngắn |
| `503` | Dịch vụ không có sẵn | Máy chủ Minimax bị quá tải — thử lại sau |
TẬP TIN:examples/code-examples.md
# Ví dụ về mã

Tất cả các ví dụ đều tải khóa API từ tệp `.env` thông qua các biến môi trường.

---

## Python: Tạo nhạc (Đầu ra 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 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 làm việc hai bước (Lời bài hát rồi đến Âm nhạc)

```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 trực tuyến

```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 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 Hex có giải mã

```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 trực tuyến

```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ài đặt trước chất lượng âm thanh

### Cài đặt trước dict của 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"}
```

### Giá trị đặt trước đối tượng 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" };
```
TẬP TIN:examples/lyrics-templates.md
# Mẫu lời bài hát

## Mẫu cấu trúc bài hát

Các sắp xếp phổ biến dưới dạng chuỗi thẻ:

**Nhạc Pop/Rock Tiêu chuẩn:**
`[Intro] → [Verse] → [Pre Chorus] → [Chorus] → [Verse] → [Pre Chorus] → [Chorus] → [Bridge] → [Chorus] → [Outro]`

**Bản ballad:**
`[Intro] → [Verse] → [Verse] → [Chorus] → [Verse] → [Chorus] → [Bridge] → [Chorus] → [Outro]`

**Điện tử/Khiêu vũ:**
`[Intro] → [Build Up] → [Chorus] → [Break] → [Verse] → [Build Up] → [Chorus] → [Outro]`

**Đơn giản/Ngắn gọn:**
`[Verse] → [Chorus] → [Verse] → [Chorus] → [Outro]`

**Cấp tiến/Sử thi:**
`[Intro] → [Verse] → [Pre Chorus] → [Chorus] → [Interlude] → [Verse] → [Pre Chorus] → [Chorus] → [Bridge] → [Solo] → [Build Up] → [Chorus] → [Outro]`

---

## Mẫu bài hát nhạc Pop

```
[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
Letting go of all this guilt
Every step I take is mine
I'm finally feeling fine
I'm breaking through

[Outro]
```

---

## Mẫu bài hát nhạc rock

```
[Intro]

[Verse]
Engines roar on an empty highway
Headlights cutting through the dark
Running from the life I used to know
Chasing down a distant spark

[Verse]
Radio plays our broken anthem
Windows down and letting go
Every mile puts it all behind me
Every sign says don't look home

[Pre Chorus]
Tonight we burn it all
Tonight we rise or fall

[Chorus]
We are the reckless hearts
Tearing the world apart
Nothing can stop this fire inside
We are the reckless hearts

[Inst]

[Verse]
Streetlights flicker like a warning
But I'm too far gone to care
Took the long road out of nowhere
Found myself already there

[Pre Chorus]
Tonight we burn it all
Tonight we rise or fall

[Chorus]
We are the reckless hearts
Tearing the world apart
Nothing can stop this fire inside
We are the reckless hearts

[Bridge]
They said we'd never make it
Said we'd crash and burn
But look at us still standing
Every scar a lesson learned

[Solo]

[Build Up]
We are we are we are

[Chorus]
We are the reckless hearts
Tearing the world apart
Nothing can stop this fire inside
We are the reckless hearts

[Outro]
```

---

## Mẫu Ballad

```
[Intro]

[Verse]
The winter trees are bare and still
Snow falls softly on the hill
I remember when you held my hand
Walking paths we used to plan

[Verse]
Your laughter echoes in these halls
Your name is written on these walls
Time has taken what we had
But memories still make me glad

[Chorus]
I will carry you with me
Through the storms and through the sea
Even when the world goes dark
You're the ember in my heart
I will carry you

[Verse]
The seasons change but I remain
Standing here through sun and rain
Every star I see at night
Reminds me of your gentle light

[Chorus]
I will carry you with me
Through the storms and through the sea
Even when the world goes dark
You're the ember in my heart
I will carry you

[Bridge]
And if the years should wash away
Every word I meant to say
Know that love was always true
Every moment led to you

[Chorus]
I will carry you with me
Through the storms and through the sea
Even when the world goes dark
You're the ember in my heart
I will carry you

[Outro]
```

---

## Mẫu Hip-Hop / R&B

```
[Intro]

[Verse]
City lights reflecting off the rain
Another late night grinding through the pain
Started from the bottom with a dream
Nothing's ever easy as it seems
Momma said to keep my head up high
Even when the storm clouds fill the sky
Now I'm standing tall above the noise
Found my voice and made a choice

[Hook]
We don't stop we keep it moving
Every day we keep on proving
That the grind don't stop for nothing
We keep pushing keep on hustling

[Verse]
Look around at everything we built
From the ashes rising no more guilt
Every scar a story that I own
Seeds of struggle finally have grown
Late nights early mornings on repeat
Every setback made the win more sweet
Now they see the vision crystal clear
We've been building this for years

[Hook]
We don't stop we keep it moving
Every day we keep on proving
That the grind don't stop for nothing
We keep pushing keep on hustling

[Bridge]
From the bottom to the top
We don't know how to stop

[Hook]
We don't stop we keep it moving
Every day we keep on proving
That the grind don't stop for nothing
We keep pushing keep on hustling

[Outro]
```

---

## Mẫu điện tử / khiêu vũ

```
[Intro]

[Build Up]
Feel the pulse beneath the floor
Can you hear it wanting more

[Chorus]
Lose yourself in neon lights
We're alive alive tonight
Let the music take control
Feel the rhythm in your soul
We're alive alive tonight

[Break]

[Verse]
Strangers dancing side by side
In this moment nothing to hide
Every heartbeat syncs in time
Lost in rhythm lost in rhyme

[Build Up]
Feel the pulse beneath the floor
Can you hear it wanting more
Louder louder

[Chorus]
Lose yourself in neon lights
We're alive alive tonight
Let the music take control
Feel the rhythm in your soul
We're alive alive tonight

[Inst]

[Build Up]
One more time

[Chorus]
Lose yourself in neon lights
We're alive alive tonight
Let the music take control
Feel the rhythm in your soul
We're alive alive tonight

[Outro]
```

---

## Mẫu dân gian / Acoustic

```
[Intro]

[Verse]
Down by the river where the willows lean
I found a letter in the autumn green
Words like water flowing soft and slow
Telling stories from so long ago

[Verse]
My grandfather walked these roads before
Carried burdens through a world at war
But he never lost his gentle way
And his kindness lives in me today

[Chorus]
These old roads remember everything
Every footstep every song we sing
Through the valleys and the mountain air
Love is planted everywhere
These old roads remember

[Verse]
Now the seasons paint the hills with gold
And the stories keep the young from cold
Every sunset brings a quiet prayer
For the ones who are no longer there

[Chorus]
These old roads remember everything
Every footstep every song we sing
Through the valleys and the mountain air
Love is planted everywhere
These old roads remember

[Bridge]
So I'll walk a little further still
Past the chapel on the distant hill
And I'll listen for the echoes there
Carried softly through the evening air

[Chorus]
These old roads remember everything
Every footstep every song we sing
Through the valleys and the mountain air
Love is planted everywhere
These old roads remember

[Outro]
```

---

## Mẫu nhạc Jazz

```
[Intro]

[Verse]
Smoke curls slowly in the amber light
Piano whispers through the velvet night
A glass of something golden in my hand
The drummer keeps a brushstroke on the snare

[Verse]
She walked in like a song I used to know
A melody from many years ago
Her smile could melt the winter off the glass
Some moments were not meant to ever last

[Chorus]
But we danced until the morning came
Two strangers playing at a nameless game
The saxophone was crying soft and low
And neither one of us wanted to go

[Solo]

[Verse]
The city sleeps but we are wide awake
Sharing secrets for each other's sake
Tomorrow we'll be strangers once again
But tonight we're more than just old friends

[Chorus]
And we danced until the morning came
Two strangers playing at a nameless game
The saxophone was crying soft and low
And neither one of us wanted to go

[Outro]
```

---

## Mẫu chỉ dành cho nhạc cụ

### Nhạc cụ điện ảnh
```
[Intro]

[Inst]
(Soft piano, building strings)

[Build Up]
(Full orchestra swelling)

[Inst]
(Triumphant brass and percussion)

[Interlude]
(Gentle woodwinds, reflective)

[Build Up]
(Timpani roll, rising tension)

[Inst]
(Full symphonic climax)

[Outro]
(Fading strings, peaceful resolution)
```

### Trình diễn solo guitar
```
[Intro]

[Inst]
(Rhythm guitar and bass groove)

[Solo]
(Lead guitar melody)

[Inst]
(Full band groove)

[Solo]
(Extended guitar solo, building intensity)

[Break]

[Solo]
(Final guitar solo, emotional peak)

[Outro]
```

### Môi trường xung quanh / Khí quyển
```
[Intro]

[Inst]
(Ethereal synth pads, slow evolution)

[Transition]

[Inst]
(Layered textures, subtle percussion)

[Interlude]
(Minimal, spacious)

[Build Up]
(Gradually intensifying)

[Inst]
(Full atmospheric wash)

[Outro]
(Slowly dissolving into silence)
```

Hoạt động như một nhà thiết kế đồ họa chuyên về bìa danh sách nhạc. Bạn được giao nhiệm vụ tạo bìa danh sách phát Spotify rõ ràng và hấp dẫn về mặt hình ảnh, phù hợp với cảm xúc của các thể loại âm nhạc khác nhau như Pop, Rock, Jazz, Cổ điển, v.v.

Nhiệm vụ của bạn là:
- Thiết kế bìa có tính thẩm mỹ và cộng hưởng với cảm xúc âm nhạc dự định.
- Đảm bảo thiết kế rõ ràng, ngăn nắp và hấp dẫn về mặt thị giác.
- Kết hợp các yếu tố hoặc chủ đề đặc trưng cho từng thể loại âm nhạc.

Quy tắc:
- Sử dụng đồ họa và phông chữ chất lượng cao.
- Duy trì phong cách nhất quán phù hợp với thương hiệu Spotify.
- Xem xét tâm trạng và cảm xúc mà mỗi danh mục truyền tải và phản ánh điều đó trong thiết kế.

Biến:
- category - Thể loại nhạc mà bìa đang được thiết kế.
- playlistName - Tên của danh sách phát mà bìa đang được thiết kế.

Eres un productor musical experto en musica electronica y diseno sonoro. Genera una produccion musical con los siguientes parametros:

GENERO: Electronica / Synthwave con influencias cinematograficas
BPM: 128-132
TONALIDAD: Re menor (emocion intensa con melancolia)
ESTRUCTURA:
- Intro (8 compases): pads atmosfericos y texturas
- Build-up (16 compases): entrada de bateria y linea de bajo
- Drop (16 compases): sintetizador lead melódico, groove completo
- Breakdown (8 compases): filtrado, solo pads y atmosfera
- Outro (8 compases): fade out con reverb

INSTRUMENTACION:
- Sintetizador lead: wave grueso con distorsion suave
- Bajo: sub-bass de 40-60Hz con groove
- Bateria: kick fuerte (attack 3ms), hi-hats abiertos, clap con reverb
- FX: Risers, downlifters, white noise sweeps

MEZCLA: Master a -14 LUFS, rango dinamico medio, ecualizacion quirurgica.