API tạo giọng nói

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

Mô tả endpoint

Speech biến một bài phát biểu hoặc một câu mô tả thành âm thanh "nói/phát biểu", có thể kèm nhạc nền. Phù hợp cho phát biểu, chúc rượu, thuyết minh, kịch bản đọc lời, nội dung âm thanh và các tình huống tương tự.

Lưu ý: endpoint này tạo âm thanh nói, không phải bài hát được hát (không có giai điệu, không có giọng hát). Nếu cần hát, hãy dùng API tạo nhạc chế độ đơn giản hoặc API tạo nhạc chế độ tùy chỉnh.

Endpoint: POST /api/music/speech

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 âm thanh; số tiền thực trừ tuân theo cấu hình giá 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 vài giây (1-10 giây); nhưng giống các endpoint tạo nhạc đồng bộ khác, trong trường hợp cực đoan có thể lâu hơn. 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.

Tuân thủ nội dung: nền tảng kiểm tra bản phát biểu về bản quyền và chính sách nội dung. Nếu bị xác định là có vật liệu được bảo hộ (ví dụ trích lời bài hát của người khác hay nguyên văn một tác phẩm nổi tiếng), lần gọi này sẽ thất bại và toàn bộ tiền được hoàn tự động. Hãy chuyển sang cách diễn đạt của bạn, hoặc biến trích dẫn thành diễn giải, rồi thử lại.

Tham số yêu cầu

Headers

Tham số body

Endpoint này không hỗ trợ duration: gửi vào sẽ trả HTTP 400, không bỏ qua âm thầm. Độ dài bài phát biểu do độ dài nội dung của script quyết định.

Ví dụ yêu cầu

Yêu cầu tối thiểu (chỉ cần bản phát biểu)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Xin chào quý thầy cô và các bạn! Hôm nay bài nói của tôi bàn về việc tận dụng thời gian và nỗ lực tiến lên."
  }'

Yêu cầu đầy đủ (chỉ định giọng điệu, giới tính, tắt nhạc nền)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Good evening everyone, thank you all for coming to celebrate this special day with us.",
    "tone": "warm and slow, wedding reception",
    "song_title": "Wedding Toast",
    "gender": "f",
    "backing_music": false,
    "model": "suno-v6"
  }'

Ví dụ Python

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/speech',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'script': 'Chào buổi chiều các đồng nghiệp. Tôi xin báo cáo tiến độ tuần này.',
        'tone': 'điềm tĩnh và rõ ràng, báo cáo cuộc họp',
        'gender': 'male',
        'backing_music': True,
    },
    timeout=300,
)
response.raise_for_status()
items = response.json()          # thường là 2 mục
for item in items:
    print(item['song_id'], item['status'])

Giải thích tham số

script (bài phát biểu, bắt buộc)

• Dán nội dung bạn muốn nói; cũng có thể viết một câu mô tả để model tự viết bài phát biểu (ví dụ "bài động viên giờ nghỉ cho đội đang thua hai mươi điểm, từ giọng thì thầm đến tiếng gầm phá tan sân vận động").
• Xuống dòng, đoạn và chỉ dẫn sân khấu như [ngừng] đều có thể viết trực tiếp, model sẽ tuân theo trong mức có thể.
• Giới hạn 3000 ký tự (tính theo ký tự Unicode, một chữ Hán tính là 1); vượt sẽ trả 400 và không tính phí.

tone (giọng điệu và bối cảnh, không bắt buộc)

Nó mô tả nói như thế nào, chứ không phải nói cái gì. Nên gồm bốn loại thông tin: giọng điệu, tốc độ/nhịp, cảm xúc, bối cảnh.

Sôi nổi và mạnh mẽ, tốc độ từ chậm đến nhanh, ngắt nghỉ rõ ràng; hội trường trường, trước toàn thể thầy cô và học sinh
Ấm áp và nhẹ nhàng, tốc độ chậm rãi; tiệc cưới
Điềm đạm và tiết chế, đều đặn và rõ ràng; báo cáo hội đồng quản trị

Giới hạn 1000 ký tự. Nếu không gửi, model tự phán đoán theo nội dung script.

gender / vocal_gender (giới tính người nói, không bắt buộc)

• Giọng nam gửi m hoặc male, giọng nữ gửi f hoặc female; máy chủ chuẩn hoá về m / f.
• Cả hai tên trường đều dùng được, chỉ cần một: gender là cách viết được khuyến nghị cho endpoint này; nếu bạn đã dùng chế độ tùy chỉnh, có thể tiếp tục dùng vocal_gender.
• Không gửi nghĩa là "không giới hạn", model tự quyết định.

backing_music (nhạc nền, không bắt buộc)

• Mặc định true (có nhạc nền), giống bản web của Suno.
• false cho bài phát biểu chỉ có giọng nói, tiện nếu sau đó bạn muốn thêm nhạc hoặc lồng tiếng của mình.
• Phải là boolean JSON true / false; chuỗi "true", "1" cũng được chấp nhận, nhưng nên dùng boolean.

model (model, không bắt buộc)

Cả ba model phía khách hàng đều dùng được và cùng giá (0,6 ¥ mỗi lần gọi). Bài phát biểu được tạo bởi dòng máy Suno v6; nếu không gửi thì xử lý như suno-v6. Trừ khi bạn có sở thích rõ ràng, thường không cần gửi trường này.

Kiểm tra tham số và giới hạn văn bản

Các trường hợp sau trả HTTP 400 và đều bị chặn trước khi tính phí, nên không phát sinh chi phí:

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

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

Thông báo lỗi có dạng script must not exceed 3000 characters; received 4120: từ đầu tiên là tên trường vượt giới hạn, phần cuối là số ký tự thực tế, nên khi nhận 400 bạn có thể cắt trực tiếp theo hai con số đó.

Phản hồi

Phản hồi là mảng bài hát hoàn toàn giống các endpoint tạo nhạc khác (thường 2 mục); lưu song_id rồi dùng API truy vấn bài hát và lịch sử để tra trạng thái cuối cùng và địa chỉ âm thanh:

[
  {
    "song_id": "b7529174-b495-465b-8c5e-cd21bea2df8c",
    "song_title": "Tận dụng thời gian",
    "status": "pending",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-10-08T01:00:00Z"
  }
]

Tạo thất bại và hoàn tiền

Khi tạo thất bại, chi phí lần đó được hoàn toàn bộ tự động; không cần liên hệ hỗ trợ. Lý do có thể thấy trong phản hồi hoặc trong error_message của API truy vấn bài hát và lịch sử.

Nguyên nhân thất bại phổ biến nhất là nội dung bị nền tảng xác định là có vật liệu được bảo hộ, ví dụ:

Your lyrics contain copyrighted material. Please change it and try again.

Trong trường hợp đó, hãy đổi bản phát biểu sang cách diễn đạt của bạn (hoặc biến trích dẫn thành diễn giải) rồi gửi lại.

Câu hỏi thường gặp

H: Vì sao kết quả là "nói" mà không phải hát? Đ: Đây là endpoint phát biểu, đầu ra là âm thanh nói. Muốn hát hãy dùng endpoint tạo nhạc hoặc chế độ tùy chỉnh.

H: Vì sao mỗi lần trả về 2 mục? Đ: Như các endpoint tạo nhạc khác của nền tảng, một lần tạo ra 2 phương án; hãy truy vấn riêng theo song_id và giữ phương án bạn hài lòng.

H: Làm sao kiểm soát độ dài? Đ: Do độ dài của script quyết định; endpoint này không nhận tham số duration.

H: Có thể chỉ định giọng (ví dụ giọng tôi đã clone) không? Đ: Phiên bản hiện tại chưa hỗ trợ. Bài phát biểu dùng bộ giọng nói cố định, có thể chọn nam/nữ bằng gender; nếu cần giọng của chính bạn, hãy dùng khả năng liên quan của API tạo hồ sơ giọng nói (khuyến nghị).

H: Nếu không gửi tone thì sao? Đ: Model tự phán đoán giọng điệu và nhịp theo nội dung script. Muốn tái hiện ổn định một phong cách, hãy viết giọng điệu, tốc độ và bối cảnh vào tone.

Trường tương thích

Khi tích hợp mới hãy dùng thống nhất snake_case. Các trường còn lại (script, tone, song_title, backing_music) không có bí danh camelCase.

Bước tiếp theo

Sau khi có song_id:

1. Dùng API truy vấn bài hát và lịch sử để tra trạng thái tạo nhạc và địa chỉ âm thanh;
2. Khi xong, dùng API tải và nghe thử media của bài hát để tải hoặc nghe thử;
3. Muốn tải hàng loạt hoặc chuyển sang kho của bạn, xem các endpoint của trung tâm tải xuống.