Tham chiếu Uncensored API, giải thích từng trường

Quy ước và vận chuyển

URL cơ sở là https://api.uncensoredapis.com/v1. Tất cả thân là JSON và UTF-8. Mọi yêu cầu đều mang Authorization: Bearer <key>; khóa thiếu hoặc sai sẽ trả về 401. Chỉ có hai tuyến đường, và bất kỳ đường dẫn nào khác sẽ trả về 404.

Phương thức	Đường dẫn	Mục đích
POST	/v1/chat/completions	Tạo tin nhắn trợ lý, tùy chọn được streaming
GET	/v1/models	Liệt kê id mô hình mà bạn có thể yêu cầu

API chỉ xử lý văn bản. Không có tuyến embeddings, hình ảnh, âm thanh hoặc video và không có fine-tuning, và có đúng một mô hình, được gọi là uncensored. Vì định dạng dây tương thích với quy ước hoàn thành trò chuyện, các SDK Python và Node chính thức hoạt động khi bạn ghi đè base_url. docs bao gồm thiết lập lần đầu; trang này là người bạn đồng hành cấp trường.

Các trường thân yêu cầu

Bảng liệt kê các trường mà endpoint hiểu. Các trường lấy mẫu được chuyển qua quá trình tạo không thay đổi, vì vậy các giá trị bạn chọn hoạt động như chúng sẽ trong bất kỳ API kiểu hoàn thành trò chuyện nào.

Trường	Loại	Ghi chú
model	chuỗi	Luôn là "uncensored".
messages	mảng	Các đối tượng có thứ tự với role (system, user, assistant, tool) và content.
max_tokens	số nguyên	Giới hạn hoàn thành. Mặc định 2048, tối đa 32.000.
temperature	số	Ngẫu nhiên. Thấp hơn thì xác định hơn.
top_p	số	Ngưỡng cắt lấy mẫu hạt nhân.
stop	chuỗi hoặc mảng	Các chuỗi kết thúc quá trình tạo.
stream	boolean	true chuyển phản hồi sang sự kiện gửi bởi máy chủ.
tools	mảng	Định nghĩa hàm theo định dạng JSON-schema tiêu chuẩn.

Dưới đây là một yêu cầu đầy đủ đã được chú thích. Tin nhắn hệ thống thiết lập hành vi, tin nhắn người dùng chứa nhiệm vụ và stop kết thúc quá trình sinh tại dòng trống đầu tiên.

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"]
  }'

Hai quy tắc về ngân sách rất quan trọng. Thứ nhất, prompt cộng với phần hoàn tất phải nằm trong 100,000 token, vì vậy một yêu cầu có số token prompt cộng với max_tokens vượt quá giới hạn này sẽ bị từ chối với mã 400. Thứ hai, phần thân được tuần tự hóa không được vượt quá 8 MB. Nếu bạn gửi các lịch sử dài, hãy cắt bớt các lượt tương tác cũ ở phía bạn trước khi chúng tiến gần đến bất kỳ giới hạn nào.

Đối tượng phản hồi

Một lệnh gọi không truyền phát trả về một đối tượng JSON. Bạn hãy đọc nó từ trên xuống dưới như sau.

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: một định danh duy nhất cho phần hoàn tất. Bạn hãy ghi lại nó cạnh ID yêu cầu của riêng bạn khi cần liên kết các sự kiện.
• object: hằng số chat.completion.
• created: dấu thời gian Unix tính bằng giây.
• model: lặp lại uncensored.
• choices: một mảng. Bạn nhận được một mục, vì vậy choices[0] là câu trả lời. index là vị trí của nó.
• choices[].message: role là assistant; content chứa văn bản, hoặc là null khi mô hình trả về các lệnh gọi công cụ.
• choices[].finish_reason: lý do quá trình sinh dừng lại; xem phần tiếp theo.
• usage: tính toán token cho mục đích thanh toán, được đề cập bên dưới.

Các giá trị finish_reason

Bạn hãy rẽ nhánh dựa trên finish_reason trước khi tin tưởng vào nội dung. Một câu trả lời bị cắt ngắn và một câu trả lời đầy đủ trông giống hệt nhau cho đến khi bạn kiểm tra nó.

Giá trị	Ý nghĩa	Mã của bạn nên làm gì
stop	Mô hình đã đạt đến điểm kết thúc tự nhiên hoặc kích hoạt một trong các chuỗi stop của bạn.	Sử dụng nội dung như hiện có.
length	Ngưỡng max_tokens (hoặc cửa sổ ngữ cảnh) đã được đạt giữa chừng.	Tăng max_tokens, rút ngắn prompt hoặc yêu cầu mô hình tiếp tục.
tool_calls	Mô hình muốn chạy một hoặc nhiều hàm.	Thực thi chúng và gửi kết quả lại dưới dạng tin nhắn tool.

Khi giá trị là tool_calls, tin nhắn có dạng như sau, với các đối số được cung cấp dưới dạng JSON string mà bạn phải tự phân tích:

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"
  }]
}

Luôn bao bọc json.loads hoặc JSON.parse với arguments trong xử lý lỗi, vì JSON được tạo ra đôi khi có thể bị lỗi cú pháp.

Khối usage và chi phí của nó

Báo cáo usage hiển thị prompt_tokens, completion_tokens và total_tokens. Đây là các con số dùng để tính phí trừ vào số dư của bạn: đầu vào giá $0.25 cho mỗi triệu token và đầu ra giá $1.00 cho mỗi triệu token. Số dư trả trước được trừ theo từng yêu cầu, không có gói đăng ký.

Một ví dụ chi tiết dưới các giả định đã nêu: giả sử một yêu cầu sử dụng 2.000 token prompt và 500 token hoàn tất. Chi phí đầu vào là 2.000 / 1.000.000 x $0,25 = $0,0005. Chi phí đầu ra là 500 / 1.000.000 x $1,00 = $0,0005. Tổng chi phí cho yêu cầu là $0,0010. Các số liệu token này là giả định cho mục đích tính toán, không phải là phép đo trên bất kỳ khối lượng công việc thực tế nào. Trang giá cả có các mức giá trong một nơi.

Vì các token đầu ra đắt gấp bốn lần so với token đầu vào, việc đặt max_tokens chặt chẽ là cách kiểm soát chi phí trực tiếp nhất của bạn.

Định dạng chunk truyền phát

Đặt "stream": true và phản hồi sẽ là text/event-stream. Mỗi sự kiện là một dòng bắt đầu bằng data: theo sau là JSON, được phân tách bởi một dòng trống. Loại đối tượng thay đổi thành chat.completion.chunk và message được thay thế bằng 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. Chunk đầu tiên thường đặt delta.role thành assistant với nội dung rỗng.
2. Các chunk nội dung mang một đoạn văn bản trong delta.content. Bạn hãy nối chúng lại theo thứ tự xuất hiện.
3. Phần nội dung cuối cùng có delta rỗng và finish_reason khác null.
4. Một chunk cuối cùng với mảng choices rỗng chứa usage. Bạn không yêu cầu nó; nó được thêm vào tự động.
5. data: [DONE] kết thúc luồng.

Hãy đề phòng mảng choices trống đó: truy cập choices[0] trên chunk usage sẽ gây ra lỗi trong các vòng lặp đơn giản. Ví dụ SDK bên dưới xử lý trường hợp này.

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")

Đối với các lệnh gọi công cụ được truyền phát, delta.tool_calls đến dưới dạng các mảnh; bạn hãy tích lũy chuỗi arguments theo chỉ mục gọi và phân tích một lần khi finish_reason là tool_calls.

Endpoint mô hình

GET /v1/models chỉ cần tiêu đề Bearer và trả về một đối tượng danh sách. Vì chỉ có một mô hình, data chứa một mục, uncensored. Các ứng dụng khách điền danh sách thả xuống mô hình từ tuyến này sẽ hiển thị một lựa chọn duy nhất.

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

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

Đây cũng là cách rẻ nhất để xác minh khóa: 200 có nghĩa là khóa hợp lệ, 401 có nghĩa là khóa sai hoặc đã được tạo lại. Gọi tuyến này không tạo ra token. Để xử lý trạng thái và quy tắc thử lại, xem bảng playbook về lỗi và giới hạn tốc độ.

Danh sách kiểm tra tham chiếu cho tác giả ứng dụng khách

Nếu bạn đang viết thư viện ứng dụng khách hoặc đóng gói endpoint trong một gateway, hãy xác minh từng hành vi này đối với đặc tả ở trên trước khi phát hành.

1. Duy trì tiêu đề chuẩn. Gửi khóa chỉ trong tiêu đề Authorization, không bao giờ trong chuỗi truy vấn và không bao giờ ghi lại giá trị tiêu đề.
2. Phân tích phòng thủ. Coi các trường bổ sung không xác định trong phản hồi là có thể bỏ qua. Hãy cố định trình phân tích của bạn vào các trường được tài liệu hóa ở đây thay vì theo thứ tự khóa JSON chính xác.
3. Kiểm tra finish_reason trên mọi phản hồi. Hiển thị một chỉ báo trực quan khi nó bằng length, vì người dùng nếu không sẽ đọc văn bản bị cắt cụt như một câu trả lời đầy đủ.
4. Ngân sách trước khi gửi. Ước lượng token prompt, cộng thêm max_tokens của bạn và so sánh tổng với 100,000. Từ chối cục bộ nhanh hơn là chờ mã 400.
5. Xử lý phần cuối luồng. Mong đợi một chunk với danh sách choices rỗng và đối tượng usage, sau đó [DONE]. Đóng kết nối sau khi gặp tín hiệu.
6. Ghi lại usage. Lưu trữ total_tokens cho mỗi yêu cầu để bạn có thể đối chiếu việc đo lường của mình với số dư trả trước sau này.
7. Tuân thủ giới hạn trên. Tài khoản cho phép 300 yêu cầu mỗi phút mỗi khóa, vì vậy một gateway phân phối cho nhiều người dùng cần hàng đợi riêng.

Không có bước nào trong số này phụ thuộc vào SDK của nhà cung cấp. Một máy khách HTTP cơ bản đặt tiêu đề Bearer và giải mã JSON là đủ, và các ví dụ SDK trên trang này chỉ là tiện ích, không phải yêu cầu. Kết hợp danh sách kiểm tra này với bảng lỗi trong playbook và bạn sẽ bao phủ toàn bộ vòng đời yêu cầu: xây dựng, gửi, truyền phát, phân tích, tính toán và khôi phục.