API tạo nhạc chế độ tùy chỉnh

Cập nhật 2026-09-18 · nhóm Suno-API

Mô tả endpoint

Chế độ tùy chỉnh phù hợp khi bạn đã có lời, phong cách và tiêu đề và muốn điều khiển giọng hát, mức ảnh hưởng của phong cách cũng như độ ngẫu nhiên khi tạo nhạc.

Endpoint: POST /api/music/create/custom

Tính phí: Có phí, hiện mặc định 0,6 ¥ mỗi lần gọi. Mỗi lần thường trả về 2 bài hát; số tiền thực trừ tuân theo cấu hình giá hiện tại trong phần quản trị.

Max Mode / Variety: endpoint này hỗ trợ hai tham số tùy chọn max_mode và variety (0-4). Khi bật max_mode, lần gọi này bị tính gấp đôi (0,6 → 1,2 ¥ mỗi lần); variety không phát sinh phí thêm. Ý nghĩa và cách gửi xem mục "Tham số nâng cao" trong Tổng quan API mới.

Thời gian chờ và timeout (quan trọng): đây là endpoint đồng bộ — đơn chỉ được tiếp nhận và đưa vào tạo nhạc khi phản hồi trả về. Theo đo đạc, phần lớn yêu cầu trả về trong 1-3 giây, khoảng 10% mất hơn 30 giây và lâu nhất khoảng 230 giây. Hãy đặt timeout phía client từ 300 giây trở lên; không nhận được phản hồi không có nghĩa là chưa tạo gì, và đừng thử lại ngay sau khi timeout (sẽ trùng đơn và bị tính phí hai lần). Nếu kết nối bị ngắt, hãy kiểm tra lại sau bằng GET /api/music/songs. Xem "Thời gian chờ và thiết lập timeout" trong Tổng quan API mới.

Tham số yêu cầu

Headers

Tham số body

Ghi chú về tham số nâng cao

Giới tính giọng hát vocal_gender

• Gửi m hoặc male cho giọng nam, f hoặc female cho giọng nữ.
• Hệ thống chuẩn hóa male và female thành m và f.
• Khi instrumental=true, tham số giới tính giọng hát không được gửi tới dịch vụ tạo nhạc.

Mức ảnh hưởng phong cách style_weight

Điều khiển mức độ kết quả bám theo style_tags. Giá trị càng cao thì kết quả càng nghiêng về các thẻ phong cách bạn nhập.

Độ ngẫu nhiên weirdness_constraint

Điều khiển mức độ biến đổi và tính thử nghiệm của kết quả. Giá trị cao thường cho nhiều biến đổi hơn; giá trị thấp thường cho kết quả an toàn hơn.

Hai tham số số đều nằm trong khoảng 0.0 đến 1.0, và 0 là giá trị rõ ràng hợp lệ. Chỉ khi bỏ hẳn trường mới có nghĩa là "không chỉ định".

Khi điền, hãy lưu ý đây là số thập phân theo tỉ lệ, không phải số nguyên phần trăm. Tham chiếu: 0.0–0.3 thiên thận trọng, 0.4–0.6 cân bằng, 0.7–1.0 thiên thử nghiệm; nếu không có sở thích rõ ràng thì dùng 0.5 hoặc bỏ hẳn. Ví dụ: weirdness_constraint: 0.5, đừng ghi 50 hay 50%.

Khi instrumental=true, kết quả là nhạc không lời nên lời và giới tính giọng hát không phát huy như với bài hát có hát; nếu cần giọng hát, hãy gửi false hoặc bỏ trường đó. Trường boolean phải dùng true/false của JSON, không dùng chuỗi.

Ví dụ yêu cầu Python

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\nMàn đêm buông trên mặt biển\ngió chiều khẽ lướt qua cửa sổ',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': 'Gió chiều bên biển',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

Chế độ nhận biên nhận (không bắt buộc)

Endpoint này cũng hỗ trợ chế độ nhận biên nhận của API tạo nhạc chế độ đơn giản: khi thêm "accept_mode": "async" vào body (hoặc header X-Accept-Mode: async), endpoint trả về 202 và số biên nhận ngay, việc tạo vẫn chạy nền, và bạn theo dõi tiến độ bằng GET /api/music/requests/{request_id}.

Phù hợp với client không nên giữ kết nối lâu, hoặc không muốn timeout bị hiểu nhầm thành "chưa tạo gì". Không có tham số này thì hành vi giống hệt trước đây.

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "Gió chiều bên biển",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

Cấu trúc phản hồi và cách tra tiến độ nằm ở mục "Chế độ nhận biên nhận" trong API tạo nhạc chế độ đơn giản.

Kiểm tra tham số

Những trường hợp sau trả về HTTP 400, và message của lỗi nêu rõ trường không hợp lệ:

• style_weight hoặc weirdness_constraint không phải là số.
• Giá trị số nhỏ hơn 0.0 hoặc lớn hơn 1.0.
• vocal_gender không thuộc m, f, male, female.

Giới hạn độ dài trường văn bản

Những trường sau cũng trả về HTTP 400 khi quá dài, không vào tạo nhạc và không trừ trước phí. Cách đếm theo ký tự Unicode (một chữ Hán tính là 1) và tính cả khoảng trắng đầu/cuối:

Thông báo lỗi có dạng style_tags must not exceed 1000 characters; received 2772: từ đầu là tên trường vượt giới hạn, cuối là số ký tự đo được, nên khi nhận 400 chỉ cần rút gọn theo hai con số đó, không phải thử từng trường. Quy ước chung nằm ở "Giới hạn trường văn bản" trong Tổng quan API mới.

Phản hồi

Endpoint thường trả về mảng gồm 2 bài hát. Yêu cầu bất đồng bộ thường bắt đầu ở trạng thái pending; hãy lưu song_id rồi lấy trạng thái cuối cùng và địa chỉ âm thanh qua API truy vấn bài hát. Các trường của bài hát giống như trong API tạo nhạc chế độ đơn giản.

Trường tương thích

Tích hợp mới nên dùng snake_case thống nhất. Nếu cùng một yêu cầu gửi cả snake_case và camelCase, giá trị snake_case được ưu tiên.