Xác thực

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

Mọi yêu cầu tới Suno-API đều được xác thực bằng khóa API. Trang này trình bày cách tạo khóa, cách gửi khóa, ý nghĩa của các lỗi và cách giữ khóa an toàn.

Khóa API là gì

Khóa là một bearer token gắn với tài khoản của bạn. Khóa mang theo số dư, nên ai có khóa thì có thể tiêu số dư đó. Khóa chỉ hiển thị một lần khi tạo: hãy sao chép và cất ở nơi an toàn.

Tạo khóa

1. Đăng ký tại https://www.suno-api.io — chỉ cần e-mail, không cần số điện thoại.
2. Mở phần quản lý token trong bảng điều khiển.
3. Tạo khóa mới và sao chép.

Khóa có dạng sk-…. Khóa bị mất không thể khôi phục: hãy tạo khóa mới và xóa khóa cũ.

Dùng khóa

Định dạng header

Gửi khóa trong tiêu đề Authorization ở mọi yêu cầu:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Ví dụ

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ản piano nhẹ nhàng cho quán cà phê"}'

Lỗi xác thực

401 Unauthorized

Thiếu tiêu đề, tiêu đề sai định dạng hoặc khóa không tồn tại.

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

Kiểm tra xem tiêu đề có đúng dạng Bearer <khóa> (có dấu cách sau Bearer) và phần cuối khóa không bị lẫn ký tự xuống dòng.

403 Forbidden

Khóa tồn tại nhưng không được phép thực hiện yêu cầu này — thường là do khóa đã bị vô hiệu hoặc tài khoản bị tạm ngưng. Kiểm tra trạng thái tài khoản trong bảng điều khiển và liên hệ hỗ trợ nếu chưa rõ nguyên nhân.

Thực hành bảo mật tốt

Không đặt khóa trong mã phía máy khách

Đừng nhúng khóa vào trang web, ứng dụng di động hay phần mềm máy tính. Bất kỳ ai mở công cụ kiểm tra của trình duyệt đều đọc được và tiêu số dư của bạn. Hãy gọi API từ máy chủ của bạn và chỉ công bố điểm cuối của riêng bạn cho người dùng.

Dùng biến môi trường

Linux / macOS

# ~/.bashrc hoặc ~/.zshrc
export SUNO_API_KEY="sk-your-key-here"

# Python
import os
api_key = os.environ["SUNO_API_KEY"]

.env

# tệp .env — thêm vào .gitignore
SUNO_API_KEY=sk-your-key-here

Windows

setx SUNO_API_KEY "sk-your-key-here"

Node.js

require('dotenv').config();
const apiKey = process.env.SUNO_API_KEY;

Xoay khóa khi cần

Nên đổi khóa mỗi 3-6 tháng, và đổi ngay nếu nghi ngờ rò rỉ. Hãy xóa những khóa không còn dùng: khóa không dùng chỉ là rủi ro không dùng.

Giới hạn yêu cầu

Yêu cầu được giới hạn theo từng khóa:

429 Too Many Requests

Khi vượt giới hạn, API trả 429 và phản hồi có thể kèm giá trị retry_after tính bằng giây. Hãy chờ đủ thời gian đó rồi thử lại; giảm nhịp yêu cầu, đưa công việc vào hàng đợi hoặc thử lại với độ trễ tăng dần thay vì lặp liên tục.

Chính sách thử lại

Chỉ thử lại khi có lỗi rõ ràng. Không thử lại sau khi hết thời gian đọc hoặc kết nối: các endpoint tạo nhạc là đồng bộ, nên hết thời gian có thể nghĩa là đơn đã được tiếp nhận và đang tạo — thử lại sẽ tạo đơn trùng và bị tính phí hai lần. Hãy đặt timeout phía client từ 300 giây trở lên và sau khi mất kết nối, kiểm tra đơn bằng GET /api/music/songs trước khi gửi lại. Xem "Thời gian chờ và thiết lập timeout" trong Tổng quan API mới.

Hãy gửi lại với backoff lũy thừa thay vì lặp liên tục:

import time

delay = 1.0
for attempt in range(5):
    response = call_api()
    if response.status_code != 429:
        break
    time.sleep(delay)
    delay *= 2

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

Khóa có định dạng thế nào?

Khóa bắt đầu bằng sk- rồi tới chữ và số, tổng cộng khoảng 50-60 ký tự.

Có thể gọi API trực tiếp từ trình duyệt không?

Về mặt kỹ thuật là có, nhưng đừng làm vậy trong môi trường thật: khóa sẽ lộ cho mọi khách truy cập. Hãy proxy qua backend của bạn.

Làm sao biết khóa còn hiệu lực?

Gửi một yêu cầu có xác thực bất kỳ. 200 nghĩa là còn dùng được; 401 nghĩa là khóa không hợp lệ hoặc đã bị xóa.

Tôi mất khóa thì phải làm sao?

Khóa không thể khôi phục. Hãy tạo khóa mới trong bảng điều khiển và xóa khóa cũ.

Một tài khoản có bao nhiêu khóa?

Không có giới hạn cố định. Nên dùng mỗi ứng dụng hoặc môi trường một khóa để thu hồi riêng, và xóa những khóa không còn dùng.

Khóa có hết hạn không?

Khóa còn hiệu lực cho tới khi bạn xóa hoặc đóng tài khoản. Xoay định kỳ là thực hành tốt.

Làm sao theo dõi mức sử dụng?

Đăng nhập bảng điều khiển: mức sử dụng theo từng khóa được liệt kê ở đó, gồm số yêu cầu, chi phí và các tác vụ gần đây.

Trang liên quan

• Bắt đầu nhanh
• Mô hình hỗ trợ