Sansürsüz API Entegrasyon Rehberi: Kayıt, Doğrulama, İlk Çağrı

Başlamadan Önce Kontrol Listesi

Yoldan şaşmamak için önce bunları kontrol edin.

• Kayıt için kullanılabilecek bir e-posta adresi.
• Makinenizde Python 3, JDK 15+ (metin blokları için gerekli), Go veya curl eklentili PHP ortamlarından biri kurulu olmalıdır.
• 18 yaşından büyük olduğunuzdan emin olun; hizmet yalnızca yetişkinlere açıktır.
• Ne istediğinizi biliyorsunuz: Saf metin sohbeti. Burada tek bir model var; vektör, görüntü, ses veya ince ayar yok.
• Anahtarı ortam değişkenlerinde saklamaya hazır olun; kaynak koduna yazmayın ve depoya göndermeyin.

Arayüz sözleşmesi basittir: Adres https://api.wushenchaapi.com/v1 şeklindedir ve OpenAI sohbet tamamlama ile uyumludur; bu nedenle daha önce yazdığınız istek gövdelerini neredeyse olduğu gibi taşıyabilirsiniz.

Süre tahmini: Kayıt bir dakika sürer, ortam kurulumu makinenize bağlıdır, ilk istek kendisi otuz saniyeden fazla sürmez. Bu süreden uzun sürerse ağ veya anahtar sorunudur; doğrudan sayfanın sonundaki hata giderme listesine atlayın. Sırayı bozmayın: önce models, sonra chat; önce senkron, sonra akış. Her adımı onayladıktan sonra ilerleyin.

Kayıt Olun ve Anahtarı Alın

/get-api-key/ adresine gidin ve e-posta ile şifre kullanarak kayıt olun. Kayıt tamamlandığında anahtar hemen görünür hale gelir; kopyalayın. Dikkat edilmesi gereken birkaç nokta:

1. Her hesap için yalnızca bir anahtar vardır.
2. Anahtar yeniden oluşturulabilir, ancak eski anahtar hemen geçersiz olur. Anahtarı değiştirmeden önce yeni değeri canlı ortamda dağıtın.
3. Yeni hesaplara $0.50 deneme kredisi verilir, 7 gün içinde geçerlidir; herhangi bir ödeme bilgisi doldurulması gerekmez.
4. Deneme süresi bittiğinde veya kredi bittiğinde istek 402 döndürür, hata kodu no_credit olur. Ön ödemeli bakiye yükleyerek kullanmaya devam edebilirsiniz. Abonelik değildir; bakiye süresi dolmaz.

Anahtarı ortam değişkenine ekleyin: macOS / Linux için export API_KEY=your_key, Windows PowerShell için $env:API_KEY="your_key". Tüm örnekler API_KEY değişkeninden okur.

İlk Adım: Bağlantıyı /v1/models ile Doğrulayın

Sohbeti hemen göndermeyin. Adresi, ağı ve key'i doğrulamak için sıfır maliyetli bir GET isteği gönderin:

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

200 ve model listesi (yalnızca uncensored) dönerse bağlantı kurulmuştur. 401 hatası key'in yanlış olduğunu veya eksik olduğunu gösterir; zaman aşımı ise makine ağını ve proxy'yi kontrol edin. Bağlantı sorunlarını istek gövdesi sorunlarından ayırmak, entegrasyon aşamasında en verimli alışkanlıktır.

Python: requests

SDK'ya gerek yok, tek bir requests.post yeterlidir. Üç noktaya dikkat edin: timeout ayarlanmalıdır; r.ok değerini kontrol ettikten sonra choices değerine erişin; hata durumunda hata gövdesi {"error":{"code":...,"message":...}} şeklindedir.

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

Başarılı isteklerde usage içinde prompt_tokens ve completion_tokens bulunur; geliştirme aşamasında bunları her seferinde yazdırmak maliyetleri takip etmenizi sağlar.

İstek Gövdesi Alanlarını Tek Tek İnceleyin

Dört dilde de aynı JSON gönderilir; önce bunu anlayın, hangi dili kullanırsanız kullanın sadece çeviri yapmanız gerekir.

Alan	Zorunlu	Açıklama
model	Evet	Sabit olarak uncensored değerine sahiptir.
messages	Evet	Dizi; her öğe role ve content içerir. role değerleri system, user, assistant olabilir.
max_tokens	Hayır	Varsayılan 2048, tek istek üst limiti 16,000'dir. Uzun metinler için bu değeri kendiniz artırmanız gerekir.
temperature / top_p / stop	Hayır	Standart örnekleme parametreleri; olduğu gibi iletilir.
stream	Hayır	true olduğunda SSE akış kullanılır.

Yanıttaki en çok okunan üç alan şunlardır: choices[0].message.content metindir, choices[0].finish_reason normal bitiş mi yoksa uzunluk kesintisi mi olduğunu belirtir, usage token kullanımını gösterir. Üçünü de okuyarak tam entegrasyonu sağlayın.

Ek olarak iki katı kısıtlamayı unutmayın: İstek gövdesi 8 MB'ı geçmemeli, her anahtar için dakika başına 300 istek sınırı vardır. Toplu görevler için acele etmeyin; önce basit bir eşzamanlılık sınırı belirleyin.

Java: java.net.http

JDK 11'den itibaren yerleşik HttpClient bulunur, herhangi bir bağımlılığa gerek yoktur. Aşağıdaki örnekte JDK 15 metin blokları kullanılarak JSON yazılmıştır; daha düşük sürümler için dize birleştirme veya tanıdık bir JSON kütüphanesi kullanın.

复制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());
    }
}

İpucu: İçerik Çince içerdiğinde, BodyPublishers.ofString varsayılan olarak UTF-8 kodlamasını kullanır, ek bir işlem yapmanıza gerek yoktur. Üretim ortamında HttpClient nesnesini singleton olarak yapılandırın ve yeniden kullanın; her istek için yeni bir örnek oluşturmaktan kaçının.

Go: net/http

Go'nun standart kütüphanesi de bu iş için yeterlidir. Önemli olan varsayılan http.DefaultClient kullanırken zaman aşımı süresi ayarlamamanızdır; aksi takdirde uzak sunucu takıldığında goroutine'ler sonsuza kadar asılı kalabilir.

复制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))
}

Yanıt gövdesini io.ReadAll ile okuyun ve ardından ayrıştırın. Yapılandırılmış işleme için ilgili struct'ı tanımlayıp encoding/json ile deserialize edin; alanlar choices, message, content ve usage'dır.

PHP: curl

PHP'de curl uzantısını kullanın. json_encode çağrırken JSON_UNESCAPED_UNICODE bayrağını eklemeyi unutmayın; aksi takdirde Çince karakterler \uXXXX formatına dönüştürülür. Bu çalışsa da hata ayıklama sırasında okuması zordur.

复制<?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";

İki tür hatayı birbirinden ayırmaya dikkat edin: curl_exec false dönerse bu bir ağ katmanı sorunudur; veri döner ancak HTTP durum kodu 200 değilse bu bir API katmanı sorunudur ve error.code alanını okumanız gerekir.

İlk çağrıda sık karşılaşılan sorunlar

• 401: Header Authorization: your_key olarak yazılmış, Bearer ön eki eksik veya ortam değişkeni yeni terminalde aktif değil.
• 404: URL yolunda /v1 eksiktir veya chat/completions yazım hatası içermektedir.
• 400: JSON geçersiz veya prompt ile max_tokens toplamı 100.000 token sınırını aşıyor.
• 402: Bakiye bitmiştir veya deneme süresi dolmuştur.
• Çıktı kesildi: max_tokens varsayılan olarak 2048'dir, tek seferde maksimum 16.000 token gönderilebilir; uzun metin yazmak için bunu açıkça artırmanız gerekir.
• Akış modu isteği: İstek gövdesine "stream": true ekleyin. Yanıt SSE formatında olacaktır ve sona doğru otomatik olarak usage bilgisini içeren bir veri bloğu eklenecektir.

Bağlantı sağlandıktan sonra Prompt yazımı ile çıktı kalitesini kontrol edin, hatalar için hata kodları kılavuzu'na bakın. Parametreler doküman'da, fiyatlar fiyat sayfası'da.

İşlemler tamamlandıktan sonra, canlıya geçmeden önce şu üç adımı tamamlayın

Tutoriyaldeki örnekler minimum çalışır sürümdür. Bu kodu gerçek bir servise entegre etmeden önce en azından şu üç adımı tamamlamalısınız.

1. Zaman aşımı. Örneklerde 120 saniye verilmiştir çünkü uzun metinler yavaş oluşturulur. Senkron beklerken tolerans süresini kısaltın ve akış çıktısı ile kullanıcıların karakterleri anında görmesini sağlayın.
2. Hata yönlendirme. 401, 402 ve 403 hataları yeniden denendiğinde çözülmeyecek hatalardır; bu durumda uyarı verilmeli veya kullanıcıya bilgi verilmelidir. 429 ve 503 hataları ise geri çekilme ve yeniden deneme için uygundur. Detaylı uygulama örnekleri sorun giderme kılavuzunda yer almaktadır.
3. Kullanım kayıtları. Her yanıtın usage alanı bir log olarak kaydedilir; kullanıcı içeriğini log'a yazmayın. Ay sonunda muhasebe ve anormal tüketim için bu loglara bakın.

Anahtar yönetimi hakkında bir not daha: key tekildir; sızdırılırsa yalnızca yeniden oluşturulabilir ve yeniden oluşturmak, kullanımdaki tüm hizmetlerin aynı anda kesilmesine neden olur. Bu nedenle anahtarı birden fazla betikte ve birden fazla makinenin yapılandırmasında dağıtmayın; tek bir anahtar yapılandırma noktasında toplayın, böylece değiştirdiğinizde kaçırma yapmazsınız.

İçerik sınırları: Yetişkinlere yönelik içerik, kurgu ve tartışmalı konular reddedilmez; ancak reşit olmayanlarla ilgili cinsel içerikler (kurgu ve rol yapma dahil) 403 hatası ile engellenir. Uygulamanız yetişkinlere yönelikse, kayıt sürecinde yaş doğrulaması yapmanız önerilir.

Son olarak, monitörünüzün kenarına yapıştırabileceğiniz bir kontrol sırası: API anahtarı ortam değişkenlerinde tanımlı mı? models uç noktası çalışıyor mu? İstek gövdesi geçerli bir JSON mu? Model sansürsüz mü? max_tokens değeri yeterli mi? Yanıttaki finish_reason alanı stop mu yoksa length mi? usage verisi loglandı mı? Bu yedi kontrol de başarılı olursa entegrasyon tamamlanmış demektir.