Panduan Integrasi API Tanpa Sensor: Registrasi, Verifikasi, Panggilan Pertama

Daftar Periksa Pra-Kerja

Baca dulu agar Anda tidak perlu kembali nanti.

• Alamat email yang dapat menerima pesan untuk registrasi.
• Lingkungan runtime apa pun di mesin Anda: Python 3, JDK 15 atau lebih tinggi (contoh menggunakan blok teks), Go, atau PHP dengan ekstensi curl.
• Pastikan Anda berusia di atas 18 tahun, karena layanan ini hanya untuk pengguna dewasa.
• Ketahui bahwa Anda menginginkan percakapan teks murni: hanya ada satu model, tanpa vektor, gambar, suara, atau fine-tuning.
• Siapkan penyimpanan kunci dalam variabel lingkungan, jangan tulis ke dalam kode sumber, dan jangan kirim ke repositori.

Konvensi antarmuka sangat sedikit: URL https://api.wushenchaapi.com/v1 kompatibel dengan kelengkapan chat OpenAI, sehingga body permintaan lama Anda hampir bisa langsung digunakan.

Perkiraan waktu: registrasi satu menit, instalasi lingkungan tergantung kondisi komputer Anda, permintaan pertama tidak lebih dari tiga puluh detik. Jika melebihi waktu ini, kemungkinan besar masalah jaringan atau kunci; langsung lompat ke daftar pemecahan masalah di akhir. Urutan: models dulu, lalu chat; sinkron dulu, lalu streaming; konfirmasi setiap langkah sebelum melanjutkan.

Registrasi dan Dapatkan Kunci

Buka /get-api-key/, daftar dengan email dan kata sandi. Kunci ditampilkan segera setelah registrasi selesai, cukup salin. Beberapa detail:

1. Setiap akun hanya memiliki satu kunci API.
2. Dapat dibuat ulang, tetapi kunci lama akan segera tidak berlaku. Pastikan nilai baru telah dideploy sebelum mengganti kunci pada layanan produksi.
3. Akun baru mendapatkan $0.50 kredit uji coba gratis yang berlaku selama 7 hari tanpa perlu mengisi informasi pembayaran.
4. Saat masa percobaan habis atau saldo habis, permintaan akan mengembalikan 402 dengan kode kesalahan no_credit. Isi saldo prabayar untuk melanjutkan penggunaan; ini bukan langganan, dan saldo tidak akan kedaluwarsa.

Masukkan kunci ke variabel lingkungan: pada macOS / Linux jalankan export API_KEY=kunci_anda, pada Windows PowerShell gunakan $env:API_KEY="kunci_anda". Semua contoh selanjutnya membaca dari API_KEY.

Langkah Pertama: Verifikasi Konektivitas dengan /v1/models

Jangan langsung mengirim percakapan. Lakukan GET berbiaya nol terlebih dahulu untuk memastikan alamat, jaringan, dan kunci sudah benar:

复制curl https://api.wushenchaapi.com/v1/models \
  -H "Authorization: Bearer $API_KEY"

Respons 200 dengan daftar model (hanya uncensored) berarti berhasil. Respons 401 berarti kunci salah atau hilang; jika timeout, periksa jaringan dan proxy lokal Anda.

Python: requests

Tidak perlu SDK, satu requests.post sudah cukup. Perhatikan tiga hal: timeout harus diatur; periksa r.ok sebelum mengambil choices; saat gagal, tubuh kesalahan adalah {"error":{"code":...,"message":...}}.

复制import os
import requests

url = "https://api.wushenchaapi.com/v1/chat/completions"
headers = {
    "Authorization": "Bearer " + os.environ["API_KEY"],
    "Content-Type": "application/json",
}
payload = {
    "model": "uncensored",
    "messages": [{"role": "user", "content": "用两句话描述一场雨夜里的追逐戏。"}],
    "max_tokens": 300,
}
r = requests.post(url, headers=headers, json=payload, timeout=120)
print(r.status_code)
data = r.json()
if r.ok:
    print(data["choices"][0]["message"]["content"])
    print(data["usage"])
else:
    print(data["error"]["code"], data["error"]["message"])

Saat berhasil, usage berisi prompt_tokens dan completion_tokens. Disarankan untuk mencetaknya setiap kali selama periode pengembangan agar Anda memiliki gambaran biaya.

Analisis Bidang Tubuh Permintaan

Keempat bahasa mengirim JSON yang sama. Pahami dulu strukturnya, maka menulis dalam bahasa apa pun hanyalah terjemahan.

Bidang	Wajib	Keterangan
model	Ya	Tetap pada uncensored.
messages	Ya	Array, setiap item berisi role dan content. Role dapat berupa system, user, atau assistant.
max_tokens	Tidak	Default 2048, batas maksimum per panggilan 16,000. Harus dinaikkan secara manual untuk teks panjang.
temperature / top_p / stop	Tidak	Parameter sampling standar, diteruskan apa adanya.
stream	Tidak	Jika bernilai true, alur streaming SSE digunakan.

Ada tiga bagian yang paling sering Anda baca dalam respons: choices[0].message.content adalah isi teks, choices[0].finish_reason memberi tahu apakah selesai normal atau terpotong karena batas panjang, dan usage adalah penggunaan token untuk permintaan ini. Membaca ketiga bagian tersebut baru dianggap sebagai integrasi yang lengkap.

Catat dua batasan keras: body permintaan tidak boleh melebihi 8 MB, dan batas laju 300 permintaan per menit per kunci. Untuk tugas batch, jangan langsung melakukan permintaan paralel; tetapkan batas konkurensi sederhana terlebih dahulu.

Java: java.net.http

HttpClient bawaan tersedia mulai JDK 11 tanpa memerlukan dependensi tambahan. Contoh di bawah ini menggunakan blok teks JDK 15 untuk menulis JSON; pada versi yang lebih lama, Anda dapat mengubahnya menjadi penggabungan string atau menggunakan pustaka JSON favorit Anda untuk serialisasi.

复制import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Demo {
    public static void main(String[] args) throws Exception {
        String key = System.getenv("API_KEY");
        String body = """
            {"model":"uncensored",
             "messages":[{"role":"user","content":"写一段两百字以内的悬疑小说开头。"}],
             "max_tokens":400}
            """;
        HttpRequest req = HttpRequest.newBuilder(
                URI.create("https://api.wushenchaapi.com/v1/chat/completions"))
            .timeout(Duration.ofSeconds(120))
            .header("Authorization", "Bearer " + key)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> resp = HttpClient.newHttpClient()
            .send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(resp.statusCode());
        System.out.println(resp.body());
    }
}

Tips: Saat konten berisi bahasa Mandarin, BodyPublishers.ofString secara default menggunakan pengkodean UTF-8 sehingga tidak perlu penanganan tambahan. Di lingkungan produksi, jadikan HttpClient sebagai singleton agar dapat digunakan kembali, jangan buat baru setiap kali permintaan.

Go: net/http

Pustaka standar Go juga sudah cukup. Poin utamanya adalah jangan menggunakan http.DefaultClient tanpa mengatur batas waktu, karena goroutine akan menggantung terus-menerus jika sisi server macet.

复制package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
	"time"
)

func main() {
	body := []byte(`{"model":"uncensored","messages":[{"role":"user","content":"给一个反派角色写三句独白。"}],"max_tokens":300}`)
	req, err := http.NewRequest("POST", "https://api.wushenchaapi.com/v1/chat/completions", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{Timeout: 120 * time.Second}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(out))
}

Baca seluruh respons menggunakan io.ReadAll lalu lakukan parsing. Untuk pemrosesan terstruktur, definisikan struct yang sesuai dan gunakan encoding/json untuk deserialisasi; field-nya mencakup choices, message, content, dan usage.

PHP: curl

PHP menggunakan ekstensi curl. Ingatlah untuk menambahkan JSON_UNESCAPED_UNICODE saat menggunakan json_encode, jika tidak karakter Mandarin akan diubah menjadi format \uXXXX yang meskipun berfungsi, akan sulit dibaca saat debugging.

复制<?php
$payload = [
    "model" => "uncensored",
    "messages" => [["role" => "user", "content" => "写一首八行的现代诗，主题是末班地铁。"]],
    "max_tokens" => 300,
];
$ch = curl_init("https://api.wushenchaapi.com/v1/chat/completions");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 120,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);
$res = curl_exec($ch);
if ($res === false) {
    die("curl 错误: " . curl_error($ch) . "\n");
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n";
$data = json_decode($res, true);
echo $data["choices"][0]["message"]["content"] ?? $res, "\n";

Perhatikan perbedaan dua jenis kegagalan: jika curl_exec mengembalikan false, itu adalah masalah lapisan jaringan; jika mengembalikan konten tetapi kode status bukan 200, itu adalah masalah lapisan antarmuka, dan Anda harus membaca error.code.

Jebakan umum saat panggilan pertama

• 401: Header ditulis sebagai Authorization: kunci_api, tanpa awalan Bearer ; atau variabel lingkungan tidak aktif di terminal baru yang dibuka.
• 404: Jalur URL kurang /v1, atau chat/completions salah ketik.
• 400: JSON tidak valid, atau jumlah prompt ditambah max_tokens melebihi batas 100,000 token.
• 402: Saldo habis atau masa uji coba telah berakhir.
• Output terpotong: max_tokens memiliki nilai default 2048, dengan batas maksimum 16,000 per permintaan. Untuk teks panjang, Anda harus secara eksplisit meningkatkan nilainya.
• Menginginkan streaming: Tambahkan "stream": true ke tubuh permintaan. Respons akan berupa SSE, dan blok data yang menyertakan usage akan ditambahkan secara otomatis di akhir.

Setelah berhasil, langkah selanjutnya adalah mempelajari Cara Menulis Prompt untuk meningkatkan kualitas output. Jika mengalami error, lihat Panduan Pemecahan Masalah Kode Error. Penjelasan lengkap parameter ada di Dokumentasi, dan harga dapat dilihat di Halaman Harga.

Setelah berhasil, tambahkan tiga hal ini sebelum peluncuran

Contoh dalam tutorial adalah versi minimum yang berfungsi. Jika ingin mengintegrasikannya ke layanan produksi, Anda harus menambahkan setidaknya tiga hal berikut.

1. Batas waktu (timeout). Contoh menggunakan 120 detik karena generasi teks panjang memang membutuhkan waktu lebih lama. Jika bisnis Anda menunggu secara sinkron, perpendek batas waktu sesuai toleransi halaman Anda, dan kombinasikan dengan output streaming agar pengguna dapat melihat teks secara bertahap.
2. Pembagian kesalahan. Kesalahan 401, 402, dan 403 tidak akan berhasil meskipun dicoba lagi, sehingga perlu memicu peringatan atau memberi tahu pengguna; hanya 429 dan 503 yang layak untuk diulang dengan mekanisme backoff. Implementasi spesifiknya ada di panduan pemecahan masalah, tidak akan dibahas di sini.
3. Pencatatan penggunaan. Catat setiap usage dari respons ke dalam log. Hanya catat angka, jangan masukkan konten pengguna ke dalam log. Data ini penting untuk rekonsiliasi akhir bulan dan investigasi konsumsi anomali.

Satu hal lagi tentang manajemen kunci: hanya ada satu kunci utama. Jika bocor, Anda harus membuat kunci baru, dan pembuatan kunci baru akan membuat semua layanan yang sedang aktif terputus sekaligus. Oleh karena itu, jangan menyebarkan kunci ini di berbagai skrip atau konfigurasi mesin; kumpulkan di satu tempat konfigurasi kunci agar penggantian tidak ada yang terlewat.

Terakhir, batas konten: konten dewasa yang legal, fiksi novel, dan topik kontroversial tidak akan ditolak. Namun, konten seksual yang melibatkan anak di bawah umur akan selalu diblokir dengan status 403, termasuk dalam konteks fiksi dan roleplay. Jika aplikasi Anda ditujukan untuk pengguna dewasa, disarankan untuk menambahkan verifikasi usia dalam proses pendaftaran Anda sendiri.

Berikut adalah urutan pemeriksaan mandiri yang bisa Anda tempel di samping monitor: apakah kunci ada di variabel lingkungan; apakah endpoint models berfungsi; apakah tubuh permintaan adalah JSON yang valid; apakah model adalah model tanpa sensor; apakah max_tokens cukup; apakah finish_reason dalam respons adalah stop atau length; apakah usage telah dicatat. Jika ketujuh poin ini hijau (lulus), maka integrasi dianggap selesai.