Bidu Malajr

Agħmel l-ewwel talba: ikseb iċ-ċavetta tiegħek, ibgħat messaġġ wieħed u aqra t-tweġiba. L-API titkellem il-formats ta' OpenAI u Anthropic, għalhekk l-SDK li diġà tuża jaħdem wara li tbiddel il-base URL u ċ-ċavetta tiegħu.

1. Ikseb iċ-ċavetta tiegħek

Kull kont għandu ċavetta waħda tal-API. Idħol, iftaħ Keys & usage u ikkopjaha. Iċ-ċavetta taħdem fuq kull endpoint u kull mudell. Ċwievet u użu

2. Immira l-klijent tiegħek lejn l-API

L-endpoints kollha jinsabu taħt base URL waħda. SDK ta' OpenAI jieħodha b'/v1 fl-aħħar; SDK ta' Anthropic jieħodha mingħajru, għax iżid /v1/messages waħdu.

Klijent	Base URL
SDKs ta' OpenAI u klijenti kompatibbli ma' OpenAI	`https://api.shannon-ai.com/v1`
SDKs ta' Anthropic	`https://api.shannon-ai.com`

Tliet endpoints jipproduċu test. Jilħqu l-istess mudelli; agħżel dak li l-format tiegħu diġà juża l-kodiċi tiegħek.

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

3. Ibgħat l-ewwel talba

Ibgħat messaġġ user wieħed lil shannon-3 fuq l-endpoint Chat Completions. Ibdel YOUR_API_KEY biċ-ċavetta tiegħek.

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

Qasam	Tip	Default	Deskrizzjoni
`model`	`string`		L-id tal-mudell li jwieġeb. L-ids huma elenkati f'Models & pricing.
`messages`	`array`		Il-konversazzjoni s'issa: oġġetti b'`role` u `content`. L-aħħar messaġġ `user` huwa l-prompt. Meħtieġ.
`max_tokens`	`integer`	`4096`	Il-baġit tal-output tat-talba, minn 1 sa 65,536. It-talba tirriżerva dan l-ammont mill-bilanċ tiegħek u titħallas għal dak li użat tassew.
`stream`	`boolean`	`false`	`true` jibgħat it-tweġiba biċċa biċċa waqt li tinkiteb.

Il-body tat-talba huwa JSON u jeħtieġ l-header Content-Type: application/json. Il-lista kompluta tal-kampi tinsab fil-paġna tal-endpoint. Chat Completions

It-tweġiba

Sejħa mingħajr stream tagħti lura oġġett JSON wieħed meta t-tweġiba tkun kompluta. It-testi u n-numri hawn taħt huma eżempji.

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

Qasam	Tip	Deskrizzjoni
`id`	`string`	`chatcmpl-` segwit minn 32 karattru eżadeċimali.
`object`	`string`	Dejjem `chat.completion`.
`created`	`integer`	Il-ħin tat-tweġiba f'sekondi Unix.
`model`	`string`	L-id ippubblikat tal-mudell li wieġeb, anke meta bgħatt alias jew ikteb ieħor.
`choices`	`array`	Dejjem daħla waħda, b'`index` 0.
`choices[0].message.role`	`string`	Dejjem `assistant`.
`choices[0].message.content`	`string \| null`	It-tweġiba. Tista' tkun `null` meta t-tweġiba ġġorr `tool_calls`.
`choices[0].message.reasoning_content`	`string \| null`	Ir-raġunament tal-mudell qabel it-tweġiba tiegħu, jew `null` meta ma jkun hemm xejn.
`choices[0].message.tool_calls`	`array`	Preżenti biss meta l-mudell isejjaħ wieħed mit-tools li ddikjarajt.
`choices[0].finish_reason`	`string`	`stop` għal tweġiba, `tool_calls` meta l-mudell isejjaħ tool.
`usage.prompt_tokens`	`integer`	It-tokens li qara l-mudell għal din it-tweġiba. Fuq `shannon-2-*` u l-familja Shannon 3 dan jista' jkun aktar mit-test li bgħatt.
`usage.completion_tokens`	`integer`	It-tokens li kiteb il-mudell.
`usage.total_tokens`	`integer`	It-total. Il-ħlas ta' mudell Shannon jiġi kkalkulat minn dan in-numru.

usage iżomm l-għadd ta' tokens, mhux flus. X'ħadet is-sejħa mill-bilanċ tiegħek jintwera għal kull talba f'Keys & usage; kif jiġi kkalkulat jinsab f'Limiti u bilanċ. Limiti u bilanċ
Kull tweġiba, anke żball u stream, għandha l-header x-request-id. Jekk it-talba tiegħek iġġorr header x-request-id, il-valur tiegħu jiġi lura; inkella l-valur huwa 12-il karattru eżadeċimali. Żommu fil-logs tiegħek: jidentifika din it-talba waħedha.

L-istess sejħa bħala stream

Issettja stream għal true biex taqra t-tweġiba waqt li tinkiteb. Kull xi ieħor fit-talba jibqa' l-istess.

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

Kull frame tal-istream huwa linja waħda li tibda b'data: u żżomm oġġett JSON. Frame wieħed, stampat fuq diversi linji:

Frame wieħed

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

Frames, f'ordni	delta	finish_reason
Waqt li l-mudell jirraġuna. Zero frames jew aktar.	`{"reasoning_content": "…"}`	`null`
It-tweġiba, biċċa biċċa. Zero frames jew aktar.	`{"content": "…"}`	`null`
L-aħħar frame JSON. Iġorr ukoll `usage`; ma tridx titlobha.	`{}`	`"stop"`
It-tmiem tal-istream: il-linja `data: [DONE]`.

It-tweġiba għandha status 200 u content-type: text/event-stream. Kull frame huwa linja data: <json> segwita minn linja vojta.
Linja : ping tasal kull 15-il sekonda. Hija kummentarju li jżomm il-konnessjoni miftuħa; il-klijenti SSE jaqbżuha.
Falliment wara li jinfetaħ l-istream jasal bħala frame data: {"error": {…}}. L-istatus jibqa' 200, għalhekk iċċekkja l-frames.

Streaming

Jekk is-sejħa tfalli

Żball huwa oġġett JSON b'error li fih type u message. Dawn huma t-tweġibiet li l-ewwel sejħa tiltaqa' magħhom l-aktar spiss.

Status	Tip	Messaġġ	X'tfisser
`401`	`authentication_error`	`Missing authentication`	L-ebda ċavetta ma waslet sal-API. Ibgħat `Authorization: Bearer` segwit miċ-ċavetta tiegħek.
`401`	`authentication_error`	`Invalid API key`	Iċ-ċavetta mhijiex iċ-ċavetta kurrenti ta' kont. Ikkopjaha mill-ġdid minn Keys & usage.
`400`	`invalid_request_error`	`unknown model: <id>`	`model` mhuwiex id ippubblikat. Uża id minn Models & pricing.
`422`	`invalid_request_error`	`Failed to deserialize the JSON body into the target type…`	Qasam għandu tip JSON ħażin, jew `messages` huwa nieqes.
`429`	`rate_limit_error`	`Quota exceeded. Upgrade your plan at shannon-ai.com/plan`	Il-baġit tal-output tat-talba ma jidholx fil-bilanċ tiegħek.

Ġestjoni tal-iżbalji

Fejn tmur wara

Mudelli u prezzijiet — Agħżel mudell: ids, twieqi tal-kuntest u prezzijiet.
Chat Completions — Kull qasam tat-talba, qasam tat-tweġiba u avveniment tal-istream tal-endpoint li sejjaħt.
Streaming — Il-frames ta' stream, linji keep-alive u żbalji ġewwa stream.
Sejħiet ta' Funzjonijiet — Ħalli lill-mudell isejjaħ il-funzjonijiet tiegħek.
Limiti u bilanċ — X'tirriżerva u kemm tiswa talba, u kemm talbiet tista' tibgħat.
Playground tal-API — Ipprova talbiet fil-browser biċ-ċavetta tiegħek.