Khóa API TTS trong Python: Thiết lập, truyền phát, chế độ JSON, chế độ JSON

Kiểm tra quyền truy cập của khóa

Người tìm kiếm ví dụ khóa API TTS Python thường muốn chuyển văn bản thành giọng nói. Khóa từ dịch vụ này không làm điều đó. Nó xác thực các yêu cầu đến LLM văn bản: POST /v1/chat/completions và GET /v1/models, sử dụng mô hình uncensored. Không có tổng hợp giọng nói, không tải lên âm thanh và không có embedding.

Nếu điều đó phù hợp với dự án của bạn, ví dụ vì bạn tạo kịch bản, hội thoại hoặc lời dẫn rồi chuyển sang công cụ nói riêng, phần còn lại của trang này cung cấp Python hoạt động được. Nếu bạn cần đầu ra âm thanh từ chính API, đây là dịch vụ sai và tốt hơn nên biết ngay lúc này. tài liệu liệt kê bộ tính năng chính xác.

Một cách thực tế để dùng tạo văn bản trong dự án âm thanh là coi nó là giai đoạn viết. Mô hình soạn lời dẫn, viết lại một dòng để phù hợp giới hạn thời gian hoặc chuyển ghi chú thành hội thoại với nhiều người nói. Mã Python của bạn sau đó chuyển văn bản cuối cùng cho bất kỳ công cụ nói nào bạn dùng. Giữ các giai đoạn riêng biệt cũng có nghĩa là bạn có thể thay thế cái này mà không chạm vào cái kia và bạn chỉ trả tiền cho API này cho các từ nó viết.

Để làm theo bạn cần Python 3.9 trở lên và một khóa. Đăng ký trên trang khóa API và nhận tín dụng dùng thử $0.50 chỉ với một cú nhấp chuột; nó kéo dài 7 ngày và không cần thẻ.

Lưu khóa và cài đặt gói

Không bao giờ ghi khóa vào tệp bạn commit. Đặt nó vào biến môi trường và đọc nó khi chạy.

Copy# base URL used below: https://api.ttsapihub.com/v1 , model: uncensored
pip install openai
export API_KEY="paste-your-key-here"

Trên PowerShell Windows tương đương là $env:API_KEY = "paste-your-key-here". Đối với dự án, tệp .env tải bằng gói như python-dotenv là mẫu phổ biến, miễn là .env có trong .gitignore của bạn.

Nếu khóa rò rỉ vào kho lưu trữ, hãy coi nó là đã cháy: xóa nó khỏi lịch sử nếu có thể và yêu cầu khóa mới. Nhớ rằng khóa chi trả tín dụng trả trước, nên khóa bị rò rỉ cũng là rò rỉ tài chính.

Tạo client và thực hiện yêu cầu đầu tiên

Gói chính thức chấp nhận base_url. Mọi thứ khác là hình thức gọi OpenAI thông thường.

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.ttsapihub.com/v1",
    api_key=os.environ["API_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You write short narration scripts."},
        {"role": "user", "content": "Draft a 40-word intro for a podcast about night trains."},
    ],
    temperature=0.8,
    max_tokens=200,
)

print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

Đối tượng usage cho biết bao nhiêu token mà yêu cầu đã dùng, để bạn tính chi phí: token đầu vào nhân $0.15 mỗi triệu, cộng token đầu ra nhân $0.50 mỗi triệu. Nếu yêu cầu trên dùng 60 token đầu vào và 80 token đầu ra, chi phí là $0.000009 cộng $0.00004, tức $0.000049. Yêu cầu bị lỗi hoặc bị từ chối không bị tính phí.

max_tokens là tùy chọn. Không có nó, phần kết thúc có thể dùng bất kỳ phần nào còn lại của cửa sổ 100.000 token, nên đặt nó khi bạn muốn giới hạn cứng về độ dài và chi phí.

Nhận phản hồi qua streaming

Truyền phát trả về token khi chúng được tạo bằng sự kiện gửi qua máy chủ. Đặt stream=True và lặp qua.

Copyimport os
from openai import OpenAI

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"])

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Describe a rainy station platform in four sentences."}],
    stream=True,
)

parts = []
for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta.content or ""
    parts.append(delta)
    print(delta, end="", flush=True)

text = "".join(parts)

Bộ bảo vệ cho danh sách choices rỗng có ở đó vì sự kiện cuối của luồng có thể mang dữ liệu sử dụng và không có văn bản. Bỏ qua nó tránh lỗi chỉ mục. Một chi tiết vận hành: yêu cầu truyền phát giữ slot độ đồng thời của nó cho đến khi luồng kết thúc. Nếu bạn bắt đầu nhiều luồng trong các luồng và không bao giờ đọc chúng, bạn sẽ chạm giới hạn độ đồng thời dù tốc độ yêu cầu của bạn thấp.

Yêu cầu JSON và gọi công cụ

Chế độ JSON

Đặt response_format thành một đối tượng JSON để phản hồi có thể phân tích cú pháp. Đồng thời, hãy yêu cầu mô hình trong prompt trả về JSON; cài đặt này ràng buộc định dạng, còn prompt cho biết cấu trúc mong muốn.

Copyimport json, os
from openai import OpenAI

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"])

resp = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply only with JSON: {\"title\": str, \"beats\": [str]}"},
        {"role": "user", "content": "Outline a three-beat radio drama about a lost key."},
    ],
)

data = json.loads(resp.choices[0].message.content)
print(data["title"], len(data["beats"]))

Dù sao hãy bọc json.loads trong khối try. Phản hồi đạt max_tokens có thể bị cắt ngang giữa đối tượng.

Gọi hàm

Chuyển tools và tùy chọn tool_choice. Khi mô hình yêu cầu gọi công cụ, hãy tự chạy nó và gửi kết quả lại dưới dạng thông báo với role: "tool".

Copyimport json, os
from openai import OpenAI

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"])

tools = [{
    "type": "function",
    "function": {
        "name": "word_count",
        "description": "Count the words in a text",
        "parameters": {
            "type": "object",
            "properties": {"text": {"type": "string"}},
            "required": ["text"],
        },
    },
}]

messages = [{"role": "user", "content": "How many words are in: the quick brown fox?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
msg = first.choices[0].message

if msg.tool_calls:
    call = msg.tool_calls[0]
    args = json.loads(call.function.arguments)
    result = len(args["text"].split())
    messages.append(msg)
    messages.append({"role": "tool", "tool_call_id": call.id, "content": str(result)})
    final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
    print(final.choices[0].message.content)

Giữ hội thoại và theo dõi ngân sách token

API không có trạng thái. Nếu bạn muốn một cuộc hội thoại ghi nhớ những gì đã được nói, hãy giữ danh sách tin nhắn trong chương trình của bạn và gửi toàn bộ danh sách đó với mỗi lệnh gọi. Một lớp nhỏ có thể thực hiện việc này, và đây cũng là nơi phù hợp để giới hạn lịch sử để chi phí không tăng dần.

Copyimport os
from openai import OpenAI

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"])

history = [{"role": "system", "content": "You are a dialogue writer. Keep replies under 120 words."}]

def say(user_text, keep_last=12):
    history.append({"role": "user", "content": user_text})
    # keep the system message plus the most recent turns
    trimmed = [history[0]] + history[1:][-keep_last:]
    resp = client.chat.completions.create(model="uncensored", messages=trimmed, max_tokens=250)
    reply = resp.choices[0].message.content
    history.append({"role": "assistant", "content": reply})
    return reply, resp.usage.total_tokens

print(say("Open a scene in a ticket office at closing time.")[0])

Cắt giảm quan trọng hơn về tiền hơn về cửa sổ. Mô hình chấp nhận tối đa 100.000 token tổng cộng, nhưng nếu mỗi lượt gửi lại 30.000 token lịch sử, mỗi yêu cầu tốn $0.0045 chỉ cho đầu vào (30.000 nhân $0.15 mỗi triệu). Năm mươi lượt như vậy cộng lại thành $0.225 trước khi một token đầu ra được tính. Giữ mười hai lượt cuối hoặc tóm tắt các lượt cũ thành ghi chú ngắn thường giữ chất lượng và cắt giảm hóa đơn đáng kể.

Độ đồng thời là thứ khác cần thiết kế cho. Nếu chương trình của bạn phục vụ nhiều người dùng cùng lúc, một semaphore có kích thước bằng giới hạn khóa của bạn (8 cho khóa đầy đủ, 2 cho khóa dùng thử) giữ bạn không chạm lỗi concurrency. Các yêu cầu vượt giới hạn chờ trong hàng đợi của riêng bạn thay vì thất bại, thân thiện hơn là thử lại trên 429.

Kiểm tra cũng đáng một từ. Viết một tập lệnh nhỏ gọi API với seed cố định, nhiệt độ thấp và max_tokens ngắn và chạy nó bất cứ khi nào bạn thay đổi prompt hoặc cài đặt. Seed và nhiệt độ thấp làm đầu ra có thể lặp lại hơn, cho phép bạn so sánh hai phiên bản prompt mà không có nhiễu. Giữ các kiểm tra này nhỏ; một bài kiểm tra tốn một phần nhỏ của một cent có thể chạy trên mỗi commit mà không ai nhận ra hóa đơn.

Cuối cùng, hãy ghi lại ID yêu cầu từ mỗi phản hồi. Khi một lệnh gọi hoạt động kỳ lạ, ID đó là cách nhanh nhất để hướng dẫn bộ phận hỗ trợ đến đúng yêu cầu đó.

Xử lý giới hạn, lỗi và số dư

Khóa đầy đủ cho phép 8 yêu cầu đồng thời và 300 yêu cầu mỗi phút. Khóa dùng thử cho phép 2 yêu cầu đồng thời và 60 yêu cầu mỗi phút. Vượt quá giới hạn đầu tiên sẽ trả về HTTP 429 với mã lỗi concurrency, và vượt quá giới hạn thứ hai sẽ trả về 429 với rate_limited. Quá tải tạm thời cũng trả về 429 kèm tiêu đề Retry-After: 5.

Gói OpenAI tự thử lại một số lỗi và bạn có thể nâng cao điều đó với max_retries. Đối với công việc hàng loạt, thêm giới hạn của riêng bạn cho công việc song song để bạn ở dưới giới hạn độ đồng thời thay vì dựa vào thử lại.

Copyimport os
from openai import OpenAI, RateLimitError

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"], max_retries=3)

raw = client.chat.completions.with_raw_response.create(
    model="uncensored",
    messages=[{"role": "user", "content": "One sentence about trains."}],
    max_tokens=60,
)
print("balance:", raw.headers.get("X-Balance-USD"))
print("request id:", raw.headers.get("X-Request-Id"))
print(raw.parse().choices[0].message.content)

Các tiêu đề phản hồi X-Request-Id và X-Balance-USD hữu ích trong nhật ký. Trích dẫn ID yêu cầu khi bạn liên hệ hỗ trợ. Chi phí được liệt kê trên trang giá cả: $0.15 mỗi 1M token đầu vào và $0.50 mỗi 1M token đầu ra, với nạp tiền từ $20 đến $500 và tiền thưởng 5%, 10% và 15% tại $50, $100 và $200. Thẻ (Visa, Mastercard, Apple Pay, Google Pay) và tiền mã hóa (USDT trên TRC20, USDC trên Base) được chấp nhận. Prompt không được dùng để huấn luyện. Mô hình dành cho người trưởng thành sử dụng hợp pháp và nội dung tình dục liên quan đến người chưa thành niên không bao giờ được phép.

Hướng dẫn khác

• API miễn phí cho SillyTavern: Tín dụng Dùng thử và Thiết lập
• URL cơ sở của TTS API: Nó là gì và cần nhập gì
• Danh sách kiểm tra API Elevenlabs: Đường ống TTS không kiểm duyệt