# Nhân bản giọng

Tạo giọng riêng từ một bản ghi ngắn, với xác nhận đồng ý của người nói.

`POST /v1/audio/voices` tạo một giọng nhân bản từ bản ghi ngắn. Nhân bản giọng **không tính phí**; dùng giọng đó để đọc thì tính phí như bình thường.

## Đồng ý (consent)

Bạn chỉ được nhân bản giọng của chính mình, hoặc giọng của người đã cho phép bạn. Mỗi request phải gửi `consent=true`, nghĩa là bạn xác nhận câu:

> I confirm I own this voice or have the speaker's permission to clone it.

Hệ thống lưu lại lời xác nhận, thời điểm, địa chỉ IP và khóa API đã dùng. Bản ghi đồng ý được giữ lại cả khi bạn xóa giọng. Thiếu `consent=true`: `422 consent_required`.

## Tạo giọng

Gửi `multipart/form-data`:

| Field | Bắt buộc | Ghi chú |
|---|---|---|
| `name` | có | 1-40 ký tự `a-z`, `0-9`, `_`, `-`. Không trùng giọng có sẵn, duy nhất trong tài khoản. Đây là giá trị bạn truyền vào `voice`. |
| `consent` | có | Phải là `true`. |
| `ref_text` | có | Lời chính xác của những gì được nói trong bản ghi, 1-500 ký tự. |
| `audio_sample` | có | File WAV hoặc MP3, tối đa 10 MiB và 30 giây. |
| `display_name` | không | Tên hiển thị, 1-60 ký tự; mặc định bằng `name`. Sai độ dài trả `400 voice_display_name_invalid`. |
| `description` | không | Mô tả, tối đa 500 ký tự (`400 voice_description_too_long`). Được trả về ở cả `description.vi` và `description.en`. |
| `anchors` | không | Mảng JSON tối đa 5 chuỗi (mỗi chuỗi đến 500 ký tự) giúp hoàn thiện hồ sơ giọng. |

```bash
curl https://api.example.com/v1/audio/voices \
  -H "Authorization: Bearer $SOTA_API_KEY" \
  -F name=my_narrator \
  -F consent=true \
  -F "ref_text=Xin chào, đây là giọng đọc mẫu của tôi." \
  -F audio_sample=@sample.wav
```

```json
{
  "id": "voice_01jd8y7n4t2k6m8p0q1r3s5u7w",
  "object": "voice",
  "name": "my_narrator",
  "display_name": "my_narrator",
  "type": "cloned",
  "profile_state": "queued",
  "created_at": 1763366400,
  "tagline": null,
  "description": null,
  "category": null,
  "gender": null,
  "age": null,
  "accent": null,
  "languages": [],
  "featured": false,
  "verified": false,
  "sort_order": 0,
  "preview_url": null
}
```

Gợi ý cho bản ghi: một người nói, phòng yên tĩnh, không nhạc nền, nói tự nhiên, và `ref_text` khớp từng chữ với lời nói.

## Trạng thái hồ sơ giọng

Giọng **dùng được ngay** khi request trả về: truyền `name` vào `voice` của `POST /v1/audio/speech`, WebSocket hoặc job. Trong lúc đó hồ sơ giọng được hoàn thiện dần, thể hiện qua `profile_state`:

| `profile_state` | Ý nghĩa |
|---|---|
| `queued` | Đang chờ xử lý hồ sơ. |
| `building` | Đang hoàn thiện hồ sơ. |
| `ready` | Hồ sơ đã hoàn thiện. Giọng có sẵn luôn ở trạng thái này. |
| `failed` | Không hoàn thiện được hồ sơ. |

Giọng dùng được ở mọi trạng thái; trạng thái chỉ cho biết hồ sơ đã được tinh chỉnh tới đâu. Theo dõi bằng `GET /v1/audio/voices/{id}`.

## Giới hạn và lỗi

| Trường hợp | Lỗi |
|---|---|
| Đã có tối đa số giọng nhân bản (mặc định 10 mỗi tài khoản) | `409 voice_limit` |
| `name` đã có trong tài khoản | `409 voice_name_taken` |
| File quá 10 MiB | `413 sample_too_large` |
| File dài quá 30 giây | `422 sample_too_long` |
| Không phải WAV hoặc MP3 hợp lệ | `422 unsupported_audio` |
| Thiếu `consent=true` | `422 consent_required` |
| Tài khoản bị tạm khóa | `403 account_suspended` |

## Liệt kê và xóa

- `GET /v1/audio/voices`: mọi giọng có sẵn đang hiển thị (theo thứ tự danh mục), sau đó là các giọng bạn đã nhân bản (mới nhất trước), trong một response. Giọng có sẵn kèm `display_name`, `tagline`, `description`, `category`, `gender`, `age`, `accent`, `languages`, `featured`, `verified`, `sort_order` và `preview_url` (URL ký sẵn, sống 1 giờ); giọng nhân bản có các trường này ở giá trị rỗng (`null` hoặc `[]`).
- `GET /v1/audio/voices/{id}`: giọng có sẵn (theo tên) hoặc giọng nhân bản (theo `voice_...`).
- `DELETE /v1/audio/voices/{id}`: xóa giọng nhân bản và bản ghi mẫu đã lưu. Giọng có sẵn không xóa được. Bản ghi đồng ý vẫn được giữ.

