開工前檢查清單
先過一遍，避免中途回頭。
- 一個可收信的信箱，用於註冊。
- 本機具備任一執行環境：Python 3、JDK 15 以上（範例使用文字區塊）、Go，或帶有 curl 擴充功能的 PHP。
- 確認自己是 18 歲以上的成年人，服務僅面向成年用戶。
- 知道自己要的是純文字對話：這裡只有一個模型，沒有向量、圖片、語音、微調。
- 準備好用環境變數儲存金鑰，不要寫進原始碼，更不要提交到程式碼庫。
介面規範簡潔：地址 https://api.wushenchaapi.com/v1，格式與 OpenAI 聊天補全相容，因此你過去撰寫的請求體幾乎可直接沿用。
時間預估：註冊需一分鐘，安裝環境取決於本機狀況，首次請求本身不超過 30 秒。若超過此時長仍無結果，多為網路或金鑰問題，請直接跳至文末排除清單。順序勿亂：先 models，後 chat；先同步，後串流，每一步確認後再繼續。
註冊並取得金鑰
開啟 /get-api-key/，使用信箱與密碼註冊。註冊完成後金鑰立即顯示，複製即可。幾點細節：
- 每個帳戶僅有一把金鑰。
- 可重新生成，但舊金鑰會立即失效，線上服務更換金鑰前，請先部署新值。
- 新帳戶贈送 $0.50 試用額度，7 天內有效，無需填寫任何支付資訊。
- 試用到期或額度用盡後，請求將返回 402，錯誤碼
no_credit，儲值預付額度即可繼續使用，非訂閱制，餘額不會過期。
將金鑰放入環境變數：macOS / Linux 執行 export API_KEY=你的金鑰，Windows PowerShell 使用 $env:API_KEY="你的金鑰"。後續所有範例皆從 API_KEY 讀取。
第一步：使用 /v1/models 驗證連線
別急著發送對話。先發送零成本的 GET 請求，確認地址、網路、金鑰三項皆無問題：
curl https://api.wushenchaapi.com/v1/models \
-H "Authorization: Bearer $API_KEY"返回 200 與模型列表（僅含 uncensored）即表示連線成功。返回 401 代表金鑰錯誤或未攜帶；超時則檢查本機網路與代理。將連線問題與請求體問題分開處理，是接入階段最節省時間的習慣。
Python：requests
無需 SDK，一個 requests.post 即可。注意三點：timeout 必設；先檢查 r.ok 再取 choices；失敗時錯誤體為 {"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"])成功時 usage 中包含 prompt_tokens 與 completion_tokens，開發期間建議每次皆列印，以便掌握成本。
請求體逐欄位拆解
四種語言發送的是同一個 JSON，先理解其結構，撰寫任何語言都只是翻譯。
| 欄位 | 必填 | 說明 |
|---|---|---|
| model | 是 | 固定為 uncensored。 |
| messages | 是 | 陣列，每項含 role 與 content，role 可取 system、user、assistant。 |
| max_tokens | 否 | 預設 2048，單次上限 16,000。撰寫長文需自行調大。 |
| temperature / top_p / stop | 否 | 標準採樣參數，原樣透傳。 |
| stream | 否 | 設為 true 時走 SSE 串流輸出。 |
你讀取響應時最常看的三個欄位是：choices[0].message.content 是正文，choices[0].finish_reason 告訴你是否正常結束或被長度截斷，usage 是本次的 token 用量。三處都讀，才算接入完整。
另外兩項硬限制請記好：請求體不超過 8 MB，每把 API 金鑰每分鐘 300 次請求。批量任務別一股腦並行請求，先設定一個簡單的並行上限。
Java：java.net.http
JDK 11 起內建 HttpClient，不需要任何相依套件。下面使用 JDK 15 的文字區塊撰寫 JSON，低版本可改為字串拼接，或使用你熟悉的 JSON 函式庫序列化。
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());
}
}提示：內容包含中文時，BodyPublishers.ofString 預設以 UTF-8 編碼，無需額外處理。生產環境請將 HttpClient 設為單例複用，不要每次請求都新建。
Go：net/http
Go 的標準函式庫同樣足夠。重點是不要使用預設的 http.DefaultClient 卻不設定超時，否則當對端卡住時 goroutine 會一直掛著。
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))
}響應體請用 io.ReadAll 讀完後再解析。需要結構化處理時，定義對應的 struct 並使用 encoding/json 反序列化即可，欄位就是 choices、message、content、usage 這些。
PHP：curl
PHP 使用 curl 擴充套件，json_encode 記得加上 JSON_UNESCAPED_UNICODE，否則中文會被轉成 \uXXXX，雖然能運作，但除錯時很難閱讀。
<?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";注意區分兩類失敗：curl_exec 返回 false 是網路層問題；返回了內容但狀態碼非 200，是介面層問題，請讀取 error.code。
首次呼叫常見的坑
- 401：Header 寫成了
Authorization: 金鑰，漏了Bearer前綴；或環境變數在新開的終端機裡沒生效。 - 404：路徑少了
/v1，或把chat/completions拼錯。 - 400：JSON 不合法，或 prompt 加上 max_tokens 超過 100,000 token 的上限。
- 402：餘額用完或試用過期。
- 輸出被截斷：
max_tokens預設 2048，單次最大 16,000，寫長文要明確調大。 - 想要串流：請求體加上
"stream": true，響應是 SSE，最後會自動追加一個帶 usage 的資料區塊。
跑通之後，下一步看 Prompt 寫法 調輸出品質，遇到報錯查 錯誤碼排障手冊。參數完整說明在 文件，價格見 價格頁。
跑通之後，上線前補三樣東西
教程裡的範例是最小可用版本，真要放進服務裡，至少補這三項。
- 超時。範例裡統一給了 120 秒，因為長文字生成確實慢。如果你的業務是同步等待，就按頁面容忍度縮短，並配合串流輸出，使用者能先看到字。
- 錯誤分流。401、402、403 屬於重試也沒用的錯誤，要報警或提示使用者；429 和 503 才值得退避重試。具體寫法放在排障手冊裡，這裡不展開。
- 用量記錄。每次響應的 usage 落一條日誌，只記數字，不要把使用者內容寫進日誌。月底對帳、查異常消耗都靠它。
再提一句金鑰管理：key 只有一把，洩漏後只能重新產生，而重新產生會讓所有在用的服務同時掉線。所以別把它散落在多個腳本和多台機器的設定裡，集中放在一個金鑰設定處，換起來才不會漏。
最後是內容邊界：合法的成人向內容、小說虛構和有爭議的話題不會被拒絕，但涉及未成年人的性內容一律攔截，返回 403，虛構和角色扮演也不例外。你的應用面向成年使用者時，建議在自己的註冊流程裡也做年齡確認。
最後給一個自檢順序，貼在顯示器邊上也行：金鑰在不在環境變數裡；models 通不通；請求體是不是合法 JSON；model 是不是無審查；max_tokens 夠不夠；響應裡 finish_reason 是 stop 還是 length；usage 有沒有記錄。七項全綠，接入就算完成。
