快速开始

发出第一个请求：获取密钥，发送一条消息，读取回复。该 API 支持 OpenAI 和 Anthropic 格式，因此你正在使用的 SDK 只需更改基础 URL 和密钥即可工作。

1. 获取密钥

每个账户有一个 API 密钥。登录后打开密钥与用量并复制它。该密钥适用于所有端点和所有模型。密钥与用量

2. 让客户端指向 API

所有端点都位于同一个基础 URL 下。OpenAI SDK 需要在末尾加上 /v1；Anthropic SDK 则不加，因为它会自己添加 /v1/messages。

客户端	基础 URL
OpenAI SDK 和兼容 OpenAI 的客户端	`https://api.shannon-ai.com/v1`
Anthropic SDK	`https://api.shannon-ai.com`

有三个端点可生成文本。它们访问相同的模型；选择与你代码已有格式一致的那个。

端点	格式
`POST /v1/chat/completions`	OpenAI Chat Completions
`POST /v1/messages`	Anthropic Messages
`POST /v1/responses`	OpenAI Responses

3. 发送第一个请求

在 Chat Completions 端点上向 shannon-3 发送一条 user 消息。将 YOUR_API_KEY 替换为你的密钥。

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
  }'

字段	类型	默认值	说明
`model`	`string`		作答模型的 id。这些 id 列在模型与定价页面。
`messages`	`array`		到目前为止的对话：带有 `role` 和 `content` 的对象。最后一条 `user` 消息就是提示词。必填。
`max_tokens`	`integer`	`4096`	请求的输出预算，从 1 到 65,536。请求会从你的余额中预留这个数量，并按实际使用量收费。
`stream`	`boolean`	`false`	`true` 会在回答生成的同时分段发送。

请求体是 JSON，需要标头 Content-Type: application/json。完整的字段列表见端点页面。 Chat Completions

不带 stream 的调用会在回答完成后返回一个 JSON 对象。下面的文本和数字仅为示例。

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
  }
}

字段	类型	说明
`id`	`string`	`chatcmpl-` 后跟 32 个十六进制字符。
`object`	`string`	始终为 `chat.completion`。
`created`	`integer`	回复的时间，以 Unix 秒表示。
`model`	`string`	作答模型的已发布 id，即使你发送的是别名或其他写法也是如此。
`choices`	`array`	始终只有一个条目，`index` 为 0。
`choices[0].message.role`	`string`	始终为 `assistant`。
`choices[0].message.content`	`string \| null`	回答。当回复带有 `tool_calls` 时，它可以是 `null`。
`choices[0].message.reasoning_content`	`string \| null`	模型在回答之前的推理，没有时为 `null`。
`choices[0].message.tool_calls`	`array`	仅当模型调用了你声明的某个工具时才出现。
`choices[0].finish_reason`	`string`	回答为 `stop`；模型调用工具时为 `tool_calls`。
`usage.prompt_tokens`	`integer`	模型为这次回答读取的 tokens。在 `shannon-2-*` 和 Shannon 3 系列上，这可能多于你发送的文本。
`usage.completion_tokens`	`integer`	模型写出的 tokens。
`usage.total_tokens`	`integer`	总数。Shannon 模型的费用由这个数字计算得出。

usage 包含的是 token 数，而不是金额。该调用从你的余额中扣除了多少，会在密钥与用量中按请求显示；计算方式见限额与余额。限制与余额
每个回复，包括错误和流，都带有标头 x-request-id。如果你的请求带有 x-request-id 标头，其值会原样返回；否则该值为 12 个十六进制字符。请将它保存在你的日志中：它唯一标识这一次请求。

同一个调用，改用流

将 stream 设为 true，即可在回答生成的同时读取它。请求中的其他内容都保持不变。

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
  }'

流中的每个帧是以 data: 开头的一行，内容为一个 JSON 对象。下面是一个帧，分成多行显示：

一个帧

{
  "id": "chatcmpl-9b2f6c1e4a7d4f0f8a3c5d2e1b6a7c90",
  "object": "chat.completion.chunk",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "Hello! "
      },
      "finish_reason": null
    }
  ]
}

帧，按顺序	delta	finish_reason
模型推理期间。零个或多个帧。	`{"reasoning_content": "…"}`	`null`
回答，一段一段到达。零个或多个帧。	`{"content": "…"}`	`null`
最后一个 JSON 帧。它同时携带 `usage`；你不必特意请求。	`{}`	`"stop"`
流的结尾：这一行 `data: [DONE]`。

回复的状态码为 200，content-type: text/event-stream。每个帧是一行 data: <json>，后面跟一个空行。
每 15 秒会收到一行 : ping。它是用来保持连接的注释；SSE 客户端会跳过它。
流打开之后发生的失败会以帧 data: {"error": {…}} 到达。状态码仍然是 200，所以请检查这些帧。

流式

如果调用失败

错误是一个 JSON 对象，其 error 中包含 type 和 message。以下是首次调用最常遇到的回复。

状态码	类型	消息	含义
`401`	`authentication_error`	`Missing authentication`	API 没有收到密钥。请发送 `Authorization: Bearer` 加上你的密钥。
`401`	`authentication_error`	`Invalid API key`	该密钥不是任何账户的当前密钥。请从密钥与用量页面重新复制。
`400`	`invalid_request_error`	`unknown model: <id>`	`model` 不是已发布的 id。请使用模型与定价页面中的 id。
`422`	`invalid_request_error`	`Failed to deserialize the JSON body into the target type…`	某个字段的 JSON 类型错误，或缺少 `messages`。
`429`	`rate_limit_error`	`Quota exceeded. Upgrade your plan at shannon-ai.com/plan`	该请求的输出预算超出了你的余额。

错误处理

接下来去哪里

模型与定价 — 选择模型：id、上下文窗口和价格。
Chat Completions — 你所调用端点的每个请求字段、回复字段和流事件。
流式 — 流的帧、保活行，以及流中的错误。
函数调用 — 让模型调用你的函数。
限制与余额 — 请求会预留和花费什么，以及你可以发送多少请求。
API 演练场 — 用你的密钥在浏览器中试用请求。