Uncensored API 参考，逐字段详解

约定与传输

基础 URL 为 https://api.uncensoredapis.com/v1。所有请求体均为 JSON 和 UTF-8 格式。每个请求都携带 Authorization: Bearer <key>；密钥缺失或错误将返回 401。仅存在两条路由，其他任何路径均返回 404。

方法	路径	用途
POST	/v1/chat/completions	生成助手消息，支持流式输出
GET	/v1/models	列出你可以请求的模型 ID

API 仅支持文本。没有嵌入、图像、音频或视频路由，也没有微调，且只有一个模型，标识为 uncensored。由于传输格式兼容 chat completions 约定，当你覆盖 base_url 时，官方 Python 和 Node SDK 即可使用。文档涵盖首次运行设置；本页面是字段级配套指南。

请求体字段

该表列出了接口理解的字段。采样字段原样传递给生成过程，因此你选择的值在任何聊天补全式 API 中的行为方式相同。

字段	类型	备注
model	string	始终为 "uncensored"。
messages	array	带有 role（system、user、assistant、tool）和 content 的有序对象。
max_tokens	integer	补全上限。默认 2048，最大 32,000。
temperature	number	随机性。值越低越确定。
top_p	number	核采样截断值。
stop	string or array	结束生成的序列。
stream	boolean	true 将回复切换为服务器发送事件。
tools	数组	标准 JSON-schema 格式中的函数定义。

这是一个完整的带注释的请求。系统消息设置行为，用户消息承载任务，stop 在第一个空行处结束生成。

Copycurl https://api.uncensoredapis.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "You are a terse release-notes writer."},
      {"role": "user", "content": "Summarize: fixed login bug, added dark mode."}
    ],
    "max_tokens": 120,
    "temperature": 0.4,
    "stop": ["\n\n"]
  }'

两条预算规则至关重要。首先，提示词加上补全内容必须容纳在 100,000 token 内，因此如果请求的提示词 token 数加上 max_tokens 超过该限制，请求将被拒绝并返回 400。其次，序列化请求体不得超过 8 MB。如果你发送长历史记录，请在接近任一限制之前，在客户端截断旧的对话轮次。

响应对象

非流式调用返回一个 JSON 对象。请按以下顺序从头到尾读取。

Copy{
  "id": "chatcmpl-example123",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "uncensored",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "v1.4: Login bug fixed. Dark mode added."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 38,
    "completion_tokens": 14,
    "total_tokens": 52
  }
}

• id：补全的唯一标识符。当需要关联事件时，请将其记录在你的请求 ID 旁边。
• object：常量 chat.completion。
• created：Unix 时间戳（秒）。
• model：回显 uncensored。
• choices：数组。你只会收到一个条目，因此 choices[0] 即为答案。index 表示其位置。
• choices[].message：role 为 assistant；content 包含文本，或者当模型返回工具调用时为 null。
• choices[].finish_reason：生成停止的原因；详见下一节。
• usage：用于计费的 token 统计，详见下文。

finish_reason 值

在信任内容之前，请先根据 finish_reason 进行分支判断。截断的答案和完整的答案在检查之前看起来是一样的。

值	含义	你的代码应执行的操作
stop	模型达到了自然结束点，或触发了你的 stop 序列。	直接使用该内容。
length	max_tokens 上限（或上下文窗口）在回答过程中被触及。	增加 max_tokens，缩短提示词，或要求模型继续生成。
tool_calls	模型希望执行一个或多个函数。	执行它们并将结果作为 tool 消息发送回去。

当值为 tool_calls 时，消息如下所示，参数以 JSON string 形式传递，你需要自行解析：

Copy{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc1",
        "type": "function",
        "function": {"name": "get_order", "arguments": "{\"order_id\": 8841}"}
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

在错误处理中，务必对 json.loads 或 JSON.parse 的 arguments 进行包裹，因为生成的 JSON 偶尔可能格式不正确。

usage 块及其成本

usage 报告 prompt_tokens、completion_tokens 和 total_tokens。这些是用于计算你余额扣减的数字：输入按每百万 token $0.25 计费，输出按每百万 token $1.00 计费。预付额度按请求扣除，无订阅费用。

在给定假设下的计算示例：假设一次请求使用了 2,000 个提示词 token 和 500 个补全 token。输入费用为 2,000 / 1,000,000 x $0.25 = $0.0005。输出费用为 500 / 1,000,000 x $1.00 = $0.0005。该请求总计 $0.0010。这些 token 数量是用于算术计算的假设，并非对任何实际负载的测量。定价页面集中列出了费率。

由于输出 token 的成本是输入 token 的四倍，严格的 max_tokens 设置是你最直接的成本控制手段。

流式输出块格式

设置 "stream": true，响应将变为 text/event-stream。每个事件是一行，以 data: 开头，后跟 JSON，由空行分隔。对象类型变为 chat.completion.chunk，message 被 delta 替换。

Copydata: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"v1.4: "},"finish_reason":null}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Login bug fixed."},"finish_reason":null}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":38,"completion_tokens":14,"total_tokens":52}}

data: [DONE]

1. 第一个块通常将 delta.role 设置为 assistant，且内容为空。
2. 内容块在 delta.content 中携带片段。按到达顺序将它们拼接起来。
3. 最后一个内容块的 delta 为空，且包含非空的 finish_reason。
4. 最后一个块包含空的 choices 数组，并携带 usage。你无需请求它；它会自动添加。
5. 字面量 data: [DONE] 终止流式输出。

防范空的 choices 数组：在简单循环中对 usage chunk 索引 choices[0] 会引发错误。下面的 SDK 示例处理了该情况。

Copyimport os
from openai import OpenAI

client = OpenAI(base_url="https://api.uncensoredapis.com/v1", api_key=os.environ["API_KEY"])

reason, usage = None, None
for chunk in client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Name three uses of a rubber duck in debugging."}],
    stream=True,
):
    if chunk.choices:
        piece = chunk.choices[0].delta.content
        if piece:
            print(piece, end="", flush=True)
        if chunk.choices[0].finish_reason:
            reason = chunk.choices[0].finish_reason
    if getattr(chunk, "usage", None):
        usage = chunk.usage

print("\nfinish:", reason, "| tokens:", usage.total_tokens if usage else "n/a")

对于流式输出的工具调用，delta.tool_calls 以片段形式到达；按调用索引累积 arguments 字符串，并在 finish_reason 为 tool_calls 时解析一次。

模型接口

GET /v1/models 只需要 Bearer 头并返回一个列表对象。因为只有一个模型，data 包含一个条目 uncensored。因此，从该路由填充模型下拉列表的客户端将只显示一个选项。

Copycurl https://api.uncensoredapis.com/v1/models -H "Authorization: Bearer $API_KEY"

{
  "object": "list",
  "data": [
    {"id": "uncensored", "object": "model"}
  ]
}

这也是验证密钥最便宜的方式：200 表示密钥有效，401 表示密钥错误或已被重新生成。调用此路由不会生成 token。有关状态处理和重试规则，请参阅 错误和速率限制手册。

客户端作者参考清单

如果你正在编写客户端库或在网关中封装接口，请在发布前根据上述规范验证以下行为。

1. 头部整洁。 仅在 Authorization 头中发送密钥，绝不在查询字符串中发送，也绝不记录头值。
2. 防御性解析。 将响应中的未知额外字段视为可忽略。将解析器固定在此处记录的字段上，而不是固定的 JSON 键顺序。
3. 检查每个回复的 finish_reason。 当其等于 length 时，显示可见指示器，否则用户会将截断的文本误读为完整答案。
4. 发送前估算预算。 估算提示词 token，加上你的 max_tokens，并将总和与 100,000 进行比较。本地拒绝比等待 400 错误更快。
5. 处理流式尾部。 预期一个包含空 choices 列表和 usage 对象的块，然后是 [DONE]。在哨兵之后关闭连接。
6. 记录用量。 存储每个请求的 total_tokens，以便稍后根据预付额度核对你自己的计量数据。
7. 遵守上限。 账户允许每个密钥每分钟 300 个请求，因此扇出许多用户的网关需要自己的队列。

这些步骤都不依赖于供应商 SDK。设置 Bearer 头并解码 JSON 的普通 HTTP 客户端就足够了，本页面中的 SDK 示例只是便利，而非必需。将此检查清单与 手册 中的错误表结合使用，即可覆盖整个请求生命周期：构建、发送、流式输出、解析、账户和恢复。