API nhân bản giọng nói và tạo nhạc với giọng chỉ định (không khuyến nghị)

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

⛔ Chuỗi cũ, không khuyến nghị cho tích hợp mới. Trang này mô tả chuỗi persona ban đầu (voice_task_id / generate-with-voice). Nó vẫn hoạt động, nhưng không còn được khuyến nghị cho khách hàng; menu bên trái đánh dấu là "không khuyến nghị".

Với tích hợp mới, hãy dùng 【Khuyến nghị】 API hồ sơ giọng nói: tạo hồ sơ giọng nói từ một mẫu giọng (POST /api/music/voice-profile/create), rồi dùng nó để cover một bài hát chỉ định hoặc hát một bài mới. Hồ sơ giọng nói là tài nguyên hạng nhất: có thể liệt kê, truy vấn và xóa, và audio gốc được giữ vĩnh viễn.

Nếu sản phẩm của bạn cần vòng lặp đầy đủ "tạo giọng → dùng lại lâu dài → cover", hãy ưu tiên chuỗi mới.

Lưu ý quan trọng: giọng đã nhân bản có thể hết hạn.

voice_id / voice_task_id do nhân bản giọng nói tạo ra không phải tài nguyên dùng được mãi: chúng có thể ngừng hoạt động do thời hạn hiệu lực, trạng thái tài khoản hoặc thay đổi trạng thái giọng. Bên tích hợp không được nhân bản một lần rồi dùng mãi ID giọng đã lưu trong bộ nhớ đệm cục bộ.

Cách làm được khuyến nghị:

• Lưu voice_task_id, voice_id, is_available, updated_at và thời điểm tạo thành công gần nhất.
• Trước mỗi lần tạo nhạc bằng giọng đã nhân bản, hãy gọi GET /api/voice/clone/tasks/{voice_task_id} hoặc POST /api/voice/clone/tasks/{voice_task_id}/check và xác nhận is_available=true.
• Nếu endpoint báo giọng không dùng được, tác vụ không tồn tại hoặc trả về selected voice is not ready, hãy yêu cầu người dùng nhân bản lại hoặc chọn giọng khác đang dùng được.
• Không hứa với người dùng cuối rằng giọng đã nhân bản là "tài sản vĩnh viễn"; hãy hiển thị trong giao diện sản phẩm rằng "giọng có thể hết hạn và cần xác thực lại hoặc nhân bản lại".

Mô tả endpoint

Nhóm endpoint này tạo một giọng có thể dùng lại và tạo bài hát bằng giọng đó. Bên gọi chỉ cần API Key do nền tảng cấp; máy chủ xử lý việc gửi tác vụ, đồng bộ trạng thái, tính phí và tải xuống.

Xác thực: Authorization: Bearer YOUR_API_KEY

Tính phí:

• Kiểm tra giọng, nhân bản giọng, truy vấn trạng thái, xóa và tải xuống: miễn phí.
• Lối vào nhân bản một bước trong không gian làm việc: cố định 5 ¥ mỗi lần gọi; tự động hoàn tất kiểm tra giọng gốc và audio xác minh thứ hai, hoàn tiền nếu thất bại.
• Tự động chuyển tiếp sang audio xác minh sau khi nhân bản thường: cố định 5 ¥ mỗi lần gọi; thất bại thì hoàn tiền theo luồng hiện có.
• Tạo bài hát bằng giọng đã nhân bản: có phí, cố định 1,2 ¥ mỗi lần gọi; mỗi lần gọi thường trả về 2 tác vụ chỗ giữ chỗ.
• Khi bật Max Mode (max_mode: true trong POST /api/music/generate-with-voice), mức 1,2 ¥ mỗi lần gọi được tính gấp 2, tức 2,4 ¥ mỗi lần gọi; tạo nhạc bằng giọng cũng hỗ trợ variety (0-4, không phụ phí); quy tắc giá trị nằm ở mục "Tham số nâng cao" trong tổng quan API mới.

Luồng gọi

1. Gọi POST /api/voice/clone/validate để tải giọng gốc lên và nhận voice_task_id.
2. Chờ hoặc thăm dò GET /api/voice/clone/tasks/{voice_task_id} cho tới khi nhận validate_info.
3. Người dùng đọc to văn bản đó và ghi audio xác minh.
4. Gọi POST /api/voice/clone/tasks/{voice_task_id}/generate để gửi audio xác minh.
5. Gọi POST /api/voice/clone/tasks/{voice_task_id}/check hoặc tiếp tục truy vấn tác vụ cho tới khi is_available=true.
6. Gọi POST /api/music/generate-with-voice để tạo bài hát bằng giọng đó.
7. Endpoint tạo nhạc trả về tác vụ chỗ giữ chỗ trước; khi tạo xong và có song_id thật, bạn có thể dùng các endpoint tải xuống để lấy một tệp hoặc một gói.
8. (Tùy chọn) Khi không cần giọng nữa, gọi DELETE /api/voice/clone/voices/{voice_task_id} để xóa; ngữ nghĩa ở mục 6.

Còn có nhân bản một bước: ở trang ghi âm/tải giọng gốc đầu tiên trong không gian làm việc, bạn có thể chọn hoàn tất trong một bước; hệ thống làm kiểm tra và tạo giọng cùng lúc, nên bạn không phải ghi audio xác minh thứ hai; giá 5 ¥ mỗi lần gọi và hoàn tiền nếu thất bại.

Trường của tác vụ giọng

1. Gửi giọng gốc để kiểm tra

Endpoint: POST /api/voice/clone/validate

Tham số body

vocal_end_s - vocal_start_s phải đạt yêu cầu tối thiểu của đoạn giọng. Hãy tải lên bản ghi giọng rõ ràng, không có nhạc đệm hay tạp âm rõ rệt.

Ví dụ yêu cầu

curl -X POST https://www.suno-api.io/api/voice/clone/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://example.com/source-voice.wav",
    "voice_name": "Giọng nữ tiếng Trung của tôi",
    "description": "Giọng nữ tiếng Trung trong trẻo, tự nhiên",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

Ví dụ phản hồi

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Giọng nữ tiếng Trung của tôi",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. Truy vấn tác vụ giọng

Endpoint: GET /api/voice/clone/tasks/{voice_task_id}

Ví dụ yêu cầu

curl https://www.suno-api.io/api/voice/clone/tasks/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Ví dụ phản hồi

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Giọng nữ tiếng Trung của tôi",
      "validate_info": "Hãy đọc to văn bản xác minh được trả về ở đây",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. Tạo lại văn bản xác minh

Endpoint: POST /api/voice/clone/tasks/{voice_task_id}/regenerate

Gọi khi văn bản xác minh không phù hợp để đọc to hoặc khi cần kiểm tra lại.

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. Gửi audio xác minh và tạo giọng

Endpoint: POST /api/voice/clone/tasks/{voice_task_id}/generate

Tham số body

Ví dụ yêu cầu

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify_url": "https://example.com/verify-voice.wav",
    "voice_name": "Giọng nữ tiếng Trung của tôi"
  }'

5. Kiểm tra giọng có dùng được không

Endpoint: POST /api/voice/clone/tasks/{voice_task_id}/check

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Khi tác vụ dùng được, is_available trong phản hồi là true và trả về voice_id.

6. Xóa giọng

Endpoint: DELETE /api/voice/clone/voices/{voice_task_id}

Tính phí: miễn phí.

curl -X DELETE https://www.suno-api.io/api/voice/clone/voices/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Ví dụ phản hồi

{
  "success": true,
  "message": "",
  "data": {
    "voice_task_id": 123,
    "deleted": true
  }
}

Sau khi xóa thì thế nào

• Không thể dùng để tạo bài mới nữa: gọi POST /api/music/generate-with-voice với voice_task_id này (hoặc voice_id của nó) sẽ bị từ chối với thông báo selected voice is not ready, không tính phí.
• Các bài đã tạo bằng giọng này hoàn toàn không bị ảnh hưởng: phát, tải xuống, nối tiếp, thay thế và tách track vẫn như cũ.
• Tác vụ giọng này biến mất khỏi truy vấn: GET /api/voice/clone/tasks/{voice_task_id} trả về record not found.
• Audio gốc được giữ theo chính sách lưu trữ vĩnh viễn của nền tảng (từ 2026-09-23, xóa không còn dọn mẫu giọng bạn đã tải lên), nhưng điều đó không có nghĩa là khôi phục được: tác vụ cũ đã kết thúc, muốn tiếp tục dùng cùng giọng thì phải đi lại toàn bộ luồng nhân bản và sẽ nhận voice_task_id mới.
• Xóa lặp lại: xóa lại cùng tác vụ sẽ trả về record not found (nó đã ở trạng thái đã xóa và không tra được nữa).

7. Tạo bài hát bằng giọng đã nhân bản

Endpoint: POST /api/music/generate-with-voice

Tính phí: 1,2 ¥ mỗi lần gọi.

Tham số body

Hỗ trợ suno-v6, suno-v6-wild và suno-v6-mini; mô hình để trống được xử lý như suno-v6. Các mô hình V5/V5.5 cũ đã ngừng, nhưng tác vụ lịch sử có thể vẫn hiển thị tên mô hình cũ.

Cấu trúc yêu cầu dùng chung cũng phân tích các trường tương thích Create UI như task, soundType, soundLoop, soundBpm, soundKey, voiceTaskId, voiceId, nhưng chúng không phải tham số khách hàng hợp lệ của endpoint này: tác vụ giọng phải truyền qua voice_task_id, xác minh giọng tùy chọn qua voice_id, và việc tạo nhạc bằng giọng không bao giờ đọc các trường sound.

Cách điền tham số tạo nhạc

• Khi customMode=false, prompt chứa mô tả bài hát; khi customMode=true, prompt chứa lời đầy đủ, và style cùng title cũng phải điền. Đừng gửi lời bài hát vào trường mô tả của chế độ cảm hứng, cũng đừng coi mô tả bài hát là lời ở chế độ nâng cao.
• weirdnessConstraint và styleWeight là tỷ lệ thập phân từ 0.0 đến 1.0; không thể truyền 50 hay 50%. 0.5 là giá trị cân bằng; bỏ trống nghĩa là "không chỉ định", còn 0 là giá trị rõ ràng hợp lệ.
• vocalGender chỉ nhận m, male, f hoặc female. instrumental ở đây chỉ là trường tương thích: tạo nhạc bằng giọng đã nhân bản luôn được xử lý như bài có giọng hát.
• waitAudio không đổi hành vi ở đây; endpoint luôn trả về tác vụ chỗ giữ chỗ theo cách bất đồng bộ. audio_url trống trong kết quả đầu tiên là bình thường: hãy truy vấn bằng client_request_id và chỉ đọc địa chỉ audio sau khi kết quả hoàn tất.

Tham số header

Hành vi của Idempotency-Key:

• Yêu cầu đầu tiên ghi một bản ghi bất biến trước khi tính phí;
• Nếu cùng khóa với cùng yêu cầu đã hoàn tất, phản hồi tiếp nhận đầu tiên được phát lại, không tính phí lần hai và không tạo tác vụ thứ hai;
• Cùng khóa nhưng nội dung yêu cầu khác sẽ bị từ chối;
• Cùng khóa vẫn đang xử lý sẽ trả về lỗi "đang xử lý" ổn định và chỉ trả client_request_id an toàn khi đã được tạo;
• Nếu yêu cầu đầu tiên với một khóa thất bại thì giữ trạng thái thất bại; thử lại phải dùng khóa mới.

Điều kiện cover qua sourceClipId

Cover từ nguồn trong API khách hàng được xử lý hoàn toàn ở phía máy chủ: quyền truy cập bài hát nguồn do máy chủ giải quyết và khách hàng không truyền thông tin tài khoản. Có thực hiện được hay không do phản hồi thực tế của endpoint quyết định.

Nguồn phải thuộc người dùng API hiện tại, là bài hát đã hoàn tất trong không gian làm việc và không ở trạng thái pending:, đồng thời có audio dùng được. Hỗ trợ tạo thường, nguồn tải lên thường và bài cuối của tải lên tăng cường; bản ghi trung gian của tải lên tăng cường bị từ chối trước khi tính phí. Máy chủ chỉ nhận ID bài hát nguồn do khách hàng gửi và không bao giờ nhận ID tài khoản; nguồn không dùng được hoặc chưa xong sẽ trả lỗi trước khi tính phí.

Ví dụ yêu cầu

curl -X POST https://www.suno-api.io/api/music/generate-with-voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_task_id": 123,
    "customMode": true,
    "prompt": "Viết một bài nhạc pop Trung Quốc về bờ biển trong đêm hè",
    "style": "Mandopop, warm piano, emotional",
    "title": "Gió biển đêm hè",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

Ví dụ phản hồi

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "items": [
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Gió biển đêm hè",
        "prompt": "Viết một bài nhạc pop Trung Quốc về bờ biển trong đêm hè"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Gió biển đêm hè",
        "prompt": "Viết một bài nhạc pop Trung Quốc về bờ biển trong đêm hè"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

Về tác vụ chỗ giữ chỗ và song_id cuối cùng

generate-with-voice là endpoint tạo nhạc bất đồng bộ. Phản hồi thành công chỉ nghĩa là tác vụ tạo nhạc đã được gửi, không phải bài hát đã xong.

Ý nghĩa các trường quan trọng trong phản hồi:

Lưu ý: placeholder_id bắt đầu bằng pending: không thể dùng làm song_id cuối cùng, cũng không thể truyền trực tiếp vào /api/music/query hay các endpoint tải xuống. Gọi /api/music/query chỉ với các giá trị pending:* có thể trả về mảng rỗng [], vì bài hát thật chưa xong hoặc tác vụ chỗ giữ chỗ chưa được thay bằng ID bài hát cuối cùng.

Ví dụ sai:

{
  "song_ids": "pending:cu_1780480000_abcd1234:0"
}

Luồng đúng:

1. Gọi POST /api/music/generate-with-voice để gửi tác vụ tạo nhạc bằng giọng.
2. Lưu client_request_id, items[].placeholder_id và items[].client_request_index từ phản hồi.
3. Thăm dò GET /api/music/generate-with-voice/results?client_request_id=cu_xxx.
4. Khi items[].song_id có giá trị và không bắt đầu bằng pending:, gọi /api/music/query, /api/music/download-file hoặc /api/music/download-all.

Phiên bản hiện tại bổ sung endpoint truy vấn công khai:

GET /api/music/generate-with-voice/results?client_request_id=cu_xxx

Nó trả về kết quả tác vụ của cùng client_request_id thuộc người dùng hiện tại, để khách hàng tự tra song_id cuối cùng. Trong danh sách trả về:

• song_id là ID bài hát thật;
• placeholder_id chỉ xuất hiện khi tác vụ vẫn ở trạng thái chỗ giữ chỗ;
• giá trị bắt đầu bằng pending: không dùng được với /api/music/query hay các endpoint tải xuống.

Nếu bạn chỉ lưu client_request_id hoặc ID chỗ giữ chỗ pending:*, hãy gọi endpoint kết quả này trước; nếu vẫn chưa tra được song_id thật, hãy gửi client_request_id cho hỗ trợ kỹ thuật để định vị.

Truy vấn kết quả tạo nhạc bằng giọng

Endpoint: GET /api/music/generate-with-voice/results

Tính phí: miễn phí.

Tham số truy vấn

Ví dụ yêu cầu

curl -X GET "https://www.suno-api.io/api/music/generate-with-voice/results?client_request_id=cu_1780480000_abcd1234" \
  -H "Authorization: Bearer YOUR_API_KEY"

Ví dụ phản hồi khi đang tạo

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "processing",
    "items": [
      {
        "song_id": "",
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "processing",
        "type": "voice_generate",
        "title": "Gió biển đêm hè"
      }
    ]
  }
}

Ví dụ phản hồi khi hoàn tất

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "completed",
    "items": [
      {
        "song_id": "song_abc123",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "completed",
        "type": "voice_generate",
        "title": "Gió biển đêm hè",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

Ý nghĩa status cấp cao nhất

8. Tải một tệp

Endpoint: POST /api/music/download-file

Tham số body

Ví dụ yêu cầu

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123",
    "kind": "audio"
  }' \
  --output song.mp3

Phản hồi là luồng tệp; Content-Type và tên tệp theo giá trị backend trả về.

9. Tải tài nguyên bài hát dạng gói

Endpoint: POST /api/music/download-all

Tham số body

Ví dụ yêu cầu

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123"
  }' \
  --output song.zip

Gói thường chứa audio, ảnh bìa và metadata.json; nếu loại tài nguyên nào chưa được tạo thì sẽ không có trong tệp nén.

Lỗi thường gặp

Lỗi của nhóm này luôn trả về HTTP 200: hãy đánh giá kết quả bằng trường success trong nội dung (false là thất bại, nguyên nhân ở message) và đừng chỉ nhìn mã trạng thái HTTP. Ngữ nghĩa đầy đủ của việc xóa giọng (còn dùng được không, có khôi phục được không) ở mục 6.