Tài liệu

Hai dòng. Mọi công cụ.

Công cụ nào bên dưới cũng chỉ cần hai thứ: base URL của apmix và khóa API của bạn. Dán khóa một lần là mọi đoạn mã trên trang này sẵn sàng để sao chép.

Base URL

https://api.apmix.ai/v1Tương thích OpenAI
Chat Completions và Responses. Dành cho Codex, Cursor, OpenCode, Kilo Code, Pi, Kimi, Grok, Hermes và các SDK.
https://api.apmix.aiTương thích Anthropic
Messages API. Dành cho Claude Code và các SDK của Anthropic.

Thiết lập của bạn

Lấy khóa →

Khóa API

Chỉ lưu trong tab này và chỉ dùng để điền vào các đoạn mã trên trang.

Mô hình

Mỗi công cụ có sẵn một mô hình mặc định hợp lý. Bạn có thể chọn bất kỳ mô hình nào trong danh mục.

base_url: https://api.apmix.ai
api_key: apx_live_YOUR_KEY
model: claude-sonnet-5

Chọn công cụ của bạn

12 công cụ

01
Cài đặt Claude Code
Cần Node.js 18 trở lên. Bỏ qua bước này nếu máy bạn đã cài.
Terminal
```
npm install -g @anthropic-ai/claude-code
```
02
Trỏ tới apmix
Claude Code dùng giao thức Anthropic nên base URL không có /v1. Đặt ba biến này trong terminal mà bạn dùng để chạy nó.
```
export ANTHROPIC_BASE_URL="https://api.apmix.ai"
export ANTHROPIC_AUTH_TOKEN="apx_live_YOUR_KEY"
export ANTHROPIC_MODEL="claude-sonnet-5"
```
Dán khóa ở trên để tự điền vào đây
03
Lưu cố định
Ghi các giá trị tương tự vào ~/.claude/settings.json để mọi terminal mới đều dùng được ngay. Script sẽ sao lưu tệp hiện có trước; nếu bạn đã có cấu hình, hãy gộp khối env vào thay vì thay thế cả tệp.
~/.claude/settings.json
```
mkdir -p ~/.claude
[ -f ~/.claude/settings.json ] && cp ~/.claude/settings.json ~/.claude/settings.json.bak
cat > ~/.claude/settings.json <<'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.apmix.ai",
    "ANTHROPIC_AUTH_TOKEN": "apx_live_YOUR_KEY",
    "ANTHROPIC_MODEL": "claude-sonnet-5"
  }
}
EOF
```
Dán khóa ở trên để tự điền vào đây
04
Chạy
Khởi động Claude Code trong dự án của bạn. Đổi mô hình bất cứ lúc nào bằng /model, với bất kỳ ID Claude nào trong danh mục.
Terminal
```
cd your-project
claude
```

Xác minh

Kiểm tra xem khóa đã hoạt động chưa.

Liệt kê các mô hình mà khóa của bạn truy cập được. Nhận về danh sách JSON nghĩa là khóa và URL đều đúng; lỗi 401 nghĩa là khóa sai hoặc đã hết hạn.

curl https://api.apmix.ai/v1/models -H "Authorization: Bearer apx_live_YOUR_KEY"

Dán khóa ở trên để tự điền vào đây

Không thấy công cụ của bạn?

Công cụ nào cho phép đặt base URL của OpenAI hoặc Anthropic đều dùng được với apmix. Tìm trường Base URL hoặc Custom provider, dán URL và khóa của bạn, rồi dùng một ID mô hình trong danh mục.

Vẫn chưa được? Gửi email tới support@apmix.ai kèm tên công cụ và ID yêu cầu của bạn.

Lỗi

Mọi lỗi, mã số và cách xử lý.

API trả về mã trạng thái HTTP chuẩn cùng phần thân JSON nêu tên lỗi. code không bao giờ thay đổi nên bạn có thể dựa vào nó để đối chiếu; message được viết cho người đọc. Mỗi phản hồi cũng có header x-apmix-request-id — hãy ghi kèm khi bạn viết cho support@apmix.ai.

Hai định dạng, tùy theo endpoint

Endpoint tương thích OpenAI (/v1/chat/completions, /v1/responses, /v1/models, /v1/usage)

HTTP/1.1 429 Too Many Requests
x-apmix-request-id: req_5b1f…

{
  "error": {
    "message": "Your monthly allowance is used up. …",
    "type": "insufficient_quota",
    "code": "allowance_exhausted",
    "param": null
  }
}

Endpoint tương thích Anthropic (/v1/messages, /v1/messages/count_tokens)

HTTP/1.1 429 Too Many Requests
x-apmix-request-id: req_5b1f…

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Your monthly allowance is used up. …",
    "code": "allowance_exhausted"
  }
}

Trạng tháiMãKhi nào xảy raCách xử lý

400Yêu cầu không hợp lệ

400
invalid_json
invalid_request_error
Khi nào xảy ra: Không thể phân tích phần thân yêu cầu thành JSON.
Cách xử lý: Kiểm tra dấu ngoặc kép, dấu phẩy và header Content-Type: application/json.
400
missing_model
invalid_request_error
Khi nào xảy ra: Yêu cầu thiếu trường model.
Cách xử lý: Thêm một ID mô hình trong danh mục, ví dụ claude-sonnet-4-6.
400
bad_request
invalid_request_error
Khi nào xảy ra: Mô hình từ chối một tham số (sai kiểu, tùy chọn không được hỗ trợ, nội dung quá dài).
Cách xử lý: Đọc message; nó nêu lại lý do từ mô hình. Sửa tham số rồi gửi lại.

401Xác thực

401
missing_api_key
authentication_error
Khi nào xảy ra: Chưa gửi khóa. Mọi endpoint đều cần khóa, kể cả GET /v1/models, vì danh mục phụ thuộc vào gói của bạn.
Cách xử lý: Gửi Authorization: Bearer apx_live_… (hoặc x-api-key với các endpoint Anthropic).
401
invalid_api_key
authentication_error
Khi nào xảy ra: Khóa không tồn tại hoặc đã bị xóa.
Cách xử lý: Sao chép lại từ Bảng điều khiển → Khóa API, hoặc tạo khóa mới.
401
key_expired
authentication_error
Khi nào xảy ra: Khóa đã quá ngày hết hạn mà bạn đặt khi tạo.
Cách xử lý: Tạo khóa mới; thời hạn của khóa không thể kéo dài.

403Quyền truy cập

403
model_not_in_plan
permission_error
Khi nào xảy ra: Mô hình có tồn tại nhưng thuộc gói cao hơn gói của bạn, hoặc tài khoản chưa có gói. message nêu tên mô hình, gói cần có và gói hiện tại của khóa.
Cách xử lý: Gọi GET /v1/models bằng chính khóa đó — kết quả chỉ liệt kê những mô hình gói của bạn gọi được — hoặc nâng cấp trong Bảng điều khiển → Thanh toán.
403
event_not_started
permission_error
Khi nào xảy ra: Mô hình thuộc một sự kiện cộng đồng chưa mở. message cho biết thời điểm bắt đầu.
Cách xử lý: Chờ hết đếm ngược trên apmix.ai/event, hoặc tạm dùng mô hình khác.
403
event_ended
permission_error
Khi nào xảy ra: Quỹ token chung của sự kiện đã cạn, hoặc sự kiện đã đóng.
Cách xử lý: Chuyển sang mô hình khác. Sự kiện tiếp theo sẽ được thông báo trên apmix.ai/event.
403
account_suspended
permission_error
Khi nào xảy ra: Tài khoản bị tạm khóa do vi phạm điều khoản.
Cách xử lý: Gửi email tới support@apmix.ai từ địa chỉ email của tài khoản.
403
account_on_hold
permission_error
Khi nào xảy ra: Một khoản thanh toán của tài khoản đang được kiểm tra; các yêu cầu sẽ tạm dừng cho đến khi hoàn tất.
Cách xử lý: Bạn không cần làm gì. Hãy để ý email, hoặc viết cho support@apmix.ai nếu quá một ngày.

404Không tìm thấy

404
model_not_found
not_found_error
Khi nào xảy ra: ID mô hình không xác định hoặc mô hình đã ngừng hoạt động.
Cách xử lý: Dùng ID từ /v1/models hoặc trang Mô hình. Có thể dùng tiền tố tên hãng như anthropic/.
404
not_found
not_found_error
Khi nào xảy ra: Đường dẫn hoặc phương thức không tồn tại.
Cách xử lý: Dùng POST /v1/chat/completions, POST /v1/responses, POST /v1/messages, GET /v1/models hoặc GET /v1/usage.

429Giới hạn

429
allowance_exhausted
insufficient_quota · rate_limit_error
Khi nào xảy ra: Bạn đã dùng hết token quy đổi của tháng. type là insufficient_quota, giống OpenAI.
Cách xử lý: Nâng cấp trong Bảng điều khiển → Thanh toán, hoặc chờ đến ngày gia hạn hiển thị ở trang Tổng quan.
429
daily_limit_reached
rate_limit_error
Khi nào xảy ra: Bạn đã chạm giới hạn hằng ngày do chính bạn đặt trong Cài đặt → Giới hạn.
Cách xử lý: Nâng hoặc bỏ giới hạn, hoặc chờ đến nửa đêm UTC.
429
weekly_limit_reached
rate_limit_error
Khi nào xảy ra: Bạn đã chạm giới hạn hằng tuần do chính bạn đặt trong Cài đặt → Giới hạn.
Cách xử lý: Nâng hoặc bỏ giới hạn, hoặc chờ đến 00:00 UTC thứ Hai.
429
rate_limit_exceeded
rate_limit_error
Có thể thử lại
Khi nào xảy ra: Hơn 60 yêu cầu trong một phút trên cùng một khóa.
Cách xử lý: Chờ retry-after giây. Chia các tác vụ nặng ra nhiều khóa.
429
upstream_rate_limited
rate_limit_error
Có thể thử lại
Khi nào xảy ra: Bản thân mô hình đang quá tải.
Cách xử lý: Thử lại với thời gian chờ tăng dần (1s, 2s, 4s). Không bị tính phí.

502Nhà cung cấp

502
upstream_error
api_error
Có thể thử lại
Khi nào xảy ra: Mô hình trả về phản hồi bị lỗi hoặc không như mong đợi.
Cách xử lý: Thử lại một lần; nếu vẫn lỗi, hãy thử mô hình khác. Không bị tính phí.

503Không khả dụng

503
upstream_unavailable
api_error · overloaded_error
Có thể thử lại
Khi nào xảy ra: Mô hình hết thời gian chờ hoặc đang bảo trì.
Cách xử lý: Thử lại sau giây lát hoặc đổi mô hình. Không bị tính phí.
503
no_provider
api_error · overloaded_error
Có thể thử lại
Khi nào xảy ra: Mô hình tạm thời không có tuyến hoạt động ở phía chúng tôi (hiếm gặp, thường khi bảo trì).
Cách xử lý: Thử lại sau vài phút hoặc chọn mô hình khác.

Các lỗi được đánh dấu “có thể thử lại” chỉ là tạm thời: đợi một hai giây rồi gửi lại đúng yêu cầu đó (hầu hết SDK tự làm việc này với lỗi 429 và 5xx). Các lỗi còn lại đòi hỏi bạn phải sửa gì đó ở phía mình trước.

Các header phản hồi hữu ích

x-apmix-request-id: ID duy nhất của yêu cầu này. Hãy ghi kèm khi bạn gửi email tới support@apmix.ai.
x-apmix-remaining: Số token quy đổi còn lại trong hạn mức hằng tháng của bạn sau yêu cầu này.
x-apmix-weighted-tokens: Chi phí của yêu cầu này, đã nhân hệ số của mô hình.
retry-after: Số giây cần chờ; được gửi kèm lỗi rate_limit_exceeded.