Gọi API tạo nhạc tự động: khoá, tags, hỏi kết quả, tránh tốn credit

Trang tạo nhạc hợp cho một người làm từng bài. Khi cần 30 bài cho 30 chi nhánh, một bài chúc mừng tự động cho mỗi khách hàng sinh nhật trong tháng, hay một ứng dụng riêng có nút "tạo nhạc" cho người dùng của bạn, thì bấm tay không còn hợp. AI Âm Nhạc có API cho việc đó: hai lệnh gọi HTTP, trừ credit vào đúng tài khoản của bạn.

Bài này viết cho người biết gọi HTTP cơ bản. Không cần thư viện gì đặc biệt — curl là đủ để thử.

Lấy khoá

Đăng nhập, vào trang API, tạo khoá. Khoá có dạng anm_ theo sau là một chuỗi dài. Mỗi khoá có thể đặt nhãn (ví dụ "server-shop", "thu-nghiem"), tắt tạm hoặc xoá hẳn.

Ba nguyên tắc với khoá:

• Khoá tiêu credit của bạn. Ai có khoá là tạo được nhạc bằng tiền của bạn. Đừng nhúng khoá vào mã chạy trên trình duyệt hay ứng dụng điện thoại — đặt ở máy chủ của bạn, ứng dụng gọi qua máy chủ.
• Mỗi nơi dùng một khoá. Lộ một khoá thì tắt đúng khoá đó, nơi khác vẫn chạy.
• Khoá thử nghiệm riêng. Lúc viết mã, dùng một khoá có nhãn "thu-nghiem" để sau này xoá gọn.

Lệnh 1: gửi yêu cầu tạo bài

POST https://aiamnhac.com/v1.php?action=create

Header: Authorization: Bearer anm_XXXX và Content-Type: application/json.

Thân yêu cầu là JSON với ba trường:

Xuống dòng trong lời viết là \n trong chuỗi JSON. Ví dụ thử nhanh:

curl -X POST "https://aiamnhac.com/v1.php?action=create" -H "Authorization: Bearer anm_XXXX" -H "Content-Type: application/json" -d '{"lyrics":"[Verse 1]\nSáng nay quán mở cửa sớm\n...\n[Chorus]\n...","tags":"vietnamese pop, upbeat, happy, female vocal","duration":60}'

Thành công trả về {"job_id":"…","credits_used":5000}. Credit đã bị trừ ngay lúc này.

Lệnh 2: hỏi kết quả

GET https://aiamnhac.com/v1.php?action=status&id=<job_id> với cùng header khoá.

Các trạng thái có thể gặp:

Nhịp hỏi hợp lý: mỗi 10–30 giây. Thường khoảng một phút là xong; khi máy chính bận, bài đi sang máy dự phòng chậm hơn nhiều và có thể mất hàng chục phút. Đừng giữ một kết nối chờ — hỏi theo nhịp, và đặt giới hạn tổng thời gian chờ ở phía bạn (ví dụ 2 tiếng) rồi mới coi là thất bại. Bên mình cũng có giới hạn riêng: bài kẹt quá lâu sẽ tự chuyển sang lỗi và hoàn credit.

Khi nhận done, tải file về và lưu ở chỗ của bạn. Đường dẫn trả về là để tải, đừng dùng nó làm nơi lưu trữ lâu dài cho ứng dụng.

Viết tags cho đúng — chỗ quan trọng nhất

Trang web ghép tags từ các nút. Qua API, bạn tự viết chuỗi này, và cách viết ảnh hưởng trực tiếp tới kết quả.

Hệ thống dò trong chuỗi tags các từ khoá thể loại theo thứ tự: bolero, rap, edm, rock, lofi, children, acoustic, ballad, pop. Gặp từ khoá nào trước thì dùng bộ mô tả đầy đủ của thể loại đó (nhạc cụ, chất âm) và chọn nhịp trong khoảng của nó. Tương tự với giọng: male and female duet vocal, female vocal, male vocal, instrumental.

Những phần còn lại (tâm trạng, nhạc cụ thêm) được giữ nguyên và ghép vào sau.

Hệ quả:

• Viết đúng từ khoá như trang web để được bộ mô tả đầy đủ: vietnamese ballad, romantic, warm, female vocal cho kết quả giống hệt bấm Ballad + Lãng mạn + Giọng nữ.
• Không có từ khoá thể loại nào thì chuỗi của bạn được gửi nguyên văn, không có nhịp gợi ý. Dùng được nếu bạn biết mình đang mô tả gì, nhưng kết quả kém đều tay hơn.
• Hai từ khoá thể loại trong một chuỗi thì cái đứng trước trong thứ tự dò thắng, không phải cái bạn viết trước. pop, rock guitar → Rock.

Bảng tags tương đương với các nút trên web:

Tâm trạng: upbeat, happy · sad, melancholic · energetic, powerful · soft, gentle, relaxing · epic, anthem, cinematic · romantic, warm.

Chuỗi tags tối đa 400 ký tự. Ý nghĩa từng nút được giải thích ở bài máy thật sự nhận gì từ mỗi nút chọn.

Mã lỗi và cách xử lý

Mã 429 là điểm khác lớn nhất so với các API quen thuộc: mỗi tài khoản chỉ chạy một bài một lúc. Gửi 30 yêu cầu dồn dập thì yêu cầu thứ hai trở đi bị từ chối ngay. Hàng đợi phải nằm ở phía bạn.

Một vòng lặp hàng loạt đúng cách

Giả sử bạn có danh sách 30 bộ lời cho 30 chi nhánh:

1. Đọc bộ lời tiếp theo trong danh sách.
2. Gọi create. Nhận 429 → chờ 30 giây, thử lại. Nhận 402 → dừng cả vòng. Nhận 400 → ghi lỗi, bỏ qua bộ này.
3. Có job_id → hỏi status mỗi 15 giây.
4. done → tải MP3, đặt tên theo chi nhánh, ghi lại job_id.
5. error → ghi lỗi; tuỳ chọn gửi lại một lần.
6. Quay lại bước 1.

Ước lượng thời gian: lúc máy chính rảnh, mỗi bài thường khoảng một phút, nên 30 bài là cỡ nửa tiếng đến một tiếng. Chạy vào buổi tối hoặc sáng sớm thường đều hơn giờ cao điểm. Đừng hứa với khách "xong trong 30 phút" dựa trên con số tốt nhất.

Những chỗ làm tròn credit

• Độ dài làm tròn lên theo phút. 61 giây tính như 2 phút; 90 giây cũng 2 phút. Theo bảng giá hiện tại, mỗi phút 5.000 credit. Gửi đúng bội số 60 để không trả cho phần không dùng.
• Độ dài ngoài khoảng bị kẹp lại: dưới 30 giây thành 30, trên 300 thành 300.
• Lời trống = nhạc không lời; vẫn tính theo độ dài như bình thường.
• Bài lỗi được hoàn đủ một lần, tự động. Không cần gọi gì thêm.

Kiểm thử trước khi chạy thật

• Gửi một bài 30–60 giây với lời ngắn để kiểm luồng mã. Rẻ nhất có thể.
• Thử cố tình sai khoá, gửi hai yêu cầu liền nhau, để chắc mã của bạn xử lý đúng 401 và 429.
• Kiểm chuỗi lời sau khi mã hoá JSON vẫn giữ dấu tiếng Việt (UTF-8). Lời mất dấu sẽ bị hát như tiếng Anh — lỗi này hay gặp khi đọc dữ liệu từ tệp CSV xuất bằng Excel với bảng mã cũ.

Viết lời cho máy hát rõ, xem mục Viết lời & cấu trúc bài. Nếu ứng dụng cần cả giọng đọc lồng tiếng, AI Giọng Nói cũng có API theo cách tương tự.

Hỏi đáp nhanh