Demo API TTS: Contoh Permintaan dan Respons Langsung

Sebelum Anda menjalankan apa pun

Peringatan jujur bagi siapa saja yang berharap menekan tombol putar dan mendengar suara: demo API TTS ini tidak menghasilkan suara. Layanan mengembalikan teks dari satu model, uncensored, melalui POST /v1/chat/completions. Ada endpoint kedua, GET /v1/models, untuk mencantumkan apa yang tersedia. Tidak ada yang mengembalikan audio, gambar, atau embedding.

Lalu mengapa demo? Karena banyak proyek suara membutuhkan tepat bagian ini: penulis naskah, pembersih teks, pemisah yang memutuskan siapa mengatakan apa. Contoh-contoh di bawah ini menunjukkan pekerjaan-pekerjaan tersebut, dan format output adalah apa yang akan diparsing oleh kode suara Anda.

Anda memerlukan kunci. Daftar di halaman kunci API dengan Google atau dengan email dan kata sandi, lalu klaim kredit uji coba $0,50 dengan satu klik. Kredit ini berlaku selama 7 hari dan tidak memerlukan kartu. Ekspor kunci agar perintah di bawah ini dapat membacanya:

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

Jika panggilan itu mengembalikan daftar JSON yang mencakup uncensored, kunci berfungsi dan Anda dapat melanjutkan.

Demo 1: permintaan biasa

Panggilan berguna terkecil meminta paragraf bergaya lisan yang singkat:

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
  }'

Balasannya terlihat seperti contoh di bawah. Teks di dalam content akan berbeda pada setiap jalannya, jadi anggap ini sebagai ilustrasi struktur dan bukan output yang direkam.

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}
}

Kode Anda membaca choices[0].message.content. finish_reason memberi tahu Anda mengapa generasi berakhir: stop untuk akhir yang alami, length jika max_tokens memotongnya secara singkat. Jika Anda tidak menyertakan max_tokens, completion dapat menggunakan sisa jendela 100.000 token, yang mencakup prompt dan completion bersama-sama.

Apa yang dikatakan oleh header

Tambahkan -i ke perintah curl dan Anda akan melihat X-Request-Id, X-Balance-USD, X-RateLimit-Limit-Requests dan X-RateLimit-Limit-Concurrency. Header saldo berguna dalam demo karena Anda dapat melihatnya turun sedikit setelah setiap panggilan. Untuk permintaan ini, penggunaan di atas dihitung menjadi 38 x $0,15 / 1.000.000 ditambah 21 x $0,50 / 1.000.000, yang merupakan $0,0000057 ditambah $0,0000105, sekitar $0,0000162.

Demo 2: streaming skrip

Untuk audio, Anda jarang ingin menunggu teks lengkap. Tambahkan "stream": true dan API mengirim server-sent events, satu bagian kecil teks pada satu waktu. Contoh Node di bawah mencetak teks saat tiba, di mana Anda akan mengisi antrean kalimat.

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");

Jalankan sebagai modul ES (simpan sebagai demo.mjs dan jalankan node demo.mjs setelah npm install openai). Di jaringan, setiap peristiwa adalah baris yang dimulai dengan data: diikuti JSON, dan stream ditutup dengan penanda akhir. Penggunaan token dilaporkan di akhir stream. Satu hal penting untuk perencanaan: permintaan yang di-streaming menjaga slot konkurensinya hingga stream berakhir, sehingga konsumen lambat dapat memblokir permintaan berikutnya Anda.

Demo 3: pemanggilan fungsi sebagai router suara

Pemanggilan fungsi memungkinkan model mengembalikan instruksi terstruktur alih-alih prosa. Dalam proyek suara, ini adalah cara bersih untuk memilih gaya penyampaian per baris. Anda menentukan fungsi bernama say, dan model mengisi argumennya. Kode Anda kemudian memutuskan apa yang harus dilakukan dengannya. Model tidak menjalankan apa pun sendiri.

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"])

Argumen tiba sebagai string JSON, jadi uraikan dan validasi sebelum digunakan. Model dapat menghasilkan gaya di luar enum Anda atau mengabaikan bidang, dan nilai yang tidak diperiksa tidak boleh pernah mencapai mesin Anda. Jika Anda ingin percakapan berlanjut, lampirkan pesan asisten dan balasan dengan role: "tool" dan tool_call_id yang sesuai, lalu panggil API lagi.

Saat streaming, pemanggilan fungsi tiba dalam potongan. Nama fungsi datang pertama dan string argumen dibangun di seluruh potongan, jadi kumpulkan fragmen berdasarkan indeks dan uraikan sekali aliran selesai.

Demo 4: mode JSON untuk daftar pemeran

Jika Anda lebih suka melewatkan definisi fungsi, mode JSON memberikan JSON valid di konten pesan. Ini sangat cocok untuk mengubah adegan kasar menjadi baris per pembicara.

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."}
    ]
  }'

Mode JSON menjamin bahwa output diparsing, bukan bahwa itu sesuai dengan bentuk Anda. Jelaskan bentuknya dalam prompt, seperti di atas, dan periksa kunci dalam kode. Suhu rendah menjaga struktur tetap stabil.

Demo 5: dokumen panjang dalam satu permintaan

Jendela konteks adalah 100.000 token, dibagi bersama oleh prompt dan completion. Itu cukup untuk mengirim transkrip panjang atau cerita pendek utuh dan meminta versi yang ditulis untuk telinga. Badan permintaan dapat berukuran hingga 8 MB, sehingga ukuran jarang menjadi batas; jumlah token adalah batasnya.

Berikut adalah biaya panggilan berat. Katakan Anda mengirim 80.000 token dan mendapatkan 2.000 kembali. Input: 80.000 x $0,15 / 1.000.000 = $0,012. Output: 2.000 x $0,50 / 1.000.000 = $0,001. Totalnya adalah $0,013, sehingga uji coba $0,50 akan mencakup sekitar 38 panggilan seperti itu. Input panjang murah dibandingkan dengan output panjang, itulah mengapa ringkasan dan penulisan ulang teks besar terjangkau sementara menghasilkan novel utuh sekaligus tidak.

Tips praktis untuk input panjang: letakkan instruksi Anda di awal dan ulangi aturan kunci di akhir. Model cenderung mengikuti instruksi terbaru dengan baik, dan pengingat satu baris setelah 80.000 token teks sumber hampir tidak memakan biaya.

Membaca kesalahan dalam demo

Rusak sesuatu secara sengaja sekali agar Anda mengenalinya nanti. Kirim permintaan dengan kunci yang salah dan Anda mendapatkan kesalahan autentikasi alih-alih completion. Kirim sepuluh permintaan pada saat yang sama dari kunci uji coba dan beberapa kembali sebagai HTTP 429.

429 memiliki tiga penyebab, dan kode kesalahan memisahkannya:

• rate_limited berarti terlalu banyak permintaan dalam satu menit: 60 pada kunci uji coba, 300 pada kunci penuh.
• concurrency berarti terlalu banyak permintaan yang sedang berjalan pada satu waktu: 2 pada kunci uji coba, 8 pada kunci penuh.
• Respons 429 dengan header Retry-After: 5 berarti layanan sedang kelebihan beban secara singkat. Tunggu lima detik dan kirim lagi.

Permintaan yang gagal atau ditolak tidak dibebankan biaya, sehingga kesalahan tidak memakan biaya. Untuk melihat batas yang dimiliki kunci Anda, baca X-RateLimit-Limit-Requests dan X-RateLimit-Limit-Concurrency pada respons normal apa pun. Loop coba ulang kecil yang tidur selama nilai Retry-After, atau lima detik ketika nilai tersebut hilang, adalah semua yang dibutuhkan skrip demo.

Apa yang harus dicoba selanjutnya

Setelah empat panggilan ini berhasil, Anda memiliki potongan pipa skrip. Bungkus permintaan biasa dalam fungsi, jalankan loop streaming ke antrian, dan sambungkan antrian ke mesin suara pilihan Anda. Mesin berbeda dalam harga, lisensi, dan kualitas, jadi baca ketentuan terkini mereka. Layanan ini tidak menyediakan satu pun dan tidak menyatakan apa pun tentang mereka.

Biaya tetap kecil saat Anda bereksperimen. Pada $0,15 per juta token input dan $0,50 per juta token output, panggilan demo khas memakan biaya sepersekian sen, dan uji coba $0,50 mencakup ratusan panggilan. Lihat halaman harga untuk isi saldo dari $20 hingga $500 dengan bonus dari 5% hingga 15%, dibayar dengan kripto. dokumentasi mencakup daftar parameter lengkap, batas laju (8 konkuren dan 300 per menit pada kunci penuh) dan kode kesalahan. Prompt tidak digunakan untuk pelatihan.

Urutan yang wajar untuk sore pertama: jalankan permintaan biasa hingga nadanya tepat, beralih ke streaming dan cetak kalimat saat selesai, lalu tambahkan panggilan alat atau mode JSON, mana pun yang sesuai dengan cara kode suara Anda menginginkan inputnya. Simpan setiap prompt dalam file di bawah kontrol versi. Ketika sebuah baris terdengar salah dalam audio akhir, Anda dapat melacaknya kembali ke instruksi tepat yang menghasilkannya dan mengubah satu hal pada satu waktu.

Panduan lainnya

• API TTS Python: Siapkan Teks untuk Suara dengan SDK
• API TTS Gratis: Apa yang Dicakup oleh Uji Coba $0,50 (Hanya Teks)
• API Voice Cloning: TTS Kompatibel OpenAI