چټک پیل

لومړی غوښتنه وکړئ: کیلي ترلاسه کړئ، یو پیغام ولیږئ او ځواب ولولئ. API د OpenAI او Anthropic بڼې خبرې کوي، نو هغه SDK چې تاسو لا دمخه کاروئ وروسته له base URL او کیلي بدلولو کار کوي.

1. خپله کیلي ترلاسه کړئ

هر حساب یوه API کیلي لري. ننوځئ، Keys & usage پرانیزئ او کاپي یې کړئ. کیلي په هر endpoint او هر ماډل کار کوي. کیلي او کارونه

2. خپل کلاینټ API ته په نښه کړئ

ټول endpoints د یو base URL لاندې دي. OpenAI SDK یې د پای کې /v1 سره اخلي؛ Anthropic SDK یې پرته له هغه اخلي، ځکه چې /v1/messages پخپله زیاتوي.

کلاینټ	Base URL
OpenAI SDKs او د OpenAI سره مطابق کلاینټونه	`https://api.shannon-ai.com/v1`
Anthropic SDKs	`https://api.shannon-ai.com`

درې endpoints متن جوړوي. دوی همدا ماډلونو ته رسیږي؛ هغه غوره کړئ چې بڼه یې ستاسو کوډ لا دمخه کاروي.

اینډپوائنټ (Endpoint)	بڼه
`POST /v1/chat/completions`	OpenAI Chat Completions
`POST /v1/messages`	Anthropic Messages
`POST /v1/responses`	OpenAI Responses

3. لومړی غوښتنه ولیږئ

یو user message د Chat Completions endpoint کې shannon-3 ته ولیږئ. 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 ګانې د Models & pricing په پاڼه کې لیست شوي.
`messages`	`array`		تر اوسه ګفتګه: څیزونه د `role` او `content` سره. وروستی `user` message prompt دی. اړین.
`max_tokens`	`integer`	`4096`	د غوښتنې output بودجه، له 1 څخه تر 65,536 پورې. غوښتنه دا مقدار ستاسو له بیلانس ساتي او د هغه څه لپاره بیل کیږي چې ریښتیا یې کارولي.
`stream`	`boolean`	`false`	`true` ځواب ټوټه ټوټه لیږي پداسې حال کې چې لیکل کیږي.

د غوښتنې بدنه JSON ده او header Content-Type: application/json ته اړتیا لري. د ساحو بشپړ لیست د endpoint په پاڼه کې دی. Chat Completions

ځواب

هغه call چې 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 چې ځواب یې ورکړ، هم کله چې تاسو alias یا بله هجا لیږلې وي.
`choices`	`array`	تل یوه داخله، د `index` 0 سره.
`choices[0].message.role`	`string`	تل `assistant`.
`choices[0].message.content`	`string \| null`	ځواب. کولی شي `null` وي کله چې ځواب `tool_calls` لري.
`choices[0].message.reasoning_content`	`string \| null`	د ماډل reasoning مخکې له ځواب، یا `null` کله چې هیڅ نه وي.
`choices[0].message.tool_calls`	`array`	یوازې هغه وخت شتون لري کله چې ماډل له هغو tools څخه یو وغواړي چې تاسو اعلان کړي.
`choices[0].finish_reason`	`string`	`stop` د ځواب لپاره، `tool_calls` کله چې ماډل tool غواړي.
`usage.prompt_tokens`	`integer`	هغه ټوکنونه چې ماډل د دې ځواب لپاره ولوستل. په `shannon-2-*` او د Shannon 3 کورنۍ کې دا کولی شي له هغه متن څخه ډیر وي چې تاسو لیږلی.
`usage.completion_tokens`	`integer`	هغه ټوکنونه چې ماډل ولیکل.
`usage.total_tokens`	`integer`	ټولیز. د Shannon ماډل لګښت له همدې شمیرې محاسبه کیږي.

usage د ټوکنونو شمیرې لري، نه پیسې. هغه څه چې call ستاسو له بیلانس واخیستل د هرې غوښتنې لپاره په Keys & usage کې ښودل کیږي؛ دا څنګه محاسبه کیږي په حدونه او بیلانس کې دی. حدونه او بیلانس
هر ځواب، تېروتنه او stream هم، header x-request-id لري. که ستاسو غوښتنه x-request-id header ولري، د هغه ارزښت بیرته راځي؛ نور ارزښت 12 هیکساډیسیمل توري دي. دا په خپلو logs کې وساتئ: دا همدا یوه غوښتنه نوموي.

همدا call د stream په توګه

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

د stream هر frame یوه کرښه ده چې په data: پیلیږي او د JSON څیز لري. یو frame، په څو کرښو کې چاپ شوی:

یو frame

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

Frames، په ترتیب	delta	finish_reason
پداسې حال کې چې ماډل reasoning کوي. صفر یا ډیر frames.	`{"reasoning_content": "…"}`	`null`
ځواب، ټوټه ټوټه. صفر یا ډیر frames.	`{"content": "…"}`	`null`
وروستی JSON frame. دا `usage` هم لري؛ تاسو اړتیا نه لرئ چې غوښتنه یې وکړئ.	`{}`	`"stop"`
د stream پای: کرښه `data: [DONE]`.

ځواب حالت 200 او content-type: text/event-stream لري. هر frame یوه کرښه data: <json> ده چې ورپسې خالي کرښه راځي.
کرښه : ping هر 15 ثانیې وروسته رارسیږي. دا تبصره ده چې اړیکه پرانیستې ساتي؛ SSE کلاینټونه یې پریږدي.
ناکامي وروسته له دې چې stream پرانیستل شو د frame data: {"error": {…}} په توګه رارسیږي. حالت 200 پاتې کیږي، نو frames وګورئ.

جریان

که call ناکام شي

تېروتنه د JSON څیز دی چې error لري چې type او message سره. دا هغه ځوابونه دي چې لومړی call ډیری وخت ورسره مخ کیږي.

حالت	ډول	پیغام	څه معنی لري
`401`	`authentication_error`	`Missing authentication`	هیڅ کیلي API ته نه ده رسیدلې. `Authorization: Bearer` ولیږئ چې ورپسې ستاسو کیلي وي.
`401`	`authentication_error`	`Invalid API key`	کیلي د حساب اوسنۍ کیلي نه ده. له Keys & usage یې بیا کاپي کړئ.
`400`	`invalid_request_error`	`unknown model: <id>`	`model` خپور شوی id نه دی. د Models & pricing 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`	د غوښتنې output بودجه ستاسو په بیلانس کې ځای نه کیږي.

د تېروتنې اداره کول

بیا چیرته لاړ شو

ماډلونه او بیې — ماډل غوره کړئ: id ګانې، context windows او نرخونه.
Chat Completions — هره د غوښتنې ساحه، د ځواب ساحه او د stream رخداد د هغه endpoint چې تاسو غوښتی.
جریان — د stream frames، keep-alive کرښې او د stream دننه تېروتنې.
فنکشن زنګ وهل — ماډل ته اجازه ورکړئ چې ستاسو functions وغواړي.
حدونه او بیلانس — غوښتنه څه ساتي او څومره لګښت لري، او تاسو څومره غوښتنې لیږلی شئ.
د API لوبې ډګر — غوښتنې په براوزر کې د خپلې کیلي سره وازمایئ.