Claude API phiên bản 2026-10-21: Có gì thay đổi và cách nâng cấp an toàn
Phiên bản Claude API 2026-10-21 là giá trị anthropic-version mới đầu tiên kể từ 2023-06-01. Nó tạo ra ba thay đổi phá vỡ tương thích đối với Messages API: temperature, top_p và top_k giờ trả về lỗi 400, các khối document trong tin nhắn assistant trả về lỗi 400, và citations trên các khối text trong tin nhắn user trả về lỗi 400. Nó cũng đổi tên một số trường của Admin API và Enterprise Analytics API. Bạn chọn tham gia bằng cách gửi anthropic-version: 2026-10-21 hoặc bằng cách nâng cấp lên các phiên bản SDK major mới (Python 2.0.0, TypeScript 1.0.0, Go 2.0.0 và những phiên bản khác).
Vấn đề nan giải: nâng cấp SDK chính là cách mà hầu hết các nhóm sẽ "vô tình" chuyển sang phiên bản mới. Một lệnh pip install -U anthropic hay npm update thông thường mà vượt qua một phiên bản major sẽ chuyển toàn bộ các request sang 2026-10-21 cùng một lúc. Hướng dẫn này liệt kê mọi thay đổi mà Anthropic công bố, chỉ ra những thay đổi nào thực sự gây ảnh hưởng trong code thực tế, và đưa ra thứ tự nâng cấp an toàn cho bạn.
Header anthropic-version là gì?
Header anthropic-version là một header request bắt buộc dùng để cố định hình dạng của Claude API mà bạn nhận được. Trong cùng một phiên bản, Anthropic giữ nguyên các tham số đầu vào và đầu ra hiện có, nhưng có thể thêm các đầu vào tùy chọn, giá trị đầu ra mới, các biến thể enum mới như kiểu sự kiện streaming, và các điều kiện lỗi mới. Các thay đổi phá vỡ tương thích chỉ đến cùng với một ngày phiên bản mới.
Theo trang versioning, tồn tại ba phiên bản:
| Phiên bản | Những gì nó giới thiệu |
|---|---|
2023-01-01 |
Bản phát hành đầu tiên |
2023-06-01 |
Các sự kiện server-sent được đặt tên theo từng bước cho streaming; loại bỏ sự kiện data: [DONE] và các giá trị exception và truncated cũ |
2026-10-21 |
Loại bỏ các tham số sampling, quy tắc nội dung tin nhắn chặt chẽ hơn, đổi tên các trường Admin và Analytics |
Nếu bạn dùng SDK chính thức, bạn không bao giờ tự đặt header. Mỗi phiên bản SDK major sẽ gửi phiên bản đang hiện hành tại thời điểm phiên bản major đó phát hành. Đó là lý do vì sao việc nâng cấp SDK và nâng cấp phiên bản API là cùng một sự kiện đối với hầu hết các codebase.
Các thay đổi phá vỡ tương thích của Claude API 2026-10-21
Những thay đổi này áp dụng cho POST /v1/messages, cho việc đếm token, và cho mọi request bên trong một Message Batch được tạo với 2026-10-21.
1. temperature, top_p và top_k bị loại bỏ
Đây là thay đổi mà hầu hết mọi người sẽ gặp phải. Bất kỳ request nào gửi temperature, top_p hoặc top_k đều trả về lỗi 400, trên mọi model, kể cả khi bạn gửi giá trị mặc định. Một dòng temperature: 1.0 còn sót lại trong file cấu hình cũng đủ để làm hỏng lệnh gọi.
Chất lượng đầu ra bị ảnh hưởng thế nào phụ thuộc vào model:
- Claude 4.7 và các phiên bản mới hơn vốn chỉ chấp nhận các giá trị sampling mặc định, nên việc loại bỏ các tham số không thay đổi gì về cách chúng sampling.
-
Các model cũ chấp nhận các giá trị khác, như Claude Sonnet 4.6, sẽ mất đi bất kỳ hiệu ứng nào bạn có được từ việc giảm
temperature. Hướng dẫn migration nói thẳng về điều này: không có cài đặt nào khác thay thế được nó.
Nếu một request thực sự phụ thuộc vào một giá trị không mặc định, Anthropic cho bạn hai lựa chọn: ngừng gửi nó, hoặc giữ riêng request đó ở 2023-06-01.
2. Các khối document trong tin nhắn assistant trả về lỗi 400
Một số ứng dụng phát lại lịch sử hội thoại với một khối document nằm trực tiếp trong một lượt assistant. Dưới 2026-10-21, điều đó bị từ chối. Hãy chuyển các document vào tin nhắn user. Một document được lồng bên trong một khối khác, chẳng hạn như kết quả công cụ web fetch mà Claude trả về, vẫn được chấp nhận.
3. citations trong tin nhắn user trả về lỗi 400
Một khối text có mảng citations không rỗng trong tin nhắn user giờ sẽ thất bại, và điều đó bao gồm cả văn bản bên trong các khối search_result. Hãy loại bỏ citations khỏi các khối đó. Citations trên chính các câu trả lời assistant của Claude mà bạn gửi lại vẫn ổn, và "citations": {"enabled": true} trên các document và kết quả tìm kiếm cũng vậy.
4. Đổi tên trường Admin API và Enterprise Analytics
Các phản hồi không còn bao gồm các tên trường cũ:
| Endpoint | Trường cũ | Trường mới |
|---|---|---|
| Nhóm RBAC | roles |
role_ids |
| Thành viên nhóm RBAC | group_id |
rbac_group_id |
| Vai trò RBAC | name |
display_name |
| Giới hạn tần suất của Organization và workspace | group_type |
group.type |
| API key | workspace_id |
scope.workspace_id |
| Báo cáo mức sử dụng và chi phí theo người dùng của Analytics | actor.email |
actor.email_address |
| Tóm tắt hoạt động của Analytics | summaries |
data |
Thay đổi về API key là thay đổi tinh tế nhất. Dưới 2023-06-01, workspace_id là null cho cả các key gắn với Default Workspace lẫn các key thuộc tất cả workspace. Dưới 2026-10-21, scope.workspace_id chứa ID thực của Default Workspace, và một key thuộc tất cả workspace có scope: {"type": "organization"} mà không có workspace_id. Nếu dashboard của bạn coi null là "Default Workspace", nó sẽ gán nhãn sai cho các key sau khi nâng cấp.
Các phiên bản SDK gửi 2026-10-21
Anthropic đã phát hành các phiên bản SDK major mới vào ngày 21 tháng 10 năm 2026, và mỗi phiên bản mặc định gửi 2026-10-21, theo release notes:
| SDK | Phiên bản đầu tiên trên 2026-10-21 |
|---|---|
Python (anthropic) |
2.0.0 |
TypeScript (@anthropic-ai/sdk) |
1.0.0 |
Go (anthropic-sdk-go/v2) |
2.0.0 |
Java (anthropic-java) |
3.0.0 |
C# (Anthropic) |
13.0.0 |
PHP (anthropic-ai/sdk) |
1.0.0 |
Ruby (anthropic) |
2.0.0 |
CLI ant
|
2.0.0 |
Các phiên bản major mới cũng mang đến những thay đổi hoàn toàn không phụ thuộc vào phiên bản API:
-
API key được gửi dưới dạng
Authorization: Bearer <key>thay vìX-Api-Key. Claude API chấp nhận cả hai, nhưng một proxy, gateway, bộ lọc log hay test stub đọcX-Api-Keysẽ không còn thấy key nữa. - Text Completions bị loại bỏ khỏi các SDK TypeScript, Go, Java và Ruby cũng như khỏi CLI. Hãy dùng Messages API.
-
betaskhông còn trong các phương thức Models không phải beta. Hãy gọiclient.beta.modelsthay thế. -
MessageParamlà một union với một kiểu cho mỗi role trong các SDK có định kiểu, nên một số chú thích kiểu cần được cập nhật. -
Go cần một đường dẫn import mới kết thúc bằng
/v2, và người dùng TypeScript trên các gói Bedrock, Vertex, Foundry, AWS hoặc Google Cloud phải chuyển chúng sang v1 trong cùng lần nâng cấp, nếu không trình quản lý gói sẽ cài một bản sao cũ hơn thứ hai của SDK lõi. - Giấy phép đã thay đổi từ MIT sang Apache 2.0.
Hãy ghim phiên bản major hiện tại của bạn trước khi làm bất cứ điều gì khác. Điều đó ngăn một bot quản lý dependency nâng cấp bạn giữa sprint.
Ngoại lệ Amazon Bedrock
Trên Amazon Bedrock, 2026-10-21 chỉ hoạt động với các model Claude 4.7 và mới hơn. Nếu bạn vẫn gọi Opus 4.6 hoặc một model cũ hơn ở đó, hãy giữ nguyên phiên bản SDK hiện tại hoặc tiếp tục gửi header hiện tại của bạn, và chuyển model trước.
Cách nâng cấp lên Claude API phiên bản 2026-10-21 một cách an toàn
Thứ tự trong hướng dẫn migration là: chuyển phiên bản, sửa các thay đổi phá vỡ tương thích, kiểm thử trước khi phát hành. Đây là cách điều đó diễn ra trong thực tế.
-
Ghim phiên bản SDK major cũ. Ví dụ
anthropic<2trong Python hoặc"@anthropic-ai/sdk": "^0"trong npm. -
Tìm kiếm trong code và cấu hình của bạn các từ
temperature,top_p,top_k,X-Api-Key,completions.create, và bất kỳ trường Admin API nào trong bảng ở trên. - Quyết định về sampling. Trên Claude 4.7 và mới hơn, hãy xóa các tham số. Trên các model cũ hơn, hoặc chấp nhận sampling mặc định hoặc giữ những lệnh gọi đó ở 2023-06-01.
-
Sửa việc xây dựng tin nhắn. Chuyển các document phía assistant sang lượt user và loại bỏ
citationskhỏi các khối văn bản của user. - Kiểm thử cùng các payload dưới cả hai phiên bản và so sánh mã trạng thái cũng như hình dạng phản hồi.
- Nâng cấp SDK và phát hành các sửa lỗi code cùng nhau. Anthropic nói rằng hãy phát hành bản nâng cấp cùng với các sửa lỗi của bạn, chứ không phải trước đó.
Không dùng SDK thì việc chuyển đổi chỉ là một header:
curl https://api.anthropic.com/v1/messages \
-H "x-[REDACTED CREDENTIAL] \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello, Claude"}]
}'
Thêm "temperature": 0.2 vào body đó và bạn sẽ nhận lỗi 400. Gửi cùng body đó với anthropic-version: 2023-06-01 và nó thành công. Cặp kết quả đó chính là điều mà bước 5 nên bắt được cho mọi payload bạn gửi trong môi trường production.
Để Claude Code kiểm thử cả hai phiên bản với Apidog CLI
Bước 5 thật tẻ nhạt khi làm thủ công: bạn có hàng tá hình dạng payload, và mỗi cái cần chạy hai lần. Hãy giao việc đó cho coding agent của bạn. Apidog CLI cung cấp cho Claude Code (hoặc Codex, Cursor và OpenCode) các lệnh để tạo test case và chạy chúng, để agent thực hiện việc so sánh còn bạn đọc bản tóm tắt.
Thiết lập một lần:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick Claude Code when prompted
Sau đó đưa cho Claude Code một [REDACTED PROMPT]
In Apidog project , create an environment "claude-api" with base URL
https://api.anthropic.com. For each JSON payload in ./fixtures/claude/, add a
POST /v1/messages test case that sends the header anthropic-version: {{anthropic_version}}
and asserts status 200 and a non-empty content array. Run every case twice, once with
anthropic_version=2023-06-01 and once with 2026-10-21, and list each case that passes
on the old version but fails on the new one, with the error message.
Agent kiểm tra schema của từng payload trước khi viết bất cứ thứ gì, rồi chạy các case:
bash
apidog environment create claude-api --project --base-url https://api.anthropic.com
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project --file case.json
apidog run --test-case --project -e --env-var "anthropic_version=2023-06-01" -r cli,json
apidog run --test-case --project -e --env-var "anthropic_version=2026-10-21" -r cli,json
Cờ `--env-var` hoán đổi giá trị header mà không cần chạm vào test case, nên khác biệt chỉ là một biến. Thêm `--upload-report` để xem cả hai lần chạy trong ứng dụng Apidog, hoặc đưa lần chạy 2026-10-21 vào CI với `-r junit` để một lần cập nhật dependency không thể đưa một trường `temperature` lên production. [Hướng dẫn Apidog CLI trong Claude Code](https://apidog.com/vi/blog/apidog-cli-in-claude-code?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) trình bày chi tiết hơn về việc thiết lập, và [tài liệu tham chiếu `apidog run`](https://apidog.com/vi/blog/apidog-run-command-reference?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) liệt kê mọi cờ. Gói Free của Apidog hỗ trợ tối đa 4 người dùng.
## 2023-06-01 có bị deprecated không?
Chưa có ngày ngừng hỗ trợ nào được công bố. Trang versioning liệt kê 2023-06-01 mà không có thông báo deprecation, và chính hướng dẫn migration cũng khuyên bạn giữ các request cần `temperature` không mặc định ở 2023-06-01. Anthropic vẫn khuyến nghị dùng phiên bản mới nhất "bất cứ khi nào có thể".
Điều đó quan trọng cho việc lập kế hoạch. Việc nâng cấp hôm nay là tùy chọn, nhưng 2026-10-21 là phiên bản mới đầu tiên sau hơn ba năm, và các thay đổi phá vỡ tương thích trong tương lai sẽ đến theo cùng cách, nên việc coi kiểm thử phiên bản là một công việc CI thường quy ngay từ bây giờ sẽ rẻ hơn so với một cuộc migration gấp gáp sau này. Nếu bạn đang tinh chỉnh quanh [giới hạn tần suất Claude API](https://apidog.com/vi/blog/claude-api-rate-limits?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) hoặc [chi phí Claude API](https://apidog.com/vi/blog/claude-api-cost?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation), hãy thêm kiểm tra phiên bản vào cùng pipeline đó. Hướng dẫn của chúng tôi về [các thực hành tốt nhất khi đánh phiên bản API](https://apidog.com/vi/blog/api-versioning-best-practices?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) giải thích vì sao các phiên bản dựa trên ngày như phiên bản này giúp việc đó dễ dàng hơn.
## Câu hỏi thường gặp
### Tôi có phải nâng cấp lên Claude API phiên bản 2026-10-21 ngay bây giờ không?
Không. 2023-06-01 vẫn hoạt động và không có ngày ngừng hỗ trợ nào được công bố. Bạn nâng cấp khi bạn gửi header mới hoặc cài một phiên bản SDK major mặc định dùng nó.
### Tại sao request của tôi trả về lỗi 400 sau khi nâng cấp SDK?
Các phiên bản SDK major mới gửi 2026-10-21, phiên bản này từ chối `temperature`, `top_p` và `top_k`, các khối `document` phía assistant và `citations` trên các khối văn bản của user. Hãy kiểm tra payload của bạn để tìm những thứ đó trước tiên.
### Tôi có thể giữ temperature cho một số request không?
Có, bằng cách giữ riêng những request đó ở 2023-06-01. Dưới 2026-10-21 không có cài đặt thay thế, và các model Claude 4.7 và mới hơn vốn chỉ sampling với các giá trị mặc định.
### 2026-10-21 có hoạt động trên Amazon Bedrock không?
Chỉ với các model Claude 4.7 và mới hơn. Các model Bedrock cũ hơn cần phiên bản SDK hoặc header hiện tại của bạn cho đến khi bạn chuyển model.
### Proxy của tôi có còn thấy API key của tôi không?
Không, nếu nó đọc `X-Api-Key`. Các SDK mới gửi key dưới dạng `[REDACTED CREDENTIAL] Hãy cập nhật proxy để đọc `Authorization`, hoặc tự cấu hình SDK để gửi `X-Api-Key`.
### Phiên bản mới có thay đổi các sự kiện streaming không?
Anthropic không liệt kê thay đổi định dạng streaming nào cho 2026-10-21. Định dạng streaming bạn dùng hôm nay đến từ 2023-06-01.
Top comments (0)