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) import OpenAI from 'openai';
const client = new OpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://api.shannon-ai.com/v1'
});
const response = await client.chat.completions.create({
model: 'shannon-3',
messages: [
{ role: 'user', content: 'Hello, Shannon!' }
],
max_tokens: 1024
});
console.log(response.choices[0].message.content); package main
import (
"context"
"fmt"
openai "github.com/sashabaranov/go-openai"
)
func main() {
config := openai.DefaultConfig("YOUR_API_KEY")
config.BaseURL = "https://api.shannon-ai.com/v1"
client := openai.NewClientWithConfig(config)
resp, err := client.CreateChatCompletion(
context.Background(),
openai.ChatCompletionRequest{
Model: "shannon-3",
Messages: []openai.ChatCompletionMessage{
{Role: "user", Content: "Hello, Shannon!"},
},
MaxTokens: 1024,
},
)
if err != nil {
panic(err)
}
fmt.Println(resp.Choices[0].Message.Content)
} curl -X POST "https://api.shannon-ai.com/v1/chat/completions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "shannon-3",
"messages": [
{"role": "user", "content": "Hello, Shannon!"}
],
"max_tokens": 1024
}' | 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ụ.
{
"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. |
-
usagechứ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 headerx-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) import OpenAI from 'openai';
const client = new OpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://api.shannon-ai.com/v1'
});
const stream = await client.chat.completions.create({
model: 'shannon-3',
messages: [
{ role: 'user', content: 'Hello, Shannon!' }
],
max_tokens: 1024,
stream: true
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
} curl -N -X POST "https://api.shannon-ai.com/v1/chat/completions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "shannon-3",
"messages": [
{"role": "user", "content": "Hello, Shannon!"}
],
"max_tokens": 1024,
"stream": 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:
{
"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
200vàcontent-type: text/event-stream. Mỗi frame là một dòngdata: <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.
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. |
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.