Tài liệu

Tạo tác vụ âm thanh

Cập nhật vào 2026-08-30

Tổng quan giao diện

Việc tạo nhạc Suno và FlowMusic là thao tác bất đồng bộ:

Gọi POST /v1/audios/tasks gửi tác vụ
Lưu ID tác vụ công khai trong phản hồi
Gọi GET /v1/tasks/{task_id} tra cứu trạng thái và kết quả

Base URL là https://api.rokoapi.com/v1, mọi yêu cầu đều phải kèm theo Authorization: Bearer $API_KEY.

Mô hình khả dụng

suno-v3.5
suno-v4
suno-v4.5
suno-v4.5-all
suno-v4.5-plus
suno-v5
suno-v5.5
flowmusic-lyria-3-pro
flowmusic-lyria-3.5

Phạm vi khả dụng thực tế dựa trên /v1/models và nhóm mà khóa API thuộc về.

Tạo nhạc bằng FlowMusic Lyria

FlowMusic chỉ nhận các trường được công bố trong danh mục mô hình. Hãy cung cấp ít nhất một trong hai trường prompt hoặc metadata.lyrics; không gửi tham số không có trong metadata của mô hình.

{
  "model": "flowmusic-lyria-3.5",
  "prompt": "nhạc ambient điện ảnh với bộ dây ấm và piano nhẹ nhàng",
  "duration": 30,
  "metadata": {
    "lyrics": "[Verse]\nNeon rain falls softly tonight",
    "title": "Neon Rain",
    "bpm": 120,
    "seed": "42"
  }
}

Tạo bài hát

curl https://api.rokoapi.com/v1/audios/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v5.5",
    "action": "generate",
    "mode": "easy",
    "prompt": "Một ca khúc pop mùa hè sôi động với giọng nữ và tiếng guitar tươi sáng"
  }'

action Nếu bỏ qua, mặc định là generate, mode Nếu bỏ qua, mặc định là easy.

Chế độ nâng cao

{
  "model": "suno-v5.5",
  "action": "generate",
  "mode": "advanced",
  "lyrics": "[Verse]\nWalking through the neon rain...",
  "style": "synth-pop, female vocal, 120 bpm",
  "title": "Neon Rain",
  "instrumental": false
}

advanced Trong chế độprompt, lyrics, style phải cung cấp ít nhất một mục. Khi đặt lyrics_model thì bắt buộc phải cung cấp prompt.

Tiếp tục viết đoạn nhạc

{
  "model": "suno-v5.5",
  "action": "extend",
  "continue_clip_id": "clip_123",
  "continue_at": 90,
  "prompt": "Chuyển sang điệp khúc mạnh mẽ hơn"
}

extend Bắt buộc phải cung cấp continue_clip_id và continue_at.

Phản hồi khi gửi

Gửi thành công sẽ trả về HTTP 202: ```json { “id”: “task_public_id”, “object”: “audio.generation.task”, “status”: “queued”, “upstream”: “Suno Task API” }


Các truy vấn sau luôn sử dụng `id`công khai ở đây, không sử dụng ID tác vụ nội bộ của nhà cung cấp.

## Tra cứu tác vụ

```bash
curl https://api.rokoapi.com/v1/tasks/task_public_id \
  -H "Authorization: Bearer $API_KEY"

Các trạng thái phổ biến bao gồm queued, in_progress, completed và failed. Sau khi tác vụ hoàn tất, kết quả sẽ cung cấp URL âm thanh được tạo; nên tăng dần khoảng thời gian tra cứu để tránh truy vấn tần suất cao.

Lưu trữ kết quả và địa chỉ phương tiện

Khi máy chủ bật lưu trữ phương tiện, việc tác vụ thành công không có nghĩa là địa chỉ tệp đã ổn định. Hệ thống phía sau nên tiếp tục tra cứu cho đến khi archive_status trở thành ready(hoặc partialtrong trường hợp thành công một phần), sau đó lưu trữ assets[].url.

Âm thanh, ảnh bìa, video và lời bài hát sau khi lưu trữ sẽ được chuyển sang CDN của nền tảng (https://cdn.rokoapi.com), trả về địa chỉ HTTPS công khai không thể đoán trước, không cần mang API Token để truy cập trực tiếp.

Thời gian lưu trữ

Phương tiện lưu trữ mặc định được giữ 24 giờ, sau khi hết hạn đối tượng sẽ bị xóa, trạng thái tài sản tương ứng trở thành expired.
Thời gian hết hạn của mỗi tài sản xem tại assets[].expires_at(dấu thời gian cấp giây Unix).
Nếu hệ thống phía sau cần sử dụng lâu dài, nên tự tải xuống và lưu trữ trong kho lưu trữ của mình trong vòng 24 giờ; không nên coi địa chỉ CDN của nền tảng là liên kết vĩnh viễn.
archive_status trở thành expired sau đó, assets[].url sẽ không còn khả dụng.

Ví dụ phản hồi truy vấn:

{
  "code": "success",
  "data": {
    "task_id": "task_public_id",
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://cdn.rokoapi.com/media/2026/07/abcdef.mp3",
    "archive_status": "ready",
    "assets": [
      {
        "output_id": "clip-1",
        "kind": "audio",
        "title": "Neon Rain",
        "url": "https://cdn.rokoapi.com/media/2026/07/abcdef.mp3",
        "content_type": "audio/mpeg",
        "size": 3456789,
        "expires_at": 1753862400,
        "status": "ready"
      },
      {
        "output_id": "clip-1",
        "kind": "cover",
        "title": "Neon Rain",
        "url": "https://cdn.rokoapi.com/media/2026/07/coverxyz.jpg",
        "content_type": "image/jpeg",
        "expires_at": 1753862400,
        "status": "ready"
      },
      {
        "output_id": "clip-1",
        "kind": "lyrics",
        "title": "Neon Rain",
        "url": "https://cdn.rokoapi.com/media/2026/07/lyricsxyz.txt",
        "content_type": "text/plain; charset=utf-8",
        "expires_at": 1753862400,
        "status": "ready"
      }
    ]
  }
}

Ghi chú:

archive_status: pending / processing / ready / partial / failed / expired
assets: Một tác vụ có thể chứa nhiều clip, mỗi clip có thể có audio, cover, video, lyrics
result_url: Địa chỉ công khai của tệp âm thanh đã lưu trữ đầu tiên; trước khi hoàn tất lưu trữ, có thể vẫn là URL tạm thời từ nhà cung cấp
assets[].expires_at: Thời gian dự kiến xóa tệp này; mặc định khoảng 24 giờ sau khi lưu trữ hoàn tất
URL phương tiện công khai không thể đoán trước, không cần kèm Token nền tảng; mặc định giữ lại 24 giờ trước khi xóa**
Các trang web hạ nguồn chỉ nên lưu trữ URL công khai sau khi lưu trữ (và sao lưu trước khi hết hạn), không nên phụ thuộc vào địa chỉ CDN tạm thời từ nhà cung cấp

Gợi ý truy vấn tuần tự:

# Tiếp tục truy vấn sau khi thành công cho đến khi archive_status=ready
curl https://api.rokoapi.com/v1/tasks/task_public_id \
  -H "Authorization: Bearer $API_KEY"

Tham số

Tham số	Kiểu	Mô tả
`model`	string	ID mô hình Suno, bắt buộc
`action`	string	`generate` hoặc `extend`
`mode`	string	Chế độ tạo:`easy` hoặc `advanced`
`prompt`	string	Mô tả bài hát bằng ngôn ngữ tự nhiên
`lyrics`	string	Lời bài hát tùy chỉnh
`style`	string	Mô tả thể loại, cảm xúc, nhạc cụ, v.v.
`instrumental`	boolean	Có tạo nhạc không lời không
`title`	string	Tiêu đề bài hát
`vocal_gender`	string	Tùy chọn giọng hát
`continue_clip_id`	string	ID đoạn nguồn để tiếp tục viết
`continue_at`	number	Tiếp tục viết từ số giây chỉ định của đoạn nguồn, không được âm
`timeout_ms`	integer	Thời gian chờ tác vụ nhà cung cấp, phạm vi 10.000–7.200.000 mili giây

Thanh toán

Các phiên bản Suno mặc định tính phí theo lần, giá mặc định trong mã hiện tại là $0.06. Giá mô hình và hệ số nhóm trong bảng điều khiển có thể ghi đè giá mặc định, lấy theo hiển thị trên trang định giá làm chuẩn.

Khác biệt so với giao diện Suno cũ

/v1/audios/tasks sử dụng suno-v* ID mô hình và giao diện truy vấn tác vụ thống nhất. Phiên bản cũ /suno/submit sử dụng suno_music, suno_lyrics và các tên mô hình khác; không được trộn lẫn hai bộ giao diện và tên mô hình này.

Lỗi thường gặp

400: đường dẫn, action, mode hoặc tham số bắt buộc không chính xác
403: nhóm khóa API không có quyền truy cập mô hình hoặc số dư không đủ
404: ID tác vụ không tồn tại, hoặc mô hình chưa được kích hoạt trong kênh khả dụng
502: nhà cung cấp trả về phản hồi không hợp lệ hoặc dịch vụ tác vụ tạm thời không khả dụng