Chuyển đến nội dung
Bắt đầu nhanh

Bắt đầu nhanh

Thực hiện yêu cầu đầu tiên: lấy key, gửi một tin nhắn và đọc phản hồi. API dùng các định dạng của OpenAI và Anthropic, nên SDK bạn đang dùng sẽ hoạt động sau khi bạn đổi base URL và key.

1. Lấy key của bạn

Mỗi tài khoản có một API key. Hãy đăng nhập, mở Keys & usage và sao chép nó. Key dùng được trên mọi endpoint và mọi model. Keys & usage

2. Trỏ client của bạn tới API

Mọi endpoint nằm dưới một base URL. SDK của OpenAI nhận nó với /v1 ở cuối; SDK của Anthropic nhận nó không có, vì tự nó thêm /v1/messages.

Client Base URL
SDK của OpenAI và các client tương thích OpenAI https://api.shannon-ai.com/v1
SDK của Anthropic https://api.shannon-ai.com

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

Endpoint Định dạng
POST /v1/chat/completions OpenAI Chat Completions
POST /v1/messages Anthropic Messages
POST /v1/responses OpenAI Responses

3. Gửi yêu cầu đầu tiên

Gửi một tin nhắn user tới shannon-3 trên endpoint Chat Completions. Thay YOUR_API_KEY bằng key của bạn.

POST https://api.shannon-ai.com/v1/chat/completions

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1"
)

response = client.chat.completions.create(
    model="shannon-3",
    messages=[
        {"role": "user", "content": "Hello, Shannon!"}
    ],
    max_tokens=1024
)

print(response.choices[0].message.content)
Trường Loại Mặc định Mô tả
model string Id của model trả lời. Các id được liệt kê trên Models & pricing.
messages array Cuộc hội thoại cho đến nay: các đối tượng có role và content. Tin nhắn user cuối cùng là prompt. Bắt buộc.
max_tokens integer 4096 Ngân sách đầu ra của yêu cầu, từ 1 đến 65,536. Yêu cầu giữ số lượng này từ số dư của bạn và bị tính phí cho phần thực sự đã dùng.
stream boolean false true gửi câu trả lời từng phần một khi nó được viết.

Nội dung yêu cầu là JSON và cần header Content-Type: application/json. Danh sách đầy đủ các trường nằm ở trang endpoint. Chat Completions

Phản hồi

Lượt gọi không có stream trả về một đối tượng JSON khi câu trả lời hoàn tất. Các văn bản và con số bên dưới là ví dụ.

200 JSON
{
  "id": "chatcmpl-9b2f6c1e4a7d4f0f8a3c5d2e1b6a7c90",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! What would you like to work on?",
        "reasoning_content": "A greeting. A short, friendly reply fits."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1386,
    "completion_tokens": 74,
    "total_tokens": 1460
  }
}
Trường Loại Mô tả
id string chatcmpl- theo sau là 32 ký tự thập lục phân.
object string Luôn là chat.completion.
created integer Thời điểm của phản hồi, tính bằng giây Unix.
model string Id đã công bố của model đã trả lời, kể cả khi bạn gửi một bí danh hoặc cách viết khác.
choices array Luôn có đúng một mục, với index là 0.
choices[0].message.role string Luôn là assistant.
choices[0].message.content string | null Câu trả lời. Có thể là null khi phản hồi mang tool_calls.
choices[0].message.reasoning_content string | null Phần suy luận của model trước câu trả lời, hoặc null khi không có.
choices[0].message.tool_calls array Chỉ có khi model gọi một trong các tool bạn đã khai báo.
choices[0].finish_reason string stop cho một câu trả lời, tool_calls khi model gọi một tool.
usage.prompt_tokens integer Các token model đã đọc cho câu trả lời này. Trên shannon-2-* và dòng Shannon 3, con số này có thể nhiều hơn văn bản bạn đã gửi.
usage.completion_tokens integer Các token model đã viết.
usage.total_tokens integer Tổng số. Mức phí của model Shannon được tính từ con số này.
  • usage chứa số token, không phải tiền. Số mà lượt gọi lấy từ số dư của bạn được hiển thị theo từng yêu cầu ở Keys & usage; cách tính nằm ở trang Limits and balance. Giới hạn và số dư
  • Mọi phản hồi, kể cả lỗi và stream, đều có header x-request-id. Nếu yêu cầu của bạn mang header x-request-id, giá trị của nó được trả lại; nếu không, giá trị gồm 12 ký tự thập lục phân. Hãy giữ nó trong log của bạn: nó định danh đúng yêu cầu này.

Cùng lượt gọi đó dưới dạng stream

Đặt stream là true để đọc câu trả lời trong khi nó được viết. Mọi thứ khác trong yêu cầu giữ nguyên.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1"
)

stream = client.chat.completions.create(
    model="shannon-3",
    messages=[
        {"role": "user", "content": "Hello, Shannon!"}
    ],
    max_tokens=1024,
    stream=True
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Mỗi frame của stream là một dòng bắt đầu bằng data: và chứa một đối tượng JSON. Một frame, được in trên nhiều dòng:

Một frame
{
  "id": "chatcmpl-9b2f6c1e4a7d4f0f8a3c5d2e1b6a7c90",
  "object": "chat.completion.chunk",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "Hello! "
      },
      "finish_reason": null
    }
  ]
}
Các frame, theo thứ tự delta finish_reason
Trong khi model suy luận. Không hoặc nhiều frame. {"reasoning_content": "…"} null
Câu trả lời, từng phần một. Không hoặc nhiều frame. {"content": "…"} null
Frame JSON cuối cùng. Nó cũng mang usage; bạn không cần yêu cầu. {} "stop"
Kết thúc stream: dòng data: [DONE].
  • Phản hồi có trạng thái 200 và content-type: text/event-stream. Mỗi frame là một dòng data: <json> theo sau là một dòng trống.
  • Một dòng : ping đến mỗi 15 giây. Đó là một chú thích giữ kết nối mở; các client SSE bỏ qua nó.
  • Lỗi xảy ra sau khi stream đã mở sẽ đến dưới dạng một frame data: {"error": {…}}. Trạng thái vẫn là 200, vì vậy hãy kiểm tra các frame.

Truyền phát

Nếu lượt gọi thất bại

Lỗi là một đối tượng JSON có error chứa type và message. Đây là những phản hồi mà lượt gọi đầu tiên thường gặp nhất.

Trạng thái Loại Thông báo Ý nghĩa
401 authentication_error Missing authentication Không có key nào đến được API. Hãy gửi Authorization: Bearer theo sau là key của bạn.
401 authentication_error Invalid API key Key không phải là key hiện tại của một tài khoản. Hãy sao chép lại từ Keys & usage.
400 invalid_request_error unknown model: <id> model không phải là id đã công bố. Hãy dùng một id từ Models & pricing.
422 invalid_request_error Failed to deserialize the JSON body into the target type… Một trường có kiểu JSON sai, hoặc thiếu messages.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan Ngân sách đầu ra của yêu cầu không vừa với số dư của bạn.

Xử lý lỗi

Tiếp theo nên đi đâu

  • Model và giá — Chọn một model: id, cửa sổ ngữ cảnh và giá.
  • Chat Completions — Mọi trường yêu cầu, trường phản hồi và sự kiện stream của endpoint bạn đã gọi.
  • Truyền phát — Các frame của một stream, các dòng keep-alive và lỗi bên trong stream.
  • Gọi hàm — Để model gọi các hàm của bạn.
  • Giới hạn và số dư — Một yêu cầu giữ chỗ và tốn bao nhiêu, và bạn được gửi bao nhiêu yêu cầu.
  • Sân chơi API — Thử các yêu cầu trong trình duyệt bằng key của bạn.