Tài liệu tham khảo API¶

Claudin.io là một API tương thích với OpenAI. Nếu bạn đã từng dùng API OpenAI, mọi thứ ở đây đều quen thuộc — chỉ cần trỏ đến base URL của Claudin.io và dùng model claudinio.

URL gốc¶

https://api.claudin.io

Các route kiểu OpenAI nằm dưới /v1.

Xác thực¶

Gửi API key của bạn kèm theo mọi yêu cầu, ở một trong hai header sau:

Authorization: Bearer YOUR_API_KEY

x-api-key: YOUR_API_KEY

Model¶

ID model	Cửa sổ ngữ cảnh
`claudinio`	256K tokens

Hãy dùng claudinio ở mọi nơi. (Một số client mong đợi dạng provider/model — với những client đó, hãy dùng claudinio/claudinio.)

Các endpoint¶

Phương thức & đường dẫn	Mô tả
`POST /v1/chat/completions`	Chat completions — endpoint chính
`POST /v1/completions`	Text completions kế thừa
`POST /v1/messages`	Định dạng Anthropic Messages
`POST /v1/responses`	Responses API (Codex)
`POST /v1/embeddings`	Text embeddings
`GET /v1/models`	Liệt kê các model khả dụng

Chat completions¶

curl https://api.claudin.io/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "claudinio",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Write a haiku about proxies."}
    ],
    "temperature": 0.7
  }'

Các tham số chuẩn của OpenAI đều được hỗ trợ: messages, temperature, top_p, max_tokens, stream, stop, tools / tool_choice (gọi hàm), response_format, v.v. Có hai tham số có giới hạn đáng để bạn biết trước khi gửi: max_tokens bị kẹp giữa một mức sàn và một mức trần, còn n phải là 1.

`max_tokens` và suy luận¶

Các model Claudinio suy luận trước khi trả lời, và các token suy luận được tính vào max_tokens — cùng một ngân sách bao gồm cả chuỗi suy nghĩ nội bộ lẫn câu trả lời hiển thị. Do đó, một giá trị max_tokens nhỏ có thể bị tiêu gần như toàn bộ vào suy luận, khiến câu trả lời bị cắt cụt giữa chừng.

Để ngăn điều đó, các giá trị dưới 32000 sẽ tự động được nâng lên 32000. Ở đầu còn lại, các giá trị trên 393216 sẽ bị hạ xuống 393216 — mức tối đa mà các model chấp nhận — bởi vì một con số lớn hơn sẽ bị từ chối thẳng thừng thay vì được coi là "càng nhiều càng tốt". Mọi giá trị nằm giữa hai mốc này đều được truyền qua nguyên vẹn, và việc bỏ qua tham số này luôn ổn.

max_tokens là một mức trần, không phải một khoản đặt trước: bạn chỉ bị tính phí cho các token thực sự được sinh ra, vì vậy một giá trị rộng rãi không tốn thêm gì.

Nếu bạn phân tích cú pháp đầu ra có cấu trúc (JSON, XML, một định dạng chặt chẽ), hãy kiểm tra finish_reason trước khi phân tích — "length" nghĩa là phản hồi đã chạm giới hạn token và chưa hoàn chỉnh, vì vậy việc phân tích thất bại là điều có thể dự đoán thay vì là vấn đề model bị lỗi:

choice = response.choices[0]
if choice.finish_reason == "length":
    ...  # truncated — retry with a larger max_tokens
data = json.loads(choice.message.content)

Nhiều completions (`n`)¶

Chỉ n = 1 được hỗ trợ. Gửi n lớn hơn 1 sẽ trả về 400 kèm "code": "unsupported_parameter"; bỏ qua tham số này luôn an toàn.

Các model Claudinio suy luận trước khi trả lời, và lượt suy luận chỉ tạo ra một luồng suy nghĩ duy nhất — không có cách nào rẻ để tách nó thành nhiều ứng viên độc lập, vì vậy phía upstream cũng không cung cấp. Nếu bạn muốn nhiều hơn một ứng viên, hãy gửi yêu cầu nhiều lần (temperature cao hơn sẽ cho bạn sự đa dạng), và lưu ý rằng mỗi lần gửi đều bị tính phí riêng.

Chúng tôi từ chối n > 1 thay vì âm thầm trả về một lựa chọn duy nhất: một client yêu cầu bốn nhưng nhận được một thường sẽ lỗi ở giai đoạn sau, ngay trong mã của chính nó, mà không có lỗi nào từ phía chúng tôi để giải thích lý do.

Streaming¶

Đặt "stream": true để nhận các server-sent events theo định dạng streaming của OpenAI (các khối data: {...} được kết thúc bằng data: [DONE]).

Tool / function calling¶

claudinio hỗ trợ tool calls. Truyền tools và đọc lại tool_calls từ phản hồi, giống hệt như với API OpenAI. Đây chính là điều giúp nó hoạt động bên trong các trình soạn thảo agentic như Claude Code, Kilo và Cursor.

Đầu vào đa phương thức¶

claudinio là một model văn bản, nhưng Claudin.io xử lý một cách trong suốt các khối hình ảnh, âm thanh và video: nếu bạn gửi chúng, proxy sẽ chuyển đổi thành các mô tả/bản phiên âm văn bản trước khi model nhìn thấy. Bạn không cần làm gì đặc biệt — chỉ cần gửi các content blocks chuẩn của OpenAI là nó hoạt động.

Lỗi¶

Các lỗi tuân theo cấu trúc lỗi của OpenAI:

{ "error": { "message": "…", "type": "…", "code": "…" } }

Trạng thái	Ý nghĩa	Việc cần làm
`401`	API key không hợp lệ hoặc bị thiếu	Kiểm tra key và header xác thực
`403`	Endpoint không được phép	Dùng một trong các đường dẫn `/v1/*` được hỗ trợ
`402`	Không có gói đăng ký đang hoạt động	Đăng ký — thử lại sẽ không giúp ích gì
`429`	Đã chạm giới hạn ngân sách hoặc bị giới hạn tốc độ	Chờ cửa sổ được đặt lại (xem header `Retry-After`) hoặc nâng cấp
`400`	Yêu cầu sai định dạng	Kiểm tra JSON / tham số của bạn — xem `max_tokens` và `n`
`5xx`	Sự cố thoáng qua từ upstream/nhà cung cấp	Thử lại với backoff

Chi tiết nhà cung cấp được ẩn đi có chủ đích

Các thông báo lỗi được làm sạch để không làm lộ nhà cung cấp model bên dưới. Bạn sẽ luôn thấy các lỗi mang thương hiệu Claudin.io và có cấu trúc kiểu OpenAI.

Chạm giới hạn ngân sách¶

Khi bạn dùng hết hạn mức bảo vệ chi tiêu của cửa sổ hiện tại, các yêu cầu sẽ trả về 429 kèm header Retry-After cho biết số giây còn lại cho đến khi cửa sổ được đặt lại. Dashboard của bạn hiển thị thời điểm đặt lại chính xác và ngân sách còn lại. Hãy giãn nhịp theo header đó thay vì thử lại ngay lập tức. Xem Gói & giới hạn để biết cách hoạt động của các cửa sổ.

Một tin nhắn thay cho `429`¶

Trên một số ít tài khoản, chúng tôi đang thử một câu trả lời khác cho cùng tình huống. Thay vì lỗi, yêu cầu vẫn hoàn tất và chính nội dung trả lời sẽ giải thích rằng đã chạm trần và khi nào trần được đặt lại. Chúng tôi đang đo xem cách này có đưa thông tin đến người dùng đáng tin cậy hơn một lỗi bị tác nhân của họ nuốt đi lặng lẽ hay không — và liệu khi được nói rõ, họ có muốn chuyển sang gói vừa tầm hay không.

Nếu bạn xây dựng tự động hoá, đừng đọc 2xx là "đã làm xong việc". Hãy xem một phản hồi nói rằng đã chạm trần đúng là đã chạm trần, và chờ đến khi cửa sổ được đặt lại. 429 ở trên vẫn là hành vi mặc định và là thứ gần như mọi tài khoản nhận được.

Giới hạn tốc độ¶

Claudin.io không chặn cứng việc sử dụng bình thường. Tốc độ yêu cầu ở mức lạm dụng sẽ bị làm chậm lại (một cơ chế throttle minh bạch) thay vì bị từ chối, vì vậy các client hoạt động tốt sẽ không bao giờ bị phạt. Trên thực tế, bạn không cần làm gì cả — chỉ cần thử lại trong trường hợp hiếm gặp 429.