Suno API

RouteAPI cung cấp REST API thống nhất cho việc tạo nhạc AI Suno. Tạo nhạc từ văn bản, kéo dài bài hát, nhân bản giọng nói, tách stems và nhiều hơn nữa.

Tổng quan quy trình

Tạo nhạc Suno là bất đồng bộ. Quy trình điển hình:

Gửi tác vụ đến /suno/audios → nhận task_id
Đợi 2-3 giây trước khi bắt đầu thăm dò
Thăm dò mỗi 3-5 giây qua /suno/tasks với action: "retrieve"
Khi status trở thành success → lấy audio_url

Trạng thái tác vụ

Trạng thái	Ý nghĩa	Bước tiếp theo
`submitted`	Đã gửi, đang chờ	Tiếp tục thăm dò
`queued`	Đang trong hàng đợi	Tiếp tục thăm dò
`in_progress`	Đang tạo	Tiếp tục thăm dò
`success`	✅ Hoàn thành	Lấy `audio_url` từ phần tử đầu tiên của mảng `data`
`failure`	❌ Thất bại	Kiểm tra trường `error`

Bắt đầu nhanh

Bước 1: Gửi tác vụ

curl -X POST "https://api.routeapi.ai/suno/audios" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chirp-v5-5",
    "prompt": "A cheerful summer pop song with piano and guitar",
    "async": true
  }'

Bước 2: Thăm dò kết quả

curl -X POST "https://api.routeapi.ai/suno/tasks" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "retrieve", "id": "task_xxxxx" }'

Bước 3: Lấy âm thanh

{
  "id": "task_xxxxx",
  "task_id": "task_xxxxx",
  "status": "success",
  "data": [
    {
      "id": "audio_1",
      "audio_url": "https://cdn.suno.ai/xxx.mp3",
      "duration": 183.5
    }
  ]
}

Mô hình được hỗ trợ

ID mô hình	Độ dài tối đa	Giới hạn lyric	Giới hạn style
`chirp-v5-5`	8 phút	5000 ký tự	1000 ký tự
`chirp-v5`	8 phút	5000 ký tự	1000 ký tự
`chirp-v4`	150 giây	3000 ký tự	200 ký tự

POST /suno/audios

Endpoint cốt lõi cho các thao tác âm thanh: trường action chọn thao tác và body chứa các trường mà thao tác đó cần.

Tham số cốt lõi

Trường	Loại	Mặc định	Mô tả
`model`	string	`chirp-v4`	Mô hình tạo, khuyến nghị `chirp-v5-5`
`action`	string	`generate`	Loại thao tác
`async`	boolean	—	Khuyến nghị mạnh `true`. Chỉ khi truyền rõ `false` mới dùng nhánh đồng bộ; nếu bỏ trường này, trường không được chuyển tiếp và giá trị mặc định của upstream được áp dụng

Các loại hành động

Action	Mô tả	Trường bắt buộc
`generate`	Tạo nhạc mới từ prompt	`prompt`
`extend`	Kéo dài âm thanh hiện có	`audio_id` + `continue_at`
`cover`	Diễn giải lại bài hát hiện có	`audio_id`
`stems`	Tách thành giọng hát + nhạc nền	`audio_id`
`remaster`	Remaster âm thanh để cải thiện chất lượng	`audio_id`

Để biết đầy đủ các loại hành động, vui lòng tham khảo tài liệu tiếng Anh hoặc tiếng Trung.

POST /suno/tasks

Truy vấn trạng thái và kết quả tác vụ.

curl -X POST "https://api.routeapi.ai/suno/tasks" \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "retrieve", "id": "task_xxxxx" }'

Các endpoint khác

Endpoint	Phương thức	Mô tả
`/suno/lyrics`	POST	Tạo lời bài hát
`/suno/upload`	POST	Tải lên tệp âm thanh bên ngoài
`/suno/persona`	GET/POST	Quản lý persona giọng nói
`/suno/wav`	POST	Xuất định dạng WAV

Để biết tham chiếu API đầy đủ, vui lòng tham khảo tài liệu tiếng Anh hoặc tiếng Trung.

Lỗi

Lỗi phát sinh sau khi yêu cầu tới trình xử lý tác vụ dùng body của tác vụ:

{ "code": "invalid_request", "message": "prompt_empty (request id: ...)", "data": null }

Lỗi xác thực và định tuyến xảy ra trước trình xử lý đó và giữ body kiểu OpenAI {"error": {"message": "...", "type": "...", "code": "..."}}. Xem Lỗi thường gặp.

Mã trạng thái	Mã lỗi	Nguyên nhân
400	`invalid_request`	Thiếu trường bắt buộc cho endpoint hoặc action; `message` nêu tên trường (ví dụ `prompt_empty` cho `/suno/lyrics`, hoặc `audio_id_vocal_start_vocal_end_required` cho `/suno/vox`)
400	`task_not_exist`	`action: "retrieve"` với `id` không thuộc tác vụ của bạn
401	—	API Key thiếu, không hợp lệ hoặc đã hết hạn (body kiểu OpenAI)
403	`insufficient_user_quota`	Số dư tài khoản hoặc quota của Key không đủ cho khoản tạm giữ
429	—	Kênh upstream báo giới hạn tốc độ hoặc quá tải; RouteAPI thay thế thông điệp gốc của nhà cung cấp
502	`acedata_suno_request_failed`	Upstream đã nhận nhưng từ chối yêu cầu: kiểm duyệt nội dung, `audio_id` không tồn tại, action không hỗ trợ. `message` chứa giải thích của upstream
502	`upstream_task_id_missing`	Upstream trả về 2xx nhưng không có task ID nên không thể thăm dò; khoản tạm giữ được hoàn lại
503	`get_channel_failed`	Kênh đứng sau tác vụ bị đánh giá là lỗi nghiêm trọng (ví dụ tài khoản upstream không dùng được); RouteAPI thay thế thông điệp gốc của nhà cung cấp. (Mô hình không có kênh nào bị từ chối trước khi vào trình xử lý tác vụ với `503 model_not_found` và body kiểu OpenAI)
4xx / 5xx	`fail_to_fetch_task`	Upstream trả về mã ngoài 2xx; mã trạng thái và body được chuyển tiếp, khoản tạm giữ được hoàn lại

Tác vụ thất bại (thăm dò trả về failure) cũng được hoàn khoản tạm giữ; lý do nằm ở trường error và message của bản ghi tác vụ.

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

Q: Nên sử dụng mô hình nào?
Sử dụng chirp-v5-5 (mới nhất và mạnh nhất).

Q: Tạo mất bao lâu?
generate thường mất 15-40 giây.

Q: Tôi có thể sử dụng audio_url trực tiếp không?
Có, liên kết CDN sẵn sàng để phát hoặc tải xuống.