> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Tạo Nhạc

> Tạo các tác vụ nhạc hoặc lời bài hát, kiểm tra âm thanh cuối cùng và lưu trữ các đầu ra nhạc cho người dùng một cách an toàn.

Việc tạo nhạc là không đồng bộ. `POST /v1/music/generations` tạo một tác vụ TokenLab công khai và trả về `id` / `task_id`, `status`, và thường là `poll_url`. Ứng dụng của bạn nên lưu trữ danh tính tác vụ đó, hiển thị tiến trình và kiểm tra cho đến khi có trạng thái cuối cùng.

## Chọn Quy Trình

| Quy trình                       | Trường chính                                                   | Ghi chú                                                                      |
| ------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Bài hát hoàn chỉnh hoặc nhạc cụ | `model`, `prompt`, tùy chọn `title`, `tags`, `action: "MUSIC"` | Sử dụng khi người dùng mong đợi âm thanh cuối cùng                           |
| Chỉ lời bài hát                 | `model`, `prompt`, `action: "LYRICS"`                          | Chỉ sử dụng với các mô hình có khả năng tạo lời bài hát                      |
| Tiếp tục một clip hiện có       | `continue_clip_id`, tùy chọn `continue_at`                     | Lưu trữ danh tính clip/tác vụ công khai trước đó trước khi cung cấp tiếp tục |

Truy vấn danh mục mô hình hiện tại trước khi gửi một danh sách mô hình mã cứng:

```bash theme={null}
curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
  -H "Authorization: Bearer sk-your-api-key"
```

Các ví dụ công khai hiện tại sử dụng `suno_music` cho việc tạo nhạc. Đối với các quy trình chỉ lời bài hát, gửi `action: "LYRICS"` với một mô hình mà hợp đồng công khai của nó tài liệu hóa việc tạo lời bài hát. Xem xét các ID mô hình như là các ID TokenLab công khai, không phải là một đảm bảo rằng các trường cụ thể của nhà cung cấp là các trường hợp công khai.

## Tạo Một Tác Vụ Nhạc

```bash theme={null}
curl https://api.tokenlab.sh/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno_music",
    "prompt": "Một bản nhạc synth-pop vui tươi với giọng hát ấm áp và điệp khúc trong trẻo",
    "title": "Morning Static",
    "tags": "synth-pop, vui tươi",
    "action": "MUSIC"
  }'
```

Giữ cho các prompt, tiêu đề và thẻ có thể nhìn thấy cho người dùng và an toàn để lưu trữ. Không đặt API keys, URL riêng tư, hoặc thông tin định tuyến nội bộ vào bất kỳ trường prompt nào.

## Kiểm Tra Để Hoàn Thành

Sử dụng `poll_url` trước. Nếu khách hàng của bạn cần một tuyến đường cố định, gọi `GET /v1/tasks/{id}` với `id` hoặc `task_id` đã trả về.

```bash theme={null}
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"
```

Các trạng thái công khai mong đợi là `pending`, `processing`, `completed`, và `failed`. Một tác vụ nhạc đã hoàn thành có thể bao gồm `audio_url`, `video_url`, `title`, `lyrics`, và metadata đã chuẩn hóa. Lưu trữ các URL cuối cùng trong cơ sở dữ liệu của riêng bạn để người dùng có thể mở lại kết quả mà không cần khởi động lại việc tạo.

## Giao Diện Người Dùng Và Xử Lý Trạng Thái

* Hiển thị trạng thái đang chờ ngay sau khi tạo tác vụ.
* Kiểm tra mỗi `5-10s` cho các tác vụ dài, sau đó dừng lại khi `completed` hoặc `failed`.
* Không hiển thị trình phát cuối cùng cho đến khi tác vụ được `completed` và có `audio_url`.
* Đối với các tác vụ chỉ lời bài hát, hiển thị đầu ra văn bản riêng biệt với các tác vụ âm thanh để người dùng hiểu những gì họ đang mua.
* Khi làm mới, tiếp tục từ `task_id` đã lưu thay vì tạo một tác vụ mới.

## Thanh Toán Và Đối Chiếu

Các tác vụ nhạc có thể giữ lại một số tiền ước tính tại thời điểm tạo và thanh toán sau khi trạng thái cuối cùng được biết. Lưu trữ `request_id`, `task_id`, mô hình, điểm cuối, và `billing_transaction_id` khi nó xuất hiện. Sử dụng hồ sơ sử dụng API Quản lý để đối chiếu thay vì các ID tác vụ của nhà cung cấp.

## Lỗi Thường Gặp

| Triệu chứng                              | Nguyên nhân có thể                                             | Cách khắc phục                                                                                                         |
| ---------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Tác vụ đã tạo nhưng không có trình phát  | Tác vụ vẫn đang chờ hoặc đã hoàn thành mà không có `audio_url` | Tiếp tục kiểm tra cho đến khi có trạng thái cuối cùng, sau đó xử lý đầu ra thiếu như một công việc người dùng thất bại |
| Bài hát trùng lặp sau khi làm mới        | Giao diện người dùng đã tạo lại tác vụ thay vì tiếp tục        | Lưu trữ và sử dụng lại `task_id`                                                                                       |
| Tác vụ lời bài hát không trả về âm thanh | `action: "LYRICS"` chỉ là văn bản                              | Tách biệt các đường dẫn UI lời bài hát và nhạc                                                                         |
| Tham số không được hỗ trợ                | Trường không có trong hợp đồng công khai của mô hình           | Xóa các trường cụ thể của nhà cung cấp hoặc chọn một mô hình tài liệu hóa chúng                                        |

## Tài Liệu API

| Chủ đề                | Tài liệu tham khảo                                               |
| --------------------- | ---------------------------------------------------------------- |
| Tạo Nhạc              | [Tạo Nhạc](/vi/api-reference/music/create-music)                 |
| Lấy Trạng Thái Nhạc   | [Lấy Trạng Thái Nhạc](/vi/api-reference/music/get-music-status)  |
| Lấy Trạng Thái Tác Vụ | [Lấy Trạng Thái Tác Vụ](/vi/api-reference/tasks/get-task-status) |
| Danh Sách Mô Hình     | [Danh Sách Mô Hình](/vi/api-reference/models/list-models)        |
| Thanh Toán & Giá Cả   | [Thanh Toán & Giá Cả](/vi/guides/billing)                        |