Destpêka zû

یەکەم داواکاری بکە: کلیلەکەت وەربگرە، یەک نامە بنێرە و وەڵامەکە بخوێنەرەوە. API فۆرماتەکانی OpenAI و Anthropic بەکاردەهێنێت، بۆیە ئەو SDK ـەی پێشتر بەکاری دەهێنیت دوای گۆڕینی base URL و کلیلەکەی کار دەکات.

1. کلیلەکەت وەربگرە

هەر هەژمارێک یەک کلیلی API ی هەیە. بچۆ ژوورەوە، Keys & usage بکەرەوە و کۆپی بکە. کلیلەکە لەسەر هەموو endpoint ێک و هەموو مۆدێلێک کار دەکات. Keys & usage

2. کلاینتەکەت بخە سەر API

هەموو endpoint ـەکان لەژێر یەک base URL دان. SDK ی OpenAI لەگەڵ /v1 لە کۆتاییدا وەریدەگرێت؛ SDK ی Anthropic بەبێ ئەوە، چونکە خۆی /v1/messages زیاد دەکات.

کلاینت	Base URL
SDK ـەکانی OpenAI و کلاینتە گونجاوەکانی OpenAI	`https://api.shannon-ai.com/v1`
SDK ـەکانی Anthropic	`https://api.shannon-ai.com`

سێ endpoint دەق دروست دەکەن. هەمان مۆدێلەکان بەکاردەهێنن؛ ئەوە هەڵبژێرە کە فۆرماتەکەی کۆدەکەت پێشتر بەکاری دەهێنێت.

Endpoint	فۆرمات
`POST /v1/chat/completions`	OpenAI Chat Completions
`POST /v1/messages`	Anthropic Messages
`POST /v1/responses`	OpenAI Responses

3. یەکەم داواکاری بنێرە

یەک نامەی user بنێرە بۆ shannon-3 لەسەر endpoint ی Chat Completions. 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` ئەو prompt ـەیە. پێویستە.
`max_tokens`	`integer`	`4096`	بودجەی output ی داواکارییەکە، لە 1 تا 65,536. داواکارییەکە ئەم بڕە لە باڵانسەکەت ڕادەگرێت و نرخی ئەوەی بەڕاستی بەکاری هێناوە دەگیرێت.
`stream`	`boolean`	`false`	`true` وەڵامەکە پارچە پارچە دەنێرێت لەکاتی نووسینیدا.

body ی داواکاری JSON ە و پێویستی بە header ی Content-Type: application/json ە. لیستی تەواوی بوارەکان لە لاپەڕەی endpoint دایە. 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`	وەڵامەکە. دەتوانێت `null` بێت کاتێک وەڵامەکە `tool_calls` هەڵدەگرێت.
`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`	ئەو تۆکنانەی مۆدێلەکە بۆ ئەم وەڵامە خوێندوونیەتییەوە. لەسەر `shannon-2-*` و بنەماڵەی Shannon 3 ئەمە دەتوانێت لەو دەقەی تۆ ناردووتە زیاتر بێت.
`usage.completion_tokens`	`integer`	ئەو تۆکنانەی مۆدێلەکە نووسیونی.
`usage.total_tokens`	`integer`	کۆی گشتی. نرخی مۆدێلێکی Shannon لەم ژمارەیە هەژمار دەکرێت.

usage ژمارەی تۆکن هەڵدەگرێت، نەک پارە. ئەوەی بانگکردنەکە لە باڵانسەکەت گرتووە بۆ هەر داواکارییەک لە Keys & usage نیشان دەدرێت؛ چۆنیەتی هەژمارکردنی لە Limits and balance دایە. سنوور و باڵانس
هەر وەڵامێک، هەڵە و stream یش، header ی x-request-id ی هەیە. ئەگەر داواکارییەکەت header ی x-request-id هەڵبگرێت، بەهاکەی دەگەڕێتەوە؛ ئەگینا بەهاکە 12 پیتی هەژدەیی ە. لە لۆگەکانتدا بیهێڵەرەوە: ناوی ئەم یەک داواکارییە دەبات.

هەمان بانگکردن وەک 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
  }'

هەر frame ێکی stream یەک هێڵە کە بە 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
    }
  ]
}

Frame ـەکان، بە ڕیز	delta	finish_reason
لەکاتی بیرکردنەوەی مۆدێلەکە. سفر یان زیاتر frame.	`{"reasoning_content": "…"}`	`null`
وەڵامەکە، پارچە پارچە. سفر یان زیاتر frame.	`{"content": "…"}`	`null`
دوایین frame ی JSON. `usage` یش هەڵدەگرێت؛ پێویست ناکات داوای بکەیت.	`{}`	`"stop"`
کۆتایی stream: هێڵی `data: [DONE]`.

وەڵامەکە status ی 200 و content-type: text/event-stream ی هەیە. هەر frame ێک هێڵێکی data: <json> ە و دوای ئەو هێڵێکی بەتاڵ.
هێڵی : ping هەر 15 چرکە جارێک دەگات. تێبینییەکە کە پەیوەندییەکە کراوە دەهێڵێتەوە؛ کلاینتەکانی SSE تێیدەپەڕێنن.
شکستێک دوای کرانەوەی stream وەک frame ی data: {"error": {…}} دەگات. status هەر 200 دەمێنێتەوە، بۆیە frame ـەکان بپشکنە.

Streaming

ئەگەر بانگکردنەکە شکست بخوات

هەڵە ئۆبجێکتێکی JSON ە بە error ێک کە type و message هەڵدەگرێت. ئەمانە ئەو وەڵامانەن کە یەکەم بانگکردن زۆرتر تووشیان دەبێت.

دۆخ	جۆر	پەیام	واتای چییە
`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 ێکی بڵاوکراو نییە. id ێک لە Models & pricing بەکاربهێنە.
`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 ی داواکارییەکە لەگەڵ باڵانسەکەت ناگونجێت.

Çewtî

دواتر بۆ کوێ بچیت

مۆدێل و نرخ — مۆدێلێک هەڵبژێرە: id، context window و نرخەکان.
Chat Completions — هەموو بوارێکی داواکاری، بوارێکی وەڵام و ڕووداوێکی stream ی ئەو endpoint ـەی بانگت کرد.
Streaming — Frame ـەکانی stream، هێڵەکانی keep-alive و هەڵەکانی ناو stream.
Bangkirina fonksiyonê — وا بکە مۆدێلەکە function ـەکانی تۆ بانگ بکات.
سنوور و باڵانس — داواکارییەک چی ڕادەگرێت و چی تێدەچێت، و چەند داواکاری دەتوانیت بنێریت.
API Playground — داواکاری لە وێبگەڕدا تاقی بکەرەوە بە کلیلەکەت.