Tích hợpText to Speech

Chuyển văn bản thành giọng nói

Nhận một đoạn văn bản và trả về link file audio đọc nội dung đó, xử lý đồng bộ. **Backpressure:** hệ thống giới hạn tối đa 18 request TTS xử lý đồng thời — nếu đạt giới hạn, trả về `503 SERVICE_OVERLOADED` kèm `Retry-After: 2`. **Circuit breaker:** nếu nhà cung cấp lỗi 5 lần trong 10 lần gọi gần nhất, circuit breaker mở trong 30 giây — trong lúc này mọi request nhận `503 AI_PROVIDER_UNAVAILABLE` kèm `Retry-After` là số giây còn lại.

Headers

X-Api-KeystringRequired
Idempotency-KeystringOptional<=200 characters
Key tuỳ chọn, tự sinh phía client, giúp request tính phí retry an toàn. Gửi lại nguyên vẹn cùng một giá trị khi retry: lần gọi thành công đầu tiên được tính phí một lần, kết quả được replay lại cho các lần gọi sau với cùng key (trong vòng 24 giờ). Gửi lại trong lúc request gốc vẫn đang xử lý sẽ nhận `409 DUPLICATE_REQUEST`.

Request

This endpoint expects an object.
textstringRequired1-10000 characters

Văn bản cần đọc.

voiceIdstringRequired

Mã giọng đọc — lấy tại GET /tts/voices. Bắt buộc.

modelIdstringRequired

Mã model dùng để tạo giọng nói — lấy tại GET /tts/models. Bắt buộc; modelId ngoài danh sách model hợp lệ sẽ bị từ chối với 400.

languageCodestringOptional

Gợi ý ngôn ngữ, ví dụ vi-VN. Dành cho tương lai — provider hiện bỏ qua trường này.

configmap from strings to any or nullOptional

Tham số cấu hình tuỳ chọn cho model đã chọn — một tập con của field config trả về tại GET /tts/models (ví dụ speed, speechEmotion, speechStyle, age tuỳ model, đặt tên dạng camelCase). Được chuyển thẳng cho nhà cung cấp AI, không được xác thực (validate) ở tầng public-service — giá trị speed/option không hợp lệ sẽ bị nhà cung cấp từ chối. Chỉ những tham số được gửi mới bị ghi đè; tham số bỏ trống dùng giá trị mặc định của provider.

Response

Thành công.

trackingIdstringformat: "uuid"

Mã tra cứu request (UUID v7), dùng khi cần đối soát phí hoặc liên hệ hỗ trợ.

audioUrlstringformat: "uri"

Link tải file âm thanh đã tạo.

audioDurationdouble

Độ dài âm thanh (giây).

processingTimeMslong

Tổng thời gian xử lý end-to-end (mili-giây).

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
502
Bad Gateway Error
503
Service Unavailable Error