Mwanzo wa Haraka

Fanya ombi la kwanza: pata key yako, tuma ujumbe mmoja na usome jibu. API inatumia umbizo la OpenAI na Anthropic, kwa hiyo SDK unayotumia tayari inafanya kazi baada ya kubadilisha base URL na key yake.

1. Pata key yako

Kila akaunti ina API key moja. Ingia, fungua Keys na matumizi na uinakili. Key inafanya kazi kwenye kila endpoint na kila model. Keys na matumizi

2. Elekeza client yako kwenye API

Endpoint zote ziko chini ya base URL moja. SDK ya OpenAI inaipokea na /v1 mwishoni; SDK ya Anthropic inaipokea bila, kwa sababu inaongeza /v1/messages yenyewe.

Client	Base URL
SDK za OpenAI na clients zinazooana na OpenAI	`https://api.shannon-ai.com/v1`
SDK za Anthropic	`https://api.shannon-ai.com`

Endpoint tatu zinazalisha maandishi. Zinafikia model zile zile; chagua ile ambayo umbizo lake code yako tayari inatumia.

Endpoint	Umbizo
`POST /v1/chat/completions`	OpenAI Chat Completions
`POST /v1/messages`	Anthropic Messages
`POST /v1/responses`	OpenAI Responses

3. Tuma ombi la kwanza

Tuma ujumbe mmoja wa user kwa shannon-3 kwenye endpoint ya Chat Completions. Badilisha YOUR_API_KEY na key yako.

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

Field	Aina	Chaguo-msingi	Maelezo
`model`	`string`		Id ya model inayojibu. Id zimeorodheshwa kwenye Model na bei.
`messages`	`array`		Mazungumzo hadi sasa: vitu vyenye `role` na `content`. Ujumbe wa mwisho wa `user` ndio prompt. Inahitajika.
`max_tokens`	`integer`	`4096`	Bajeti ya output ya ombi, kuanzia 1 hadi 65,536. Ombi hutenga kiasi hiki kutoka kwenye salio lako na hutozwa kwa kile lilichotumia kweli.
`stream`	`boolean`	`false`	`true` hutuma jibu kipande kwa kipande linapoandikwa.

Mwili wa ombi ni JSON na unahitaji header Content-Type: application/json. Orodha kamili ya fields iko kwenye ukurasa wa endpoint. Chat Completions

Jibu

Wito bila stream hurudisha kitu kimoja cha JSON jibu likikamilika. Maandishi na namba zilizo hapa chini ni mifano.

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

Field	Aina	Maelezo
`id`	`string`	`chatcmpl-` ikifuatiwa na herufi 32 za hexadecimal.
`object`	`string`	Daima `chat.completion`.
`created`	`integer`	Wakati wa jibu kwa sekunde za Unix.
`model`	`string`	Id iliyochapishwa ya model iliyojibu, hata ulipotuma alias au tahajia nyingine.
`choices`	`array`	Daima entry moja, yenye `index` 0.
`choices[0].message.role`	`string`	Daima `assistant`.
`choices[0].message.content`	`string \| null`	Jibu. Linaweza kuwa `null` wakati jibu linabeba `tool_calls`.
`choices[0].message.reasoning_content`	`string \| null`	Reasoning ya model kabla ya jibu lake, au `null` ikiwa hakuna.
`choices[0].message.tool_calls`	`array`	Ipo tu wakati model inaita mojawapo ya tools ulizotangaza.
`choices[0].finish_reason`	`string`	`stop` kwa jibu, `tool_calls` wakati model inaita tool.
`usage.prompt_tokens`	`integer`	Tokens ambazo model ilisoma kwa jibu hili. Kwenye `shannon-2-*` na familia ya Shannon 3 hii inaweza kuwa zaidi ya maandishi uliyotuma.
`usage.completion_tokens`	`integer`	Tokens ambazo model iliandika.
`usage.total_tokens`	`integer`	Jumla. Gharama ya model ya Shannon hukokotolewa kutoka kwenye namba hii.

usage ina hesabu za tokens, si pesa. Kile wito ulichukua kutoka kwenye salio lako kinaonyeshwa kwa kila ombi kwenye Keys na matumizi; jinsi kinavyokokotolewa kiko kwenye Mipaka na salio. Mipaka na salio
Kila jibu, pia kosa na stream, lina header ya x-request-id. Ombi lako likibeba header ya x-request-id, thamani yake inarudi; vinginevyo thamani ni herufi 12 za hexadecimal. Iweke kwenye logs zako: inataja ombi hili moja.

Wito ule ule kama stream

Weka stream kuwa true ili kusoma jibu linapoandikwa. Kila kitu kingine kwenye ombi kinabaki vile vile.

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

Kila frame ya stream ni mstari mmoja unaoanza na data: na kushikilia kitu cha JSON. Frame moja, iliyochapishwa kwenye mistari kadhaa:

Frame moja

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

Frames, kwa mpangilio	delta	finish_reason
Wakati model inafikiri. Frames sifuri au zaidi.	`{"reasoning_content": "…"}`	`null`
Jibu, kipande kwa kipande. Frames sifuri au zaidi.	`{"content": "…"}`	`null`
Frame ya mwisho ya JSON. Pia hubeba `usage`; huhitaji kuiomba.	`{}`	`"stop"`
Mwisho wa stream: mstari `data: [DONE]`.

Jibu lina hali 200 na content-type: text/event-stream. Kila frame ni mstari data: <json> ukifuatiwa na mstari mtupu.
Mstari : ping hufika kila sekunde 15. Ni maoni yanayoweka muunganisho wazi; clients za SSE huuruka.
Hitilafu baada ya stream kufunguka hufika kama frame data: {"error": {…}}. Hali hubaki 200, kwa hiyo kagua frames.

Kutiririsha

Wito ukifeli

Kosa ni kitu cha JSON chenye error inayoshikilia type na message. Haya ndiyo majibu ambayo wito wa kwanza hukutana nayo mara nyingi zaidi.

Hali	Aina	Ujumbe	Inamaanisha nini
`401`	`authentication_error`	`Missing authentication`	Hakuna key iliyofika kwenye API. Tuma `Authorization: Bearer` ikifuatiwa na key yako.
`401`	`authentication_error`	`Invalid API key`	Key si key ya sasa ya akaunti. Inakili tena kutoka Keys na matumizi.
`400`	`invalid_request_error`	`unknown model: <id>`	`model` si id iliyochapishwa. Tumia id kutoka Model na bei.
`422`	`invalid_request_error`	`Failed to deserialize the JSON body into the target type…`	Field ina aina isiyo sahihi ya JSON, au `messages` haipo.
`429`	`rate_limit_error`	`Quota exceeded. Upgrade your plan at shannon-ai.com/plan`	Bajeti ya output ya ombi haitoshei kwenye salio lako.

Ushughulikiaji wa Makosa

Wapi pa kwenda baadaye

Model na bei — Chagua model: id, madirisha ya muktadha na bei.
Chat Completions — Kila field ya ombi, field ya jibu na tukio la stream la endpoint uliyoita.
Kutiririsha — Frames za stream, mistari ya keep-alive na makosa ndani ya stream.
Uitoaji wa kazi — Acha model iite functions zako.
Mipaka na salio — Ombi hutenga nini na hugharimu nini, na maombi mangapi unaweza kutuma.
Uwanja wa API — Jaribu maombi kwenye kivinjari ukitumia key yako.