设置 shell 并检查接口
从 API 密钥页面获取密钥,然后导出密钥和基础 URL,以免在每个命令中粘贴密钥。
export API_KEY="paste-your-key-here"
export BASE="https://api.uncensoredllmapi.com/v1"
每个请求都将密钥作为 Bearer token 发送在 Authorization 请求头中。请求体是 JSON 格式,因此 POST 时需要添加 Content-Type: application/json。请求体最大为 8 MB,这仅在你将非常大的文档粘贴到提示词中时才重要。
示例使用 Unix shell 的单引号。在 Windows PowerShell 上,将 JSON 放入文件中,并使用 --data @body.json 传递,以避免引号问题。
最便宜的健全性检查是列出模型的 GET 请求。它确认密钥和 URL,且不产生费用。
curl -s "$BASE/models" \
-H "Authorization: Bearer $API_KEY"
回复中的 data 数组应包含 ID uncensored。401 表示密钥缺失或拼写错误。如果 curl 完全无法连接,请检查 $BASE 中的主机,并确保它以 /v1 结尾,没有多余的路径。
1. 发送聊天补全请求
这是每个 OpenAI 风格客户端在底层发送的请求。
curl -s "https://api.uncensoredllmapi.com/v1/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Give me three names for a fantasy tavern."}
],
"temperature": 0.8,
"max_tokens": 200
}'
回复是 JSON 格式。文本位于 choices[0].message.content,token 计数在 usage 中。如果你安装了 jq 且只需要文本,请通过 jq -r '.choices[0].message.content' 处理输出。max_tokens 字段是可选的;不填写该字段,补全可能会使用 100,000 token 上下文窗口中剩余的所有 token。
如果你的客户端使用该格式,也可以使用更新的 POST /v1/responses 接口。有关参数的完整列表,请参阅 文档。
2. 流式输出答案
添加 "stream": true 并使用 -N 告诉 curl 不要缓冲。Token 将在生成时打印。
curl -N "$BASE/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"stream": true,
"messages": [{"role": "user", "content": "Count from one to ten in words."}]
}'
每行以 data: 开头,包含带有 delta 的小 JSON 块。最后的事件携带使用情况,流式输出以 data: [DONE] 结束。如果没有 -N,curl 会等待完整缓冲区,输出看起来像一次性到达。注意,流式请求会占用一个并发槽位,直到结束。
3. 请求 JSON
对于脚本将解析的输出,使用 response_format 开启 JSON 模式。在提示词中提到 JSON 一词,以便模型知道你期望的结构。
curl -s "$BASE/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"response_format": {"type": "json_object"},
"messages": [{"role": "user",
"content": "Return JSON with keys name and level for a fantasy character."}]
}' | jq -r '.choices[0].message.content | fromjson'
最终的 fromjson 过滤器解析 content 内的字符串,因此如果模型返回的不是有效 JSON,jq 会报错。这使得它成为一个方便的快速测试。更多模式见 JSON 模式页面。
4. 尝试工具调用
函数调用允许模型请求你的代码运行函数。你在 tools 数组中描述函数,如果模型决定使用它,回复中将包含 tool_calls 条目而不是文本。
curl -s "$BASE/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "What is the weather in Oslo?"}],
"tools": [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a city",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"]
}
}
}],
"tool_choice": "auto"
}' | jq '.choices[0].message.tool_calls'
你应该获得一个函数名和一个参数的 JSON 字符串。你的代码运行该函数,然后发送第二个请求,重复之前的消息,添加带有工具调用的助手消息,并添加一条包含 role: "tool" 的消息,其中包含结果。然后模型写出最终答案。
5. 检查标头和余额
添加 -i 以查看响应标头以及请求体。你将找到 X-Request-Id、X-Balance-USD、X-RateLimit-Limit-Requests 和 X-RateLimit-Limit-Concurrency。
curl -s -i "$BASE/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"ping"}],"max_tokens":5}' \
| grep -i "^x-"
curl -s "$BASE/balance" -H "Authorization: Bearer $API_KEY"
第二次调用直接返回你的余额。OpenAI 风格的工具可以使用 GET /v1/dashboard/billing/credit_grants 代替。像上面这样的小请求成本不到一分钱:使用 10 个输入 token 和 5 个输出 token,价格为 10 x 0.15 / 1,000,000 + 5 x 0.50 / 1,000,000 = $0.000004。请参阅 定价页面 获取费率。
可复用的冒烟测试脚本
一旦你信任单个调用,将它们包装在一个简短的脚本中,以便在任何部署、密钥轮换或网络更改后运行。它在第一个问题时失败,因此你可以确切地看到哪一步出错了。
set -euo pipefail
BASE="https://api.uncensoredllmapi.com/v1"
echo "models:"
curl -sf "$BASE/models" -H "Authorization: Bearer $API_KEY" | jq -r '.data[].id'
echo "chat:"
curl -sf "$BASE/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"Say ok."}],"max_tokens":5}' \
| jq -r '.choices[0].message.content'
echo "balance:"
curl -sf "$BASE/balance" -H "Authorization: Bearer $API_KEY"
-f 标志使 curl 在 HTTP 失败时退出并报错,set -e 会在脚本出错时停止。如果你在此 API 之上运行服务并希望尽早获得变更警告,请将其放入 cron 作业或 CI 步骤中。将密钥保存在密钥库或环境变量中,不要保存在脚本文件中。
当你更改请求时,一次尝试一个设置:temperature 用于随机性,top_p 用于核采样,stop 用于自定义结束序列,以及 seed 用于可重复输出。它们都传递给模型,因此你可以从相同的终端历史记录中比较它们的效果。
读取 curl 错误
| 状态码 | 可能原因 | 修复方法 |
|---|---|---|
| 401 | 密钥缺失或错误 | 检查 Authorization 标头并确认 $API_KEY 已导出 |
| 400 | JSON 格式错误或字段错误 | 发送前使用 jq . 验证请求体 |
429,代码 rate_limited | 每分钟超过 300 个请求(试用密钥为 60 个) | 减慢循环速度 |
429,代码 concurrency | 同时超过 8 个请求(试用密钥为 2 个) | 运行更少的并行作业 |
429 且 Retry-After: 5 | 临时过载 | 等待 5 秒并重试 |
添加 -w "\n%{http_code}\n" 以在响应体之后打印状态码,从而避免猜测。错误响应体是包含消息和代码的 JSON,因此 jq .error 可以清晰地显示它们。如果在循环中看到 429,不要立即重试;暂停几秒钟可以让分钟窗口和并发槽位清空,而紧密的重试循环只会让你超过限制。试用密钥的限制比完整密钥更严格,因此你的首次充值后能运行的脚本,如果在并行运行任务,可能会在试用额度上失败。请求正常后,切换到 SDK;相同的 URL 和模型名称保持不变。新账户可以一键领取 $0.50 的试用额度,足以进行数百次小型测试调用。之后的充值从 $20 起,支持加密货币支付(TRC20 上的 USDT 或 Base 上的 USDC)。
