Bắt đầu nhanh

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

Hướng dẫn này đưa bạn từ việc tạo khóa API đến bản nhạc đầu tiên, kiểm tra tiến độ và tải audio chỉ trong khoảng năm phút. Các ví dụ có thể sao chép và chạy nguyên trạng.

Mô hình mặc định hiện tại là suno-v6. Các mô hình tạo nhạc từ suno-v2 đến suno-v5-5 đã bị tắt: chúng có thể xuất hiện trong tác vụ cũ nhưng không nhận yêu cầu mới.

Tải xuống, cài đặt và cấu hình suno-api agent kit từ địa chỉ này  https://www.suno-api.io/suno-agent-kit.zip

Khuyến nghị: để AI hoàn tất tích hợp

AI đọc 00_START_HERE.md và hỗ trợ đăng ký, lưu API Key, kiểm tra số dư, giới thiệu toàn bộ tính năng và lần tạo đầu tiên. Thao tác tính phí được xác nhận trước và timeout sẽ không tự động gửi lại.

Bước 1: lấy khóa API

1. Mở https://www.suno-api.io.
2. Nhấn Lấy khóa API và đăng ký. Chỉ cần e-mail, không cần số điện thoại.
3. Trong bảng điều khiển, mở phần quản lý token và tạo một khóa.
4. Sao chép ngay — khóa chỉ hiển thị một lần. Nạp số dư bằng mã kích hoạt trước lần gọi tính phí đầu tiên.

Bước 2: thiết lập yêu cầu

Mọi lời gọi đều dùng cùng địa chỉ gốc và cùng tiêu đề:

POST https://www.suno-api.io
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Bước 3: gửi yêu cầu đầu tiên

Ví dụ 1 — tạo từ mô tả

Mô tả bản nhạc, API sẽ viết lời, giai điệu và phần phối khí:

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "description": "một bài folk vui tươi về ngày đầu tiên của mùa xuân",
    "model": "suno-v6"
  }'

Phản hồi:

[
  {
    "song_id": "abc123",
    "status": "pending",
    "song_title": "Câu chuyện mùa xuân",
    "description": "một bài folk vui tươi về ngày đầu tiên của mùa xuân",
    "created_at": "2026-04-22T10:30:00Z"
  },
  {
    "song_id": "def456",
    "status": "pending",
    "song_title": "Nhịp bước mùa xuân",
    "description": "một bài folk vui tươi về ngày đầu tiên của mùa xuân",
    "created_at": "2026-04-22T10:30:00Z"
  }
]

Mỗi lần chạy trả về hai phiên bản khác nhau để bạn chọn. Một lần tạo tốn 0,6 ¥.

Ví dụ 2 — kiểm tra tiến độ

Gửi các song_id nhận được tới điểm cuối truy vấn:

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": ["abc123", "def456"],
    "model": "suno-v6"
  }'

Khi tác vụ đang chạy:

[
  {
    "song_id": "abc123",
    "status": "processing",
    "song_title": "Câu chuyện mùa xuân",
    "progress": "60%"
  }
]

Khi hoàn tất:

[
  {
    "song_id": "abc123",
    "status": "completed",
    "song_title": "Câu chuyện mùa xuân",
    "audio_url": "https://media.code-go.com/assets/abc123-mp3.mp3",
    "video_url": "https://media.code-go.com/assets/abc123-mp4.mp4",
    "cover_url": "https://media.code-go.com/assets/abc123-cover.jpg",
    "duration": 168
  }
]

status đi qua pending, submitted, processing rồi tới completed. Địa chỉ có thể trống trong lúc tác vụ chạy: hãy đánh giá theo status, đừng dựa vào việc có audio_url hay không.

Bước 4: tải tệp

Khi status là completed, chỉ cần yêu cầu audio_url. Việc tải MP3 và WAV là không giới hạn và không tốn thêm phí. Nếu cần audio không mất dữ liệu để dựng, hãy dùng điểm cuối WAV.

Tình huống thường gặp

Nhạc nền cho video

{
  "description": "nhạc nền lo-fi nhẹ nhàng cho video sản phẩm, không lời, động lực ổn định",
  "instrumental": true,
  "model": "suno-v6"
}

Khi instrumental là true, kết quả không có giọng hát.

Lời và phong cách riêng

{
  "lyrics": "[Verse 1]\nĐèn thành phố dần tắt\n\n[Chorus]\nChúng ta cứ bước tiếp",
  "style": "acoustic pop, giọng nữ ấm, 92 BPM",
  "model": "suno-v6"
}

Truy vấn cho tới khi xong

import time
import requests

API_KEY = "sk-your-key-here"
BASE = "https://www.suno-api.io"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

created = requests.post(
    f"{BASE}/api/music/create",
    headers=HEADERS,
    json={"description": "một bài folk vui tươi về mùa xuân", "model": "suno-v6"},
).json()

song_ids = [track["song_id"] for track in created]

for _ in range(60):
    time.sleep(10)
    tracks = requests.post(
        f"{BASE}/api/music/query",
        headers=HEADERS,
        json={"song_ids": song_ids, "model": "suno-v6"},
    ).json()
    if all(track.get("status") == "completed" for track in tracks):
        for track in tracks:
            print(track["song_title"], track["audio_url"])
        break

Xử lý lỗi

Các mã chính

Định dạng lỗi

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Thời gian chờ và timeout (quan trọng): các endpoint tạo nhạc là đồ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 (--max-time 300 trong ví dụ); 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.

Thực hành tốt

• Giữ khóa trên máy chủ, không bao giờ đặt trong trình duyệt hay ứng dụng phát hành.
• Truy vấn mỗi 10–15 giây thay vì lặp liên tục.
• Lưu song_id: đây là định danh duy nhất để tìm lại audio sau này.
• Gửi lại khi gặp 429 và 500; sửa nguyên nhân trước khi gửi lại với 400 và 401.
• Các lần tạo thất bại được hoàn tiền tự động, nên tác vụ hỏng không tốn phí.
• Timeout phía client: endpoint tạo nhạc chỉ được coi là đã tiếp nhận khi có phản hồi; hãy đặt timeout từ 300 giây trở lên.
• Thử lại: chỉ thử lại khi có lỗi rõ ràng (4xx/5xx). Sau khi timeout hoặc mất kết nối, hãy kiểm tra trước bằng GET /api/music/songs xem đơn đã được tiếp nhận chưa, tránh trùng đơn và bị tính phí hai lần.

Bước tiếp theo

• Xác thực — khóa, lỗi và giới hạn
• Mô hình hỗ trợ — tên mô hình, tách stem và mô hình đã tắt