Tổng quan

Endpoint

Mọi endpoint nằm dưới một base URL và được phục vụ qua HTTPS.

https://api.shannon-ai.com

Ba endpoint tạo văn bản dùng chung các model. Hãy chọn endpoint có định dạng mà mã của bạn đang dùng.

Kiến thức cơ bản về yêu cầu

• Nội dung của mọi POST là một đối tượng JSON, tối đa 32 MiB.
• Trường mà API không biết không gây lỗi và không có tác dụng. Một yêu cầu viết cho nhà cung cấp khác sẽ không thất bại vì có thêm một trường.
• Trường đã biết với kiểu JSON sai, hoặc thiếu trường bắt buộc, được trả lời bằng 422. Nội dung không phải JSON hợp lệ được trả lời bằng 400.
• model là một trong các id trên Models & pricing. Chữ hoa và chữ thường không quan trọng.

Phản hồi là JSON, hoặc một luồng server-sent events khi yêu cầu đặt stream là true. Mỗi endpoint trả lời theo định dạng riêng. Mọi phản hồi đều có header x-request-id.

Một yêu cầu phải qua những bước nào

Một yêu cầu được kiểm tra theo thứ tự cố định trước khi model chạy. Bước kiểm tra đầu tiên thất bại sẽ trả lời, nên 401 chưa cho bạn biết gì về nội dung.

Dạng của lỗi

Lỗi là một đối tượng JSON có error chứa type và message. /v1/messages bọc nó theo cách các SDK Anthropic mong đợi; mọi đường dẫn khác dùng dạng của OpenAI.

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

• Hãy đọc type và message. code và param chỉ có ở một số lỗi: hãy coi chúng là tùy chọn. param luôn là null.
• Sau khi stream đã bắt đầu, trạng thái đã là 200. Khi đó lỗi đến dưới dạng một error frame bên trong stream.
• Mọi phản hồi lỗi đều mang header x-request-id.

Xử lý lỗi

Thanh toán và số dư

• Mỗi tài khoản có một số dư, và chat và API dùng chung: hạn mức gói hôm nay trước, rồi đến tín dụng đã mua. API không có hạn ngạch riêng.
• Một yêu cầu giữ ngân sách đầu ra của nó (max_tokens, mặc định 4,096) và sau đó bị tính phí cho số token thực sự đã dùng, theo giá của model.
• Mọi phản hồi báo cáo số token trong usage. Trang Keys & usage hiển thị số dư và chi phí của từng yêu cầu.
• Mọi yêu cầu được phục vụ như nhau. Giới hạn duy nhất về tốc độ yêu cầu là flood protection: 120 yêu cầu mỗi phút cho mỗi tài khoản. Các yêu cầu gửi song song sẽ xếp hàng chờ.

Giới hạn và số dư Model và giá Keys & usage

Các trường phụ thuộc vào model

Mọi model nhận cùng một yêu cầu. Một vài trường chỉ có hiệu lực trên một số model; bảng nêu rõ ở đâu. Các trang endpoint liệt kê mọi trường.

Chat Completions

Nếu bạn đến từ SDK của OpenAI

• Đặt base URL là https://api.shannon-ai.com/v1 và key là key Shannon của bạn. Khi đó các lượt gọi Chat Completions và Responses hoạt động với SDK nguyên trạng.
• model phải là một id Shannon. Tên model của nhà cung cấp khác, như gpt-4o, được trả lời bằng 400 và unknown model.
• Phần suy luận nằm trong một trường riêng: reasoning_content bên cạnh content, trong tin nhắn và trong các delta của stream.
• Một stream luôn mang usage trong chunk cuối cùng, cùng với finish_reason.
• Một lần gọi tool trong stream đến dưới dạng một chunk với chuỗi arguments hoàn chỉnh.
• Một phản hồi có một choice.
• Các đường dẫn của API OpenAI không có trong bảng trên, như /v1/embeddings, được trả lời bằng 404.

Nếu bạn đến từ SDK của Anthropic

• Đặt base URL là https://api.shannon-ai.com, không có /v1, và key là key Shannon của bạn. SDK gửi nó dưới dạng x-api-key.
• model phải là một id Shannon.
• max_tokens là tùy chọn trên API này. Mặc định của nó là 4,096.
• Một phản hồi chứa các khối nội dung loại thinking, text và tool_use. Khối đầu tiên không phải lúc nào cũng là văn bản: hãy chọn khối theo type.
• stop_reason là end_turn hoặc tool_use. Một luồng stream của model Shannon cũng có thể kết thúc với max_tokens.
• anthropic-version và anthropic-beta được chấp nhận, nên SDK hoạt động mà không cần thay đổi. Yêu cầu không cần chúng.
• Lỗi trên /v1/messages có dạng của Anthropic: {"type": "error", "error": {…}}.

Các công cụ lập trình dùng các định dạng này được thiết lập theo cách tương tự: base URL, key, và một id Shannon làm model. Công cụ lập trình CLI