API chứng nhận cấp phép sử dụng âm nhạc thương mại

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

Mô tả endpoint

Các endpoint chứng nhận cấp phép sử dụng âm nhạc thương mại dùng để liệt kê những bài hát mà người dùng của API Key hiện tại có thể cấp phép, tạo chứng nhận PDF, tra cứu lịch sử chứng nhận và tải các tệp đã phát hành.

Tất cả endpoint đều dùng thống nhất New API Key:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Địa chỉ cơ sở:

https://www.suno-api.io

Điều kiện tiên quyết

• API Key phải hợp lệ và thuộc về người dùng cần chứng nhận.
• Người dùng cần hoàn tất trước việc liên kết danh tính cấp phép (xem "0. Điều kiện cấp phép và danh tính"); sau khi xác nhận, danh tính sẽ bị khóa theo quy tắc sản phẩm.
• Người dùng cần đáp ứng yêu cầu nạp tích lũy cho cá nhân hoặc doanh nghiệp.
• Các endpoint thông thường chỉ trả về thông tin danh tính đã được che; không bao giờ trả về số giấy tờ, số điện thoại hay mã tín dụng xã hội thống nhất ở dạng văn bản rõ.
• Mỗi bài hát chỉ có thể phát hành thành công một chứng nhận; chứng nhận tạo thất bại không chiếm mất điều kiện của bài hát.
• Hiện hỗ trợ các loại tạo nhạc chỉ định đã hoàn tất, có âm thanh và có Suno Song ID thật. Việc bài hát có chọn được hay không do authorization.selectable trong danh sách bài hát quyết định.

0. Điều kiện cấp phép và danh tính

Trước khi phát hành chứng nhận cần tra cứu điều kiện và liên kết danh tính. Hai endpoint này đều miễn phí.

0.1 Tra cứu điều kiện và danh tính

Endpoint: GET /api/music/authorization/context

{
  "code": 200,
  "message": "success",
  "data": {
    "identity": {
      "exists": false
    },
    "eligibility": {
      "current_amount": 216.3,
      "personal_required_amount": 200,
      "company_required_amount": 500,
      "personal_eligible": true,
      "company_eligible": false
    },
    "stats": {
      "authorized_song_count": 0,
      "certificate_count": 0
    }
  }
}

0.2 Liên kết danh tính cấp phép

Endpoint: POST /api/music/authorization/identity

{
  "identity_type": "personal",
  "legal_name": "Nguyễn Văn A",
  "id_number": "110101199001010000",
  "contact_name": "Nguyễn Văn A",
  "phone": "13800000000",
  "email": "user@example.com",
  "address": "12 Lê Lợi, Quận 1, TP. Hồ Chí Minh",
  "confirm_locked": true
}

Phản hồi trả về thông tin danh tính đã che: {"identity": {...}}. Sau khi liên kết thành công, hãy dùng endpoint context để xác nhận identity.exists đã thành true rồi mới gọi danh sách bài hát và các endpoint phát hành. Nếu cần sửa thông tin danh tính, hãy liên hệ bộ phận hỗ trợ.

1. Liệt kê bài hát có thể cấp phép

Endpoint: GET /api/music/authorization/songs

Tham số query

Ví dụ yêu cầu

curl "https://www.suno-api.io/api/music/authorization/songs?p=1&page_size=20&status=selectable" \
  -H "Authorization: Bearer YOUR_API_KEY"

Ví dụ phản hồi

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "items": [
      {
        "task_id": 10001,
        "suno_song_id": "suno-song-id-1",
        "title": "Bài hát ví dụ",
        "generation_type": "generate",
        "completed_at": 1784000000,
        "created_at": 1783999000,
        "audio_url": "https://example.com/audio.mp3",
        "model_name": "suno-v6",
        "authorization": {
          "selectable": true
        }
      }
    ]
  }
}

Khi authorization.selectable=false, phản hồi giải thích lý do qua reason_code và reason. Bài hát đã có chứng nhận cũng trả về certificate_id và certificate_no.

2. Tạo chứng nhận

Endpoint: POST /api/music/authorization/certificates

Tham số body

Ví dụ yêu cầu

curl -X POST https://www.suno-api.io/api/music/authorization/certificates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": ["suno-song-id-1", "suno-song-id-2"],
    "confirm_risk_terms": true
  }'

Ví dụ phản hồi

{
  "success": true,
  "message": "",
  "data": {
    "certificate": {
      "id": 101,
      "certificate_no": "CERTIFICATE-NO",
      "verification_code": "VERIFY-CODE",
      "status": "issued",
      "song_count": 2,
      "identity_type_snapshot": "personal",
      "licensee_name_masked": "N*",
      "document_no_masked_snapshot": "11**************34",
      "phone_masked_snapshot": "138****0000",
      "pdf_sha256": "PDF_SHA256",
      "issued_at": 1784000100,
      "created_at": 1784000000,
      "updated_at": 1784000100,
      "download_url": "/api/music/authorization/certificates/101/download",
      "songs": []
    }
  }
}

Trong phản hồi thành công, status là issued. Nếu kết xuất PDF thất bại, chứng nhận được đánh dấu failed và các bài hát liên quan vẫn có thể gửi lại sau khi khắc phục vấn đề.

3. Tra cứu lịch sử chứng nhận

Endpoint: GET /api/music/authorization/certificates

Tham số query

Ví dụ yêu cầu

curl "https://www.suno-api.io/api/music/authorization/certificates?p=1&page_size=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Cấu trúc phản hồi

data của phản hồi là một đối tượng phân trang gồm page, page_size, total và items. Mỗi mục trong items là tóm tắt chứng nhận và kèm ảnh chụp bài hát của chứng nhận đó.

4. Tra cứu chi tiết chứng nhận

Endpoint: GET /api/music/authorization/certificates/:id

Tham số đường dẫn id là ID số của chứng nhận. Endpoint chỉ cho phép truy cập chứng nhận của chính người dùng API Key hiện tại.

Ví dụ yêu cầu

curl https://www.suno-api.io/api/music/authorization/certificates/101 \
  -H "Authorization: Bearer YOUR_API_KEY"

Cấu trúc phản hồi

Khi thành công trả về data.certificate, với các trường gồm số chứng nhận, trạng thái, thông tin người được cấp phép đã che, thời điểm phát hành, giá trị kiểm tra PDF, địa chỉ tải và ảnh chụp các bài hát đã cấp phép.

5. Tải PDF chứng nhận

Endpoint: GET /api/music/authorization/certificates/:id/download

Chỉ chứng nhận có trạng thái issued mới tải được. Yêu cầu tải vẫn cần API Key hợp lệ và chỉ tải được chứng nhận của chính bạn.

Ví dụ yêu cầu

curl https://www.suno-api.io/api/music/authorization/certificates/101/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output authorization-certificate.pdf

Phản hồi thành công là luồng tệp application/pdf; tên tệp theo Content-Disposition của backend.

Nguyên nhân thất bại thường gặp

Lưu ý

• Dùng suno_song_id do danh sách bài hát trả về; không dùng ID giữ chỗ pending:* hay ID của bảng tác vụ.
• Địa chỉ tải không phải liên kết công khai; đừng bỏ xác thực bằng API Key.
• Hồ sơ chứng nhận thuộc về người dùng tương ứng với API Key, không thể tra cứu hay tải chéo giữa các người dùng.
• Phạm vi cấp phép, điều khoản giới hạn và nội dung PDF cuối cùng tuân theo chứng nhận thực tế đã phát hành.