Tổng quan tài liệu Suno API

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

Chỉ cần đăng ký bằng địa chỉ email là bạn có thể tạo khóa API. Mỗi lần tạo nhạc tốn 0,6 ¥, trả về 2 bài hát và bao gồm tải MP3/WAV, cover, Extend, tách stem và nhân bản giọng nói. URL cơ sở: https://www.suno-api.io.

Trang này liệt kê các mô hình hiện có, toàn bộ endpoint tạo nhạc và chỉnh sửa, cách tính phí và thứ tự đọc được khuyến nghị. Nếu bạn tích hợp lần đầu, hãy đọc từ trên xuống dưới; phần xử lý lỗi 401/403/429 cũng nằm ở đây.

Trả lời nhanh

Làm sao để có khóa API? Đăng ký bằng địa chỉ email, mở bảng điều khiển, vào phần quản lý token và tạo một token. Không cần số điện thoại, không cần thẻ ngân hàng.

Một lần gọi tốn bao nhiêu? Một lần gọi tạo nhạc tốn 0,6 ¥ và trả về 2 bài hát. Truy vấn trạng thái, WAV, lời có mốc thời gian và gợi ý prompt đều miễn phí.

Hỗ trợ những mô hình nào? suno-v6 (mặc định), suno-v6-wild và suno-v6-mini. Các mô hình tạo nhạc tiêu chuẩn từ v5.5 trở về trước đã ngừng hỗ trợ; những tác vụ đã có không bị ảnh hưởng.

URL cơ sở là gì? https://www.suno-api.io, kèm header Authorization: Bearer YOUR_API_KEY.

Các mô hình hiện có

Các mô hình dành cho khách hàng để tạo nhạc tiêu chuẩn là suno-v6, suno-v6-wild và suno-v6-mini. Khi bỏ trống model, hệ thống dùng suno-v6.

Các mô hình tiêu chuẩn suno-v2, suno-v3, suno-v3-5, suno-v4, suno-v4-5, suno-v4-5-all, suno-v4-5-plus, suno-v5 và suno-v5-5 đã ngừng hỗ trợ. Các tác vụ cũ vẫn có thể hiển thị những tên này; đó là dữ liệu lịch sử, không có nghĩa là mô hình còn dùng được cho yêu cầu mới. Tách stem là ngoại lệ — xem API tách stem (tách giọng hát/nhạc đệm).

Xác thực

Mọi endpoint công khai dùng khóa API đều dùng cùng bộ header:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

URL cơ sở:

https://www.suno-api.io

Quy ước tham số chung

• Trường number trong body phải là số JSON, không phải chuỗi phần trăm. Cường độ 50% viết là 0.5, tuyệt đối không viết 50 hay 50%.
• Trường boolean phải là true hoặc false. Không dùng 0 hay 1 thay thế.
• Những trường ghi "không" có thể bỏ hẳn. Khi chưa rõ một tham số làm gì, hãy bỏ trống để dịch vụ dùng mặc định; đừng gửi chuỗi rỗng, null hay 0 thay cho "không gửi", vì 0 là giá trị hợp lệ của một số trường số.
• Tên trường phân biệt chính xác từng ký tự. Mỗi trang endpoint liệt kê tên khuyến nghị và các bí danh tương thích; hãy gửi đúng như bảng tham số. Ở nơi tài liệu ghi chấp nhận cả snake_case và camelCase, đừng gửi đồng thời cả hai.
• Mọi trường thời lượng kết thúc bằng _s hoặc Seconds đều tính bằng giây và nhận số thập phân. Timestamp Unix được mô tả riêng, kèm việc dùng giây hay mili giây.
• ID bắt đầu bằng pending: là chỗ giữ chỗ của nền tảng, không phải song_id thật. Chỉ dùng nó ở nơi endpoint ghi rõ là hỗ trợ chỗ giữ chỗ; các trường hợp khác hãy chờ song_id thật.

Giới hạn trường văn bản

Vượt giới hạn văn bản sẽ trả về HTTP 400 ngay lập tức: không tạo gì, không trừ trước và không sinh bản ghi tác vụ. Cách đếm theo ký tự Unicode (một chữ Hán tính là 1) và khoảng trắng đầu/cuối cũng được tính.

Trường message nêu rõ trường nào vượt giới hạn và độ dài đo được, nên chỉ cần hai con số đó là đủ để rút gọn:

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

Áp dụng cho: /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice.

Một ngoại lệ: trường description của POST /api/music/sounds bị giới hạn ở 100 ký tự, vì luồng hiệu ứng âm thanh dùng giới hạn ngắn hơn của nền tảng.

Tạo nhạc bất đồng bộ và địa chỉ âm thanh

Các endpoint tạo nhạc mặc định chạy bất đồng bộ. Khi phản hồi đầu tiên có status là pending, submitted hoặc processing, việc audio_url, video_url hay cover_url rỗng là bình thường và không có nghĩa là tác vụ thất bại. Hãy lưu song_id thật (hoặc client_request_id mà endpoint trả về) rồi gọi endpoint truy vấn tương ứng; chỉ đọc và tải địa chỉ âm thanh khi trạng thái đã hoàn tất.

⚠️ Địa chỉ âm thanh hết hạn sau 7 ngày — hãy chuyển file của bạn kịp thời

audio_url, wav_url, video_url và các địa chỉ do endpoint tải xuống trả về đều phục vụ từ lưu trữ đối tượng của nền tảng và mặc định hết hạn sau 7 ngày (file bị thu hồi; địa chỉ cũ trả 404 / tải không được).

• Trong 7 ngày đó, hãy chuyển file sang kho của bạn (lưu trữ đối tượng của bạn, CDN hoặc ổ đĩa máy chủ). Đừng coi địa chỉ của chúng tôi là link dài hạn.
• Địa chỉ hết hạn không cần tạo lại bài hát và không tốn thêm phí: hãy gọi lại API truy vấn bài hát (hoặc API tải media) để nhận địa chỉ mới còn hiệu lực cho bài hát đó.

Thời gian chờ và thiết lập timeout

Các endpoint tạo nhạc chạy đồng bộ: đơn chỉ được tiếp nhận và chuyển cho nền tảng tạo khi phản hồi về tới. Trước đó, dịch vụ phải xếp một tài khoản và vượt qua bước kiểm tra an toàn bắt buộc, và không có phản hồi trung gian — không endpoint nào khác nhìn thấy đơn hàng. Vì vậy bằng chứng đáng tin duy nhất cho "đã tạo được gì đó" chính là phản hồi, chứ không phải bất cứ thứ gì bạn quan sát được trong lúc chờ.

Thời gian chờ đo được (nhóm /api/music/create trên production, 2026-09-18 đến 2026-09-20)

• Khoảng 10% yêu cầu mất hơn 30 giây và khoảng 1% mất 1–2 phút. Yêu cầu chậm thường có nghĩa là lần đó phải qua bước kiểm tra an toàn trước.
• Trường yêu cầu, dạng phản hồi, mã lỗi và cách tính phí không đổi, nên các tích hợp hiện có chỉ cần nâng timeout phía client — không phải sửa code nào khác.

Yêu cầu khi tích hợp

1. Đặt timeout phía client từ 300 giây trở lên. Client mặc định 30, 60 hay 120 giây sẽ ngắt kết nối trong lúc chờ.
2. Không có phản hồi không có nghĩa là chưa tạo gì. Khi timeout hay mất kết nối, đơn có thể đã được tiếp nhận và đang tạo.
3. Đừng thử lại ngay sau khi timeout: gửi trùng sẽ tạo đơn thứ hai và bị tính phí lần nữa.
4. Nếu kết nối bị ngắt, hãy liệt kê bài hát bằng GET /api/music/songs (mới nhất trước) sau một lúc — các đơn đã được tiếp nhận sẽ xuất hiện bình thường. Chỉ gửi lại khi đã xác nhận đơn thật sự không có.
5. Khi báo lỗi, hãy gửi kèm header phản hồi X-Oneapi-Request-Id để định vị đúng yêu cầu đó.

Không muốn giữ kết nối lâu? Hãy dùng chế độ nhận biên nhận. POST /api/music/create và POST /api/music/create/custom hỗ trợ biên nhận tùy chọn: thêm "accept_mode": "async" vào body (hoặc header X-Accept-Mode: async) thì endpoint trả 202 ngay kèm số biên nhận trong khi việc tạo vẫn chạy nền; gọi GET /api/music/requests/{request_id} để theo dõi tiến độ. Client chỉ có timeout vài chục giây nhờ vậy không đọc nhầm "không có phản hồi" thành "chưa tạo gì", cũng không bị tính phí hai lần do thử lại. Xem "Chế độ nhận biên nhận" trong API tạo nhạc chế độ đơn giản.

Để tham khảo: python requests dùng timeout=300, urllib dùng urlopen(..., timeout=300), Node dùng req.setTimeout(300000), curl dùng --max-time 300.

Danh sách endpoint khuyến nghị

/api/voice/clone/* và /api/music/generate-with-voice là chuỗi nhân bản giọng nói đời đầu và không được khuyến nghị cho tích hợp mới; hãy dùng 【Khuyến nghị】 API hồ sơ giọng nói thay thế.

Tham số nâng cao: Max Mode và Variety

Các endpoint tạo nhạc hỗ trợ hai tham số tùy chọn này (bỏ trống thì giữ nguyên hành vi và giá cũ):

Hai tham số này được hỗ trợ bởi: POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech.

• Giá gấp đôi trên thực tế: endpoint 0,6 ¥ mỗi lần thành 1,2 ¥ khi bật max_mode; tạo nhạc với giọng đã chọn là 1,2 ¥ mỗi lần và 2,4 ¥ khi bật Max Mode; cover bằng giọng của 【Khuyến nghị】 API hồ sơ giọng nói cũng là 1,2 ¥ mỗi lần (2,4 ¥ khi bật max_mode).
• variety chỉ áp dụng cho họ suno-v6 (suno-v6, suno-v6-wild, suno-v6-mini); gửi nó cùng mô hình khác sẽ trả 400.
• Hiệu ứng âm thanh, tách stem, concat, WAV và các thao tác chỉnh sửa trong Studio (crop, xóa đoạn, fade, đảo ngược, đổi tốc độ…) không nhận hai tham số này — gửi rõ ràng sẽ trả 400, để không tham số nào bị bỏ qua âm thầm.
• variety là số nguyên thô 0-4; style_weight và weirdness_constraint là số thập phân từ 0 đến 1, nên thang đo khác nhau.

Các trường phản hồi bài hát thường gặp

Các endpoint tạo nhạc, cover, extend, tách stem và truy vấn thường trả về một mảng bài hát với những trường sau:

Bốn bước tích hợp (ví dụ tối thiểu)

Làm đủ bốn bước này là bạn đã có bài hát đầu tiên; danh sách trường đầy đủ của từng bước nằm ở trang tương ứng trong danh sách endpoint khuyến nghị.

# 1) Gửi yêu cầu tạo nhạc: 0,6 ¥, trả về 2 bài hát
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright Mandarin pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) Gọi lại tác vụ đến khi status là completed (khoảng 3-5 giây mỗi lần là hợp lý)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id trả về ở bước 1"}'

# 3) Lấy địa chỉ media: các endpoint đọc đều miễn phí; có song / wav / video / cover / midi
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "cũng song_id đó", "kind": "song"}'

Khi có sự cố: 401 / 402 / 403 / 429 được trình bày trong tài liệu lỗi; timeout và tính phí trùng nằm ở mục "Thời gian chờ và thiết lập timeout" phía trên; chi tiết từng endpoint nằm ở danh sách endpoint khuyến nghị bên dưới.

Khuyến nghị

• Tích hợp mới nên dùng suno-v6 xuyên suốt.
• Với các endpoint có ghi giá mặc định, số tiền thực thu tuân theo cấu hình giá hiện tại trong phần quản trị và mô hình được yêu cầu.
• Các endpoint tạo nhạc thường trả về tác vụ trước; hãy đọc âm thanh cuối cùng qua /api/music/query.
• wait_completion=true sẽ chặn cho tới khi xong và phù hợp để thử với lưu lượng thấp; trên production nên dùng cách gọi lại.
• Các endpoint tạo nhạc có thể mất rất lâu mới trả về — hãy đặt timeout phía client từ 300 giây trở lên, và nhớ rằng "không có phản hồi" không giống "chưa tạo gì"; xem "Thời gian chờ và thiết lập timeout" phía trên.
• Khả năng tải lên, cover, replace và WAV phụ thuộc vào tài khoản nền tảng và quyền của clip nguồn; khi thất bại, hãy đọc message hoặc error_message trả về trước.

Về tài liệu này

Trang này được tổ chức lại theo đúng những khả năng mà Create UI thực sự hiển thị, và các tích hợp mới nên đọc trang này trước. Tài liệu API cũ vẫn còn trong mục "Tài liệu API cũ (tương thích)" dành cho những ai muốn tiếp tục dùng.