Khóa API Codex, giải thích cho nhà phát triển

Hiểu định dạng Khóa API

Khi bạn đăng ký dịch vụ cung cấp codex api key, bạn nhận được một chuỗi ký tự chữ-số duy nhất. Khóa này đóng vai trò là thông tin xác thực cho mọi yêu cầu gửi đến máy chủ. Định dạng thường tuân theo một mẫu chuẩn, chẳng hạn như sk-... hoặc các tiền tố tương tự, tùy thuộc vào cách triển khai của nhà cung cấp. Tuy nhiên, vì bạn đang sử dụng proxy độc lập, tiền tố chính xác có thể khác. Yếu tố quan trọng không phải là định dạng, mà là đảm bảo khóa được truyền đúng trong tiêu đề Authorization của HTTP dưới dạng Bearer <your_key>.

Khóa API của bạn được liên kết với một tài khoản và gói sử dụng cụ thể. Không giống như một số dịch vụ tạo nhiều khóa cho các môi trường khác nhau (dev vs. prod), cách thiết lập của chúng tôi rất đơn giản: một tài khoản, một khóa. Nếu bạn mất khóa hoặc nghi ngờ nó đã bị xâm phạm, bạn có thể tạo lại nó ngay lập tức từ bảng điều khiển của mình. Điều này sẽ thu hồi khóa cũ ngay lập tức, đảm bảo không có quyền truy cập trái phép nào tồn tại. Hãy nhớ cập nhật các biến môi trường hoặc tệp cấu hình của bạn bất cứ khi nào bạn xoay khóa.

Thực tiễn bảo mật tốt nhất

• Lưu khóa của bạn trong các biến môi trường, không phải trong mã nguồn của bạn.
• Không bao giờ commit codex api key của bạn vào các kho lưu trữ công khai.
• Sử dụng chức năng tạo lại nếu bạn nghi ngờ khóa bị lộ.

Lỗi phổ biến: 401 Không được ủy quyền

Lỗi 401 Unauthorized là vấn đề phổ biến nhất khi tích hợp khóa API mới. Lỗi này cho thấy máy chủ đã từ chối thông tin xác thực của bạn. Trong ngữ cảnh của claude code proxy hoặc bất kỳ endpoint tương thích OpenAI nào, điều này gần như luôn có nghĩa là khóa bị thiếu, sai hoặc đã hết hạn.

Để khắc phục sự cố, trước tiên hãy xác minh rằng bạn đang sao chép khóa chính xác như được cung cấp. Khóa thường phân biệt chữ hoa chữ thường và có thể chứa khoảng trắng nếu được sao chép không chính xác. Đảm bảo bạn đang sử dụng base URL đúng cho khu vực hoặc gói dịch vụ của mình. Nếu bạn vừa tạo lại khóa, hãy đảm bảo client của bạn đang sử dụng giá trị mới. Lỗi 401 không liên quan đến số dư sử dụng hoặc giới hạn tốc độ của bạn; đó đơn thuần là lỗi xác thực.

Danh sách kiểm tra để giải quyết

1. Xác nhận chuỗi khóa API khớp chính xác với bảng điều khiển.
2. Xác minh định dạng tiêu đề Authorization: Authorization: Bearer YOUR_KEY.
3. Kiểm tra xem base URL có đúng cho loại tài khoản của bạn không.
4. Đảm bảo không có khoảng trắng thừa nào được thêm vào trong quá trình sao chép-dán.

Vượt quá giới hạn tốc độ: Lỗi 429

Khi bạn vượt quá khối lượng yêu cầu cho phép, API sẽ trả về lỗi 429 Too Many Requests. Đối với dịch vụ của chúng tôi, giới hạn được đặt là 300 yêu cầu mỗi phút trên mỗi khóa. Giới hạn này được áp dụng để đảm bảo sử dụng công bằng và duy trì độ trễ thấp cho tất cả người dùng. Nếu bạn đang chạy các phiên mã hóa khối lượng lớn, bạn có thể đạt đến giới hạn này nhanh chóng, đặc biệt nếu mã của bạn kích hoạt nhiều yêu cầu nội bộ.

Khi xảy ra lỗi 429, phản hồi thường bao gồm tiêu đề Retry-After cho biết số giây bạn nên chờ trước khi thử lại. Việc triển khai backoff theo cấp số nhân trong mã client của bạn là cách tiêu chuẩn để xử lý các lỗi này một cách duyên dáng. Thay vì thử lại ngay lập tức, hãy chờ một khoảng thời gian ngắn, sau đó nhân đôi thời gian chờ cho các lần thử lại tiếp theo. Điều này ngăn ứng dụng của bạn làm ngập máy chủ bằng các yêu cầu trong khi giới hạn được đặt lại.

Điều quan trọng cần lưu ý là giới hạn tốc độ được áp dụng cho mỗi khóa, không phải cho mỗi tài khoản. Nếu bạn có nhiều thiết bị hoặc quy trình sử dụng cùng một khóa, chúng sẽ chia sẻ ngân sách 300 yêu cầu/phút. Hãy cân nhắc sử dụng các khóa riêng biệt cho các môi trường khác nhau nếu bạn cần thông lượng tổng hợp cao hơn.

Cấu hình Base URL chính xác

Base URL là nền tảng của bất kỳ tích hợp API nào. Đối với dịch vụ tương thích OpenAI, base URL xác định nơi yêu cầu của bạn được gửi. Base URL của chúng tôi là https://api.claudecodeapikey.com/v1. URL này phải được cấu hình trong thư viện client hoặc SDK của bạn trước khi thực hiện bất kỳ yêu cầu nào. Nếu bạn sử dụng base URL sai, bạn sẽ nhận được lỗi kết nối hoặc phản hồi không mong đợi.

Nhiều nhà phát triển sử dụng SDK chính thức của OpenAI cho Python, Node.js hoặc các ngôn ngữ khác. Để chuyển sang proxy của chúng tôi, bạn chỉ cần cập nhật cấu hình base URL. Ví dụ: trong Python, bạn có thể đặt base_url='https://api.claudecodeapikey.com/v1'. Đảm bảo rằng giao thức (https) và đường dẫn (/v1) đều chính xác. Bỏ qua đường dẫn /v1 là một lỗi phổ biến dẫn đến lỗi 404.

Luôn xác minh rằng client của bạn đang gửi yêu cầu đến endpoint chính xác. Bạn có thể làm điều này bằng cách kiểm tra nhật ký mạng của mình hoặc sử dụng công cụ như curl để kiểm tra kết nối. Một kết nối thành công với base URL xác nhận rằng cấu hình của bạn là chính xác.

Xử lý phản hồi truyền phát

Phản hồi truyền phát cho phép bạn nhận các phần của phản hồi API khi chúng được tạo, thay vì chờ toàn bộ phản hồi hoàn tất. Điều này rất quan trọng đối với các tác nhân mã hóa hiển thị các đoạn mã theo thời gian thực. API của chúng tôi hỗ trợ truyền phát qua các Sự kiện được gửi qua máy chủ (SSE). Khi bạn bật truyền phát trong client của mình, bạn sẽ nhận được một luồng các chunk, mỗi chunk chứa một phản hồi một phần.

Để bật truyền phát, hãy đặt tham số stream thành true trong yêu cầu của bạn. Thư viện client sau đó sẽ tự động xử lý giao thức SSE. Bạn có thể xử lý từng chunk khi nó đến, cập nhật giao diện người dùng hoặc ghi lại tiến trình. Điều này cung cấp trải nghiệm người dùng tốt hơn, đặc biệt đối với các quá trình tạo mã dài.

Truyền phát không thay đổi mô hình nền hoặc các khả năng của nó. Đó đơn thuần là một cơ chế vận chuyển. Mô hình vẫn xử lý toàn bộ prompt và tạo ra phản hồi đầy đủ; sự khác biệt nằm ở cách đầu ra được chuyển đến client của bạn.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.claudecodeapikey.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarise this thread without softening it."}],
)
print(resp.choices[0].message.content)

Sự cố cấu hình Gọi công cụ

Gọi công cụ (hoặc gọi hàm) cho phép LLM yêu cầu các hành động cụ thể, chẳng hạn như chạy một đoạn mã hoặc truy vấn cơ sở dữ liệu. API của chúng tôi hỗ trợ gọi công cụ, nghĩa là bạn có thể định nghĩa các hàm trong yêu cầu của mình và nhận phản hồi JSON có cấu trúc từ mô hình. Điều này rất quan trọng đối với các tác nhân mã hóa nâng cao cần tương tác với các hệ thống bên ngoài.

Để cấu hình gọi công cụ, bạn phải cung cấp danh sách các định nghĩa hàm trong tham số tools. Mỗi công cụ nên có tên, mô tả và lược đồ tham số. Mô hình sau đó sẽ quyết định khi nào gọi một công cụ dựa trên prompt. Nếu mô hình quyết định gọi một công cụ, phản hồi sẽ bao gồm một mảng tool_calls với tên hàm và các đối số.

Các vấn đề phổ biến nảy sinh từ các định nghĩa lược đồ JSON không chính xác. Đảm bảo rằng các loại tham số và các trường bắt buộc của bạn được chỉ định chính xác. Nếu lược đồ không hợp lệ, mô hình có thể không gọi công cụ chính xác. Hãy kiểm tra các định nghĩa công cụ của bạn với các prompt đơn giản để xác minh rằng mô hình hiểu hành vi dự kiến.

Giới hạn cửa sổ ngữ cảnh

Cửa sổ ngữ cảnh xác định lượng văn bản tối đa mà mô hình có thể xử lý trong một yêu cầu duy nhất, bao gồm cả prompt (đầu vào) và completion (đầu ra). Mô hình của chúng tôi có cửa sổ ngữ cảnh là 100.000 token. Đây là một lượng văn bản đáng kể, nhưng nó không phải là vô hạn. Nếu prompt của bạn cộng với đầu ra dự kiến vượt quá giới hạn này, API sẽ trả về lỗi.

Để quản lý ngữ cảnh hiệu quả, hãy theo dõi việc sử dụng token trong các prompt của bạn. Các tệp dài hoặc lịch sử hội thoại rộng rãi có thể nhanh chóng tiêu thụ các token có sẵn. Nếu bạn tiến gần đến giới hạn, hãy cân nhắc cắt ngắn các tin nhắn cũ hơn hoặc tóm tắt các tương tác trước đó. Một số client tự động xử lý điều này bằng cách trượt cửa sổ, nhưng tốt nhất là nên biết giới hạn để tránh các lỗi không mong đợi.

Hãy nhớ rằng cửa sổ ngữ cảnh bao gồm tất cả các token được gửi đến mô hình, bao gồm cả tin nhắn hệ thống, tin nhắn người dùng và tin nhắn trợ lý. Hãy lập kế hoạch ngân sách token của bạn tương ứng để đảm bảo hoạt động trơn tru trong các phiên mã hóa dài.

Tạo lại Khóa của bạn

Việc tạo lại khóa API của bạn là một quy trình đơn giản nhằm đảm bảo tính bảo mật. Nếu bạn nghi ngờ khóa của mình đã bị lộ hoặc muốn xoay đổi thông tin xác thực theo định kỳ, bạn có thể tạo khóa mới từ bảng điều khiển của mình. Khóa cũ sẽ bị vô hiệu hóa ngay lập tức, vì vậy bất kỳ yêu cầu nào đang sử dụng khóa cũ sẽ bị lỗi.

Khi bạn tạo lại khóa, hãy đảm bảo cập nhật tất cả các máy khách và cấu hình của bạn với giá trị mới. Điều này bao gồm các biến môi trường, tệp cấu hình và bất kỳ giá trị nào được mã hóa cứng trong mã của bạn. Việc không cập nhật tất cả các vị trí có thể dẫn đến lỗi xác thực cho một số phần trong ứng dụng của bạn.

Dịch vụ của chúng tôi cho phép tạo lại khóa không giới hạn. Không có hình phạt nào khi bạn xoay đổi khóa thường xuyên. Đây là một thực hành tốt để duy trì bảo mật, đặc biệt là trong các môi trường chia sẻ hoặc khi phân phối khóa cho các thành viên trong nhóm.

Copycurl https://api.claudecodeapikey.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Write a blunt product review of a cheap VPN."}]
  }'