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.

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" \
  -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ự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í.

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