Demo API TTS: Ví dụ yêu cầu và phản hồi thời gian thực

Trước khi bạn chạy bất cứ thứ gì

Một lời cảnh báo công bằng cho bất kỳ ai mong đợi nhấn phát và nghe giọng nói: bản demo API TTS này không tạo ra âm thanh. Dịch vụ trả về văn bản từ một mô hình, uncensored, qua POST /v1/chat/completions. Có một endpoint thứ hai, GET /v1/models, để liệt kê những gì có sẵn. Không có gì trả về âm thanh, hình ảnh hay embedding.

Tại sao lại là demo? Vì nhiều dự án xử lý giọng nói cần chính xác phần này: một người viết kịch bản, một trình làm sạch văn bản, một trình phân tách quyết định ai nói gì. Các ví dụ dưới đây hiển thị những công việc đó, và định dạng đầu ra là những gì mã xử lý giọng nói của bạn sẽ phân tích.

Bạn cần một khóa API. Đăng ký trên trang khóa API bằng Google hoặc bằng email và mật khẩu, sau đó nhận tín dụng dùng thử $0.50 chỉ với một cú nhấp chuột. Nó có giá trị trong 7 ngày và không cần thẻ. Xuất khóa để các lệnh bên dưới có thể đọc nó:

Copyexport XTTS_API_KEY="paste-your-key-here"
curl -s https://api.xtts.cc/v1/models -H "Authorization: Bearer $XTTS_API_KEY" | grep uncensored

Nếu lệnh gọi đó trả về một danh sách JSON bao gồm uncensored, khóa hoạt động và bạn có thể tiếp tục.

Demo 1: một yêu cầu đơn giản

Lệnh gọi hữu ích nhỏ nhất yêu cầu một đoạn văn phong cách nói ngắn:

Copycurl -s https://api.xtts.cc/v1/chat/completions \
  -H "Authorization: Bearer $XTTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "You write short lines for a voice actor. No stage directions."},
      {"role": "user", "content": "Welcome listeners to a show about lighthouses. Two sentences."}
    ],
    "temperature": 0.7,
    "max_tokens": 120
  }'

Phản hồi trông giống như mẫu bên dưới. Văn bản bên trong content sẽ khác nhau trong mỗi lần chạy, vì vậy hãy coi đó là minh họa về cấu trúc chứ không phải đầu ra đã ghi lại.

Copy{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "model": "uncensored",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Welcome to the show. Tonight we climb the stairs of the world's loneliest lighthouses."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 38, "completion_tokens": 21, "total_tokens": 59}
}

Mã của bạn đọc choices[0].message.content. finish_reason cho bạn biết vì sao quá trình sinh kết thúc: stop cho kết thúc tự nhiên, length nếu max_tokens cắt ngắn. Nếu bạn bỏ qua max_tokens, phần hoàn thiện có thể dùng bất kỳ phần nào còn lại của cửa sổ 100.000 token, bao gồm cả prompt và kết quả.

Các tiêu đề cho bạn biết điều gì

Thêm -i vào lệnh curl và bạn sẽ thấy X-Request-Id, X-Balance-USD, X-RateLimit-Limit-Requests và X-RateLimit-Limit-Concurrency. Tiêu đề số dư rất hữu ích trong một demo vì bạn có thể theo dõi nó giảm đi một lượng nhỏ sau mỗi lệnh gọi. Đối với yêu cầu này, mức sử dụng ở trên tương đương 38 x $0.15 / 1.000.000 cộng 21 x $0.50 / 1.000.000, tức là $0.0000057 cộng $0.0000105, khoảng $0.0000162.

Demo 2: truyền phát kịch bản

Đối với âm thanh, bạn hiếm khi muốn đợi toàn bộ văn bản. Thêm "stream": true và API gửi các sự kiện truyền phát, từng đoạn văn bản nhỏ một. Ví dụ Node bên dưới in văn bản khi nó đến, đó là nơi bạn sẽ đưa một hàng đợi câu.

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.xtts.cc/v1",
  apiKey: process.env.XTTS_API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [
    { role: "user", content: "Read a four-line weather report for a coastal town." },
  ],
});

for await (const chunk of stream) {
  const piece = chunk.choices[0]?.delta?.content ?? "";
  process.stdout.write(piece);
}
process.stdout.write("\n");

Chạy nó dưới dạng mô-đun ES (lưu dưới dạng demo.mjs và chạy node demo.mjs sau npm install openai). Trên đường truyền, mỗi sự kiện là một dòng bắt đầu bằng data: theo sau là JSON, và luồng đóng lại với một dấu hiệu cuối cùng. Mức sử dụng token được báo cáo ở cuối luồng. Một điểm quan trọng cần lưu ý khi lập kế hoạch: một yêu cầu truyền phát giữ slot yêu cầu đồng thời của nó cho đến khi luồng kết thúc, vì vậy một người tiêu dùng chậm có thể chặn yêu cầu tiếp theo của bạn.

Demo 3: gọi hàm làm bộ định tuyến giọng nói

Gọi hàm cho phép mô hình trả lại một hướng dẫn có cấu trúc thay vì văn xuôi. Trong một dự án giọng nói, đó là một cách sạch để chọn phong cách trình bày cho mỗi dòng. Bạn xác định một hàm gọi là say, và mô hình điền các đối số của nó. Mã của bạn sau đó quyết định phải làm gì với chúng. Mô hình không tự chạy bất cứ thứ gì.

Copyimport json
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.xtts.cc/v1", api_key=os.environ["XTTS_API_KEY"])

tools = [{
    "type": "function",
    "function": {
        "name": "say",
        "description": "Queue one line for the voice engine.",
        "parameters": {
            "type": "object",
            "properties": {
                "text": {"type": "string"},
                "style": {"type": "string", "enum": ["calm", "urgent", "whisper"]},
            },
            "required": ["text", "style"],
        },
    },
}]

messages = [
    {"role": "system", "content": "Always answer by calling say, once per line."},
    {"role": "user", "content": "The alarm sounds. The guard tells everyone to leave."},
]

r = client.chat.completions.create(
    model="uncensored", messages=messages, tools=tools, tool_choice="auto"
)

msg = r.choices[0].message
for call in msg.tool_calls or []:
    args = json.loads(call.function.arguments)
    print(args["style"], "->", args["text"])

Các đối số đến dưới dạng chuỗi JSON, vì vậy hãy phân tích cú pháp và xác thực chúng trước khi sử dụng. Các mô hình có thể tạo ra một kiểu bên ngoài enum của bạn hoặc bỏ qua một trường, và một giá trị không được kiểm tra không bao giờ nên đi vào công cụ xử lý của bạn. Nếu bạn muốn cuộc trò chuyện tiếp tục, hãy thêm tin nhắn trợ lý và một phản hồi với role: "tool" và tool_call_id phù hợp, sau đó gọi API lại.

Khi truyền phát, các lệnh gọi hàm đến từng mảnh. Tên hàm đến trước và chuỗi đối số được xây dựng qua các phần, vì vậy hãy thu thập các mảnh theo chỉ mục và phân tích cú pháp một lần khi luồng kết thúc.

Demo 4: chế độ JSON cho danh sách diễn viên

Nếu bạn thích bỏ qua các định nghĩa công cụ, chế độ JSON cung cấp JSON hợp lệ trong nội dung tin nhắn. Nó rất phù hợp để chuyển đổi một cảnh thô thành các dòng theo từng diễn viên.

Copycurl -s https://api.xtts.cc/v1/chat/completions \
  -H "Authorization: Bearer $XTTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "response_format": {"type": "json_object"},
    "temperature": 0.2,
    "messages": [
      {"role": "system", "content": "Return JSON: {\"lines\": [{\"speaker\": string, \"text\": string}]}"},
      {"role": "user", "content": "Ana asks Ben to hold the ladder. Ben agrees reluctantly."}
    ]
  }'

Chế độ JSON đảm bảo rằng đầu ra được phân tích cú pháp, không đảm bảo rằng nó khớp với hình dạng của bạn. Mô tả hình dạng trong prompt, như ở trên, và kiểm tra các khóa (key) trong mã. Nhiệt độ thấp giữ cho cấu trúc ổn định.

Demo 5: một tài liệu dài trong một yêu cầu

Cửa sổ ngữ cảnh là 100.000 token, dùng chung cho prompt và đoạn văn bản đầu ra. Điều đó đủ để gửi một bản ghi âm dài hoặc một câu chuyện ngắn và yêu cầu một phiên bản được viết để nghe. Thân yêu cầu có thể lên tới 8 MB, vì vậy kích thước hiếm khi là giới hạn; số lượng token mới là.

Đây là chi phí của một lệnh gọi nặng. Giả sử bạn gửi 80.000 token và nhận lại 2.000. Đầu vào: 80.000 x $0.15 / 1.000.000 = $0.012. Đầu ra: 2.000 x $0.50 / 1.000.000 = $0.001. Tổng cộng là $0.013, vì vậy tín dụng $0.50 sẽ bao gồm khoảng 38 lệnh gọi như vậy. Đầu vào dài rẻ hơn so với đầu ra dài, đó là lý do tại sao các bản tóm tắt và viết lại các văn bản lớn có giá cả phải chăng trong khi tạo toàn bộ một cuốn tiểu thuyết cùng một lúc thì không.

Một mẹo thực tế cho các đầu vào dài: đặt hướng dẫn của bạn trước và lặp lại quy tắc quan trọng ở cuối. Các mô hình có xu hướng làm theo hướng dẫn mới nhất tốt nhất, và một lời nhắc một dòng sau 80.000 token văn bản nguồn gần như không tốn gì.

Lỗi đọc trong demo

Hãy cố tình làm hỏng một thứ một lần để bạn nhận ra nó sau này. Gửi yêu cầu với một khóa sai và bạn sẽ nhận được lỗi xác thực thay vì phản hồi thành công. Gửi mười yêu cầu cùng một lúc từ một khóa dùng thử và một số sẽ trả về HTTP 429.

Lỗi 429 có ba nguyên nhân, và mã lỗi cho biết chúng khác nhau như thế nào:

• rate_limited có nghĩa là quá nhiều yêu cầu trong một phút: 60 trên một khóa dùng thử, 300 trên một khóa đầy đủ.
• concurrency có nghĩa là quá nhiều yêu cầu đang xử lý cùng một lúc: 2 trên một khóa dùng thử, 8 trên một khóa đầy đủ.
• Lỗi 429 với tiêu đề Retry-After: 5 có nghĩa là dịch vụ đã bị quá tải tạm thời. Chờ 5 giây và gửi lại nó.

Các yêu cầu thất bại hoặc bị từ chối không bị tính phí, nên lỗi không tốn gì. Để xem các giới hạn mà khóa của bạn có, hãy đọc X-RateLimit-Limit-Requests và X-RateLimit-Limit-Concurrency trên bất kỳ phản hồi bình thường nào. Một vòng lặp thử lại nhỏ dừng lại theo giá trị Retry-After, hoặc 5 giây khi giá trị bị thiếu, là đủ cho một tập lệnh demo.

Những điều nên thử tiếp theo

Khi bốn lệnh gọi này hoạt động, bạn đã có các mảnh của một chuỗi xử lý tập lệnh. Bao bọc yêu cầu đơn giản trong một hàm, đưa vòng lặp truyền phát vào hàng đợi, và kết nối hàng đợi với công cụ tổng hợp giọng nói bạn chọn. Các công cụ khác nhau về giá, giấy phép và chất lượng, vì vậy hãy đọc các điều khoản hiện tại của chúng. Dịch vụ này không cung cấp một công cụ và không nêu bất kỳ điều gì về chúng.

Chi phí vẫn nhỏ trong khi bạn thử nghiệm. Với giá $0.15 cho mỗi triệu token đầu vào và $0.50 cho mỗi triệu token đầu ra, một lệnh gọi demo điển hình tốn một phần nhỏ của một xu, và tín dụng $0.50 bao gồm hàng trăm lệnh gọi như vậy. Xem trang giá cả để nạp tiền từ $20 đến $500 với tiền thưởng từ 5% đến 15%, thanh toán bằng tiền mã hóa. tài liệu bao gồm danh sách đầy đủ các tham số, giới hạn tốc độ (8 đồng thời và 300 mỗi phút trên một khóa đầy đủ) và mã lỗi. Các prompt không được sử dụng để huấn luyện.

Thứ tự hợp lý cho một buổi chiều đầu tiên: chạy yêu cầu đơn giản cho đến khi âm sắc đúng, chuyển sang truyền phát và in các câu khi chúng hoàn thành, sau đó thêm các lệnh gọi hàm hoặc chế độ JSON, tùy thuộc vào cách đoạn mã xử lý giọng nói của bạn muốn nhận đầu vào. Giữ mọi prompt trong một tệp dưới kiểm soát phiên bản. Khi một dòng nghe sai trong âm thanh cuối cùng, bạn có thể truy ngược lại nó đến hướng dẫn chính xác đã tạo ra nó và thay đổi một thứ một lúc.

Hướng dẫn khác

• API TTS Python: Chuẩn bị văn bản cho giọng nói với SDK
• API TTS Miễn phí: Những gì gói dùng thử $0.50 bao gồm (chỉ văn bản)
• API Nhân bản Giọng nói: TTS Tương thích OpenAI